@veriko-mx/sdk 0.4.6 → 0.4.8

package/CHANGELOG.md

@@ -7,6 +7,22 @@ versiones según [SemVer](https://semver.org/lang/es/).
 
 Sin cambios todavía.
 
+## [0.4.8] — 2026-09-27
+
+### Cambiado
+
+- `validations.validateOcr()` y `validations.enqueueOcr()` documentan el comprobante en PDF, de 1 a
+  3 páginas.
+- `validations.image()` acepta un comprobante en PDF y lo nombra con la extensión `.pdf`.
+
+## [0.4.7] — 2026-09-26
+
+### Añadido
+
+- El webhook de validación trae `data.attributes.banxico_confirmed` cuando
+  Banxico ya confirmó el pago: monto, fecha, clave de rastreo, ambos bancos y
+  la cuenta del beneficiario enmascarada.
+
 ## [0.4.6] — 2026-09-24
 
 ### Cambiado

package/README.md

@@ -128,7 +128,7 @@ conserva el suyo (`banxico_status`, `processing_time_ms`), porque es el tipo gen
 
 Cada llamada consume cuota del plan, y se descuenta al aceptar la petición.
 
-### Desde la imagen del comprobante
+### Desde el comprobante
 
 ```ts
 const validation = await client.validations.validateOcr({
@@ -137,11 +137,11 @@ const validation = await client.validations.validateOcr({
 });
 ```
 
-El SDK lee el archivo y lo codifica en base64. `imageUrl` recibe una imagen ya publicada en HTTPS, y
-si se envían `image` e `imageUrl`, la API sólo considera `image`. Formatos: JPEG, PNG o WebP, de
-hasta 12 MB.
+El SDK lee el archivo y lo codifica en base64. `imageUrl` recibe un comprobante ya publicado en
+HTTPS, y si se envían `image` e `imageUrl`, la API sólo considera `image`. Formatos: JPEG, PNG, WebP
+o PDF de 1 a 3 páginas, de hasta 12 MB.
 
-La imagen de una validación por OCR se descarga con `client.validations.image(id)`.
+El comprobante de una validación por OCR se descarga con `client.validations.image(id)`.
 
 ### Sin esperar al veredicto
 
@@ -370,6 +370,14 @@ para decidir el código de respuesta aparte. La comparación es en tiempo consta
 
 El receptor completo está en [`examples/express-webhook.mjs`](examples/express-webhook.mjs).
 
+### Lo que Banxico confirmó
+
+Cuando `banxico_status` es `valid`, o `returned` con CEP descargado, `evento.data.attributes`
+trae además `banxico_confirmed`: el monto, la fecha, la clave de rastreo, ambos bancos y la cuenta
+del beneficiario (enmascarada a los últimos 4 dígitos), tal como los confirmó Banxico. Compáralo
+contra el pedido antes de liberar la mercancía: la imagen de un comprobante puede mostrar un monto
+distinto al que Banxico confirmó.
+
 ### Las cuatro cabeceras de una entrega
 
 | cabecera               | contenido                                             |

package/dist/cjs/client.d.ts

@@ -7,7 +7,7 @@ export declare const DEFAULT_TIMEOUT_MS = 30000;
 export declare const API_KEY_ENV_VAR = "VERIKO_API_KEY";
 export declare const BASE_URL_ENV_VAR = "VERIKO_BASE_URL";
 /** La versión que viaja en el `User-Agent`. `test/client.test.ts` la compara con `package.json`. */
-export declare const VERSION = "0.4.6";
+export declare const VERSION = "0.4.8";
 export interface VerikoOptions {
     /** La clave de API. Por omisión, `VERIKO_API_KEY`. */
     apiKey?: string;

package/dist/cjs/client.js

@@ -9,7 +9,7 @@ exports.DEFAULT_TIMEOUT_MS = 30_000;
 exports.API_KEY_ENV_VAR = 'VERIKO_API_KEY';
 exports.BASE_URL_ENV_VAR = 'VERIKO_BASE_URL';
 /** La versión que viaja en el `User-Agent`. `test/client.test.ts` la compara con `package.json`. */
-exports.VERSION = '0.4.6';
+exports.VERSION = '0.4.8';
 /**
  * Cliente de la API de Veriko.
  *

package/dist/cjs/generated/openapi.d.ts

@@ -117,9 +117,19 @@ export interface paths {
         put?: never;
         /**
          * Validar una transferencia SPEI (OCR)
-         * @description Valida una transferencia SPEI a partir de la imagen de su comprobante. Extrae mediante reconocimiento óptico (OCR) los datos de la imagen y los valida en **Banxico** para obtener el CEP de la transacción.
+         * @description Valida una transferencia SPEI a partir de su comprobante, en imagen o en PDF. Extrae mediante reconocimiento óptico (OCR) los datos del comprobante y los valida en **Banxico** para obtener el CEP de la transacción.
          *
-         *     La imagen se envía como `image` o `image_url`. Si es enviada mediante una URL, el host destino deberá contar con protocolo seguro (SSL/HTTPS).
+         *     El comprobante se envía como `image` o `image_url`. Si es enviado mediante una URL, el host destino deberá contar con protocolo seguro (SSL/HTTPS).
+         *
+         *     {% callout type="info" %}
+         *     **Comprobante en PDF:**\
+         *     Se acepta un PDF de 1 a 3 páginas, con el mismo máximo de `12 MB` que una imagen.
+         *     Se rechaza si está cifrado, si se modificó después de emitirse o si trae contenido activo u oculto.\
+         *     Si el PDF es el CEP de Banxico, sus datos se leen de su texto sin OCR y `banxico_result._cep_upload` indica
+         *     si su sello y su cadena original coinciden con los del CEP oficial. El veredicto no cambia por esa comparación.\
+         *     Un PDF con más de un comprobante se rechaza con `pdf_multiple_receipts`.
+         *
+         *     {% /callout %}
          *
          *     {% callout type="info" %}
          *     El campo `cuenta_beneficiaria` permite enviar explícitamente la cuenta receptora de la transferencia, enviarlo es especialmente útil cuando la imagen no lleva este dato o lo lleva incompleto.\
@@ -137,7 +147,7 @@ export interface paths {
          *
          *     {% callout type="info" %}
          *     **Modo asíncrono:**\
-         *     Enviando `?async=1` en la URL, la imagen se comprueba antes de aceptar el trabajo y la respuesta es un estado HTTP `202` inmediato con el ID de la validación en el cuerpo.\
+         *     Enviando `?async=1` en la URL, el comprobante se comprueba antes de aceptar el trabajo y la respuesta es un estado HTTP `202` inmediato con el ID de la validación en el cuerpo.\
          *     \
          *     El veredicto se recoge sondeando `GET /v1/validations/{id}` hasta un estado terminal, como describe {% concept slug="async-validations" %}las operaciones asíncronas{% /concept %}.
          *
@@ -153,10 +163,12 @@ export interface paths {
          *
          *     {% callout type="warning" %}
          *     **Políticas de cobro (cuota):**\
-         *     — Modo síncrono: Se descuenta la validación de la cuota al aceptar la petición, antes de comprobar la imagen. Es decir, una imagen inválida consume una validación.\
-         *     — Modo asíncrono: La imagen se comprueba primero, así que una imagen inválida no consume nada.\
+         *     — Modo síncrono: Se descuenta la validación de la cuota al aceptar la petición, antes de comprobar el archivo. Es decir, un archivo inválido consume una validación.\
+         *     — Modo asíncrono: El archivo se comprueba primero, así que un archivo inválido no consume nada.\
          *     \
-         *     La cuota no se devuelve en ningún caso. Los reintentos automáticos posteriores no consumen una validación adicional, y el cómputo está en {% concept slug="quotas-and-plans" %}cuotas y planes{% /concept %}.
+         *     Un CEP en PDF que se lee sin OCR cuenta como una validación, igual que uno leído por OCR.\
+         *     \
+         *     La cuota sólo se devuelve cuando la validación termina en `error` por un fallo de la plataforma. Los reintentos automáticos posteriores no consumen una validación adicional, y el cómputo está en {% concept slug="quotas-and-plans" %}cuotas y planes{% /concept %}.
          *
          *     {% /callout %}
          */
@@ -343,7 +355,11 @@ export interface paths {
         };
         /**
          * Obtener la imagen del comprobante
-         * @description Devuelve la imagen conservada de una validación por OCR, con disposición `inline` y caché privada.
+         * @description Devuelve el comprobante conservado de una validación por OCR, con caché privada:
+         *
+         *     - Imagen: se entrega con disposición `inline`.
+         *     - PDF: se entrega siempre como adjunto (`attachment`) y con `Content-Security-Policy: sandbox`,
+         *       para que un navegador no lo abra dentro del propio origen.
          *
          *     Si la validación no tiene imagen disponible, responde con un estado HTTP `404` (con `image_not_available` en el cuerpo).
          */
@@ -642,6 +658,7 @@ export interface paths {
         /**
          * Iniciar importación masiva de beneficiarios
          * @description Sube un archivo (CSV, XLS, XLSX, TXT o PDF) de hasta 20 MB y abre con él un trabajo de importación.
+         *     Las hojas XLSX/XLS admiten hasta 10 000 filas y 64 columnas. Las fórmulas XLSX se leen como texto, sin ejecutarlas. Los PDF admiten hasta 50 páginas y limitan a 8 MiB la descompresión de cada flujo.
          *
          *     El modo de lectura decide cuánto trabajo hace el archivo y cuánto el servidor:
          *
@@ -2338,11 +2355,16 @@ export interface components {
                  */
                 etag_version?: number | null;
                 /**
-                 * @description Referencia relativa de la imagen del comprobante (solo si `validation_type` es del tipo `ocr`).
+                 * @description Referencia relativa del comprobante, imagen o PDF (solo si `validation_type` es del tipo `ocr`).
                  * @example ocr/2026/04/a1b2c3d4.jpg
                  */
                 image_path?: string | null;
-                /** @description Campos extraídos mediante OCR (solo si `validation_type` es del tipo `ocr`). */
+                /**
+                 * @description Campos extraídos del comprobante (solo si `validation_type` es del tipo `ocr`).
+                 *
+                 *     `extraction_source` vale `cep_pdf` cuando el comprobante era el CEP de Banxico en PDF y sus datos se leyeron
+                 *     de su texto, sin OCR. `comprobantes_detectados` es el número de comprobantes que se encontraron en un PDF.
+                 */
                 ocr_result?: {
                     [key: string]: unknown;
                 } | null;
@@ -2361,13 +2383,81 @@ export interface components {
                 /** @description Indica si el número de tarjeta está enmascarado en el comprobante cargado (solo si `validation_type` es del tipo `ocr`). */
                 is_masked?: boolean | null;
                 /**
-                 * @description Datos devueltos por Banxico.
+                 * @description Datos devueltos por Banxico. Las propiedades tipadas abajo son las 20 que declara el esquema oficial del complemento SPEI.
                  *
                  *     `_ocr_correction` conserva los campos corregidos, su lectura original (`requested`), el valor consultado (`used`) y la confirmación (`confirmed_by`). `status_query` indica una hipótesis confirmada por la consulta de estado; `cep` indica que también se obtuvo el comprobante. La consulta de estado por sí sola no verifica una transferencia.
+                 *
+                 *     `_cep_upload` aparece cuando el comprobante subido era el CEP en PDF y Banxico confirmó el pago.
+                 *     `authenticated` es `true` cuando su sello y su cadena original coinciden con los del CEP oficial;
+                 *     con `false`, `differing_fields` lista los campos que difieren y `normalization_warnings` lo avisa.
+                 *     El veredicto sigue siendo el de Banxico.
                  */
-                banxico_result?: {
+                banxico_result?: ({
+                    /**
+                     * @description Fecha de la operación tal como la reporta el CEP de Banxico (`AAAA-MM-DD`).
+                     * @example 2025-03-15
+                     */
+                    operationDate?: string;
+                    /**
+                     * @description Hora de la operación tal como la reporta el CEP de Banxico (`HH:MM:SS`).
+                     * @example 14:22:10
+                     */
+                    processingTime?: string;
+                    /** @description Clave de la operación dentro del sistema SPEI (`ClaveSPEI` del CEP). Distinta de la clave de rastreo. */
+                    speiKey?: string;
+                    /**
+                     * @description Clave de rastreo de la operación SPEI — la misma que se envía en la petición de validación.
+                     * @example MBAN01002503151422ABCDEF
+                     */
+                    trackingKey?: string;
+                    /** @description Sello digital del CEP (`sello`) — la firma que Banxico calcula sobre la operación. */
+                    digitalSignature?: string;
+                    /** @description Número del certificado digital que Banxico usó para sellar el CEP. */
+                    certificateNumber?: string;
+                    /** @description Cadena original de la operación (`cadenaCDA`): los 47 campos que la institución envió a Banxico, separados por `|`, incluidas ambas fechas (operación y captura) y el tipo de pago. Permite auditar el CEP sin volver a pedirlo. */
+                    cadenaCda?: string;
+                    /**
+                     * @description Banco emisor de la operación, tal como lo identifica el CEP.
+                     * @example BBVA
+                     */
+                    senderBank?: string;
+                    /** @description Nombre del ordenante de la operación, tal como lo reporta el CEP. */
+                    senderName?: string;
+                    /** @description Tipo de cuenta del ordenante (por ejemplo, CLABE o tarjeta), tal como lo reporta el CEP. */
+                    senderAccountType?: string;
+                    /** @description Cuenta del ordenante, tal como la reporta el CEP, sin enmascarar en este recurso (consulta privada, propia del dueño de la validación). */
+                    senderAccount?: string;
+                    /** @description RFC del ordenante, tal como lo reporta el CEP. */
+                    senderRfc?: string;
+                    /**
+                     * @description Banco receptor de la operación, tal como lo identifica el CEP.
+                     * @example STP
+                     */
+                    receiverBank?: string;
+                    /** @description Nombre del beneficiario de la operación, tal como lo reporta el CEP. */
+                    beneficiaryName?: string;
+                    /** @description Tipo de cuenta del beneficiario (por ejemplo, CLABE o tarjeta), tal como lo reporta el CEP. */
+                    beneficiaryAccountType?: string;
+                    /** @description Cuenta del beneficiario, tal como la reporta el CEP, sin enmascarar en este recurso (consulta privada, propia del dueño de la validación). Los webhooks salientes sí la enmascaran a los últimos 4 dígitos en `banxico_confirmed.beneficiaryAccount` (ver la guía de webhooks). */
+                    beneficiaryAccount?: string;
+                    /** @description RFC del beneficiario, tal como lo reporta el CEP. */
+                    beneficiaryRfc?: string;
+                    /**
+                     * Format: float
+                     * @description Monto de la operación que Banxico confirmó por el CEP, en pesos.
+                     * @example 1500
+                     */
+                    amount?: number;
+                    /**
+                     * Format: float
+                     * @description IVA de la operación reportado por el CEP, en pesos.
+                     */
+                    iva?: number;
+                    /** @description Concepto de pago de la operación, tal como lo reporta el CEP. */
+                    paymentConcept?: string;
+                } & {
                     [key: string]: unknown;
-                } | null;
+                }) | null;
                 /**
                  * @description Mensaje legible del error terminal (si aplica).
                  * @example Banxico no respondió tras tres intentos.
@@ -2466,17 +2556,17 @@ export interface components {
                 playground?: boolean;
             };
         };
-        /** @description Cuerpo de `POST /v1/validate-ocr` con la imagen en `image` o `image_url`; exige al menos uno de ambos campos. */
+        /** @description Cuerpo de `POST /v1/validate-ocr` con el comprobante en `image` o `image_url`; exige al menos uno de ambos campos. */
         OcrValidationRequest: {
             /**
              * Format: byte
-             * @description Imagen del comprobante codificada en base64. Si también se proporciona `image_url`, solo se considera `image`. Formatos aceptados: JPEG, PNG o WebP. Tamaño máximo: `12 MB`. Dimensiones máximas: `12000px` por lado.
+             * @description Comprobante codificado en base64, en imagen o en PDF. Si también se proporciona `image_url`, solo se considera `image`. Formatos aceptados: JPEG, PNG, WebP o PDF de 1 a 3 páginas. Tamaño máximo: `12 MB`. Dimensiones máximas de una imagen: `12000px` por lado. Admite el prefijo `data:image/...;base64,` o `data:application/pdf;base64,`.
              * @example iVBORw0KGgoAAAANSUhEUgAAAAEAAAABCAYAAAAfFcSJAAAADUlEQVR42mP8z8BQDwAEhQGAhKmMIQAAAABJRU5ErkJggg==
              */
             image?: string;
             /**
              * Format: uri
-             * @description URL pública (HTTPS) de la imagen del comprobante. La imagen sigue los mismos límites de formato y tamaño que `image` (JPEG, PNG o WebP. Con un máximo de 12 MB).
+             * @description URL pública (HTTPS) del comprobante. Sigue los mismos límites de formato y tamaño que `image`: JPEG, PNG, WebP o PDF de 1 a 3 páginas, con un máximo de `12 MB`.
              * @example https://storage.example.com/receipts/comprobante-2025-03.jpg
              */
             image_url?: string;
@@ -2540,6 +2630,8 @@ export interface components {
             attributes: {
                 /** @description Nombre del banco de la contraparte. Prioriza `receptor_name` o `emisor_name` guardado; si falta, intenta resolver el código de receptor o emisor. Si tampoco puede resolverlo, devuelve ese código o `Banco no identificado`. */
                 bank_name?: string;
+                /** @description Clave Banxico canónica (3-5 dígitos) del banco de la contraparte, resuelta por la autoridad del dominio. `null` cuando el banco no pudo resolverse. Es aditiva respecto de `bank_name`: sirve para resolver recursos/avatares por clave, nunca por el nombre visible. */
+                bank_code?: string | null;
                 /** @description Etiqueta del beneficiario receptor registrado (si existe). */
                 beneficiary_label?: string | null;
                 /** @description Importe de la transferencia (en pesos mexicanos — MXN). */
@@ -5305,7 +5397,7 @@ export interface operations {
             401: components["responses"]["Unauthorized"];
             409: components["responses"]["IdempotencyKeyInProgress"];
             413: components["responses"]["PayloadTooLarge"];
-            /** @description La imagen o los datos de la petición no son válidos. Códigos posibles: `image_or_image_url_required`, `invalid_image`, `invalid_image_format`, `image_too_large`, `invalid_url`, `invalid_url_scheme`, `url_ssrf_blocked`, `invalid_clabe_checksum`. También puede devolver: `image_too_small`, `image_mime_mismatch`, `image_dimensions_too_large`, `image_decompression_bomb`, `image_polyglot_detected`, `image_url_unreachable`, `image_url_too_large`, `image_url_too_many_redirects`. En modo asíncrono, un fallo genérico de la imagen se reporta como `image_invalid`. Reutilizar `Idempotency-Key` con un cuerpo distinto produce `idempotency_key_reused`. */
+            /** @description La imagen o los datos de la petición no son válidos. Códigos posibles: `image_or_image_url_required`, `invalid_image`, `invalid_image_format`, `image_too_large`, `invalid_url`, `invalid_url_scheme`, `url_ssrf_blocked`, `invalid_clabe_checksum`. También puede devolver: `image_too_small`, `image_mime_mismatch`, `image_dimensions_too_large`, `image_decompression_bomb`, `image_polyglot_detected`, `image_url_unreachable`, `image_url_too_large`, `image_url_too_many_redirects`. Con un PDF: `pdf_invalid_structure`, `pdf_encrypted`, `pdf_active_content`, `pdf_hidden_content`, `pdf_modified_after_issue`, `pdf_too_many_pages`, `pdf_unsupported_image`, `pdf_text_layer_too_large` y `pdf_multiple_receipts`. En modo asíncrono, un fallo genérico de la imagen se reporta como `image_invalid`. Reutilizar `Idempotency-Key` con un cuerpo distinto produce `idempotency_key_reused`. */
             422: {
                 headers: {
                     [name: string]: unknown;
@@ -5880,15 +5972,17 @@ export interface operations {
         };
         requestBody?: never;
         responses: {
-            /** @description Imagen del comprobante. `Content-Type` indica `image/png`, `image/jpeg` o `image/webp` según el formato; cualquier otro contenido se entrega como `application/octet-stream`. */
+            /** @description Comprobante. `Content-Type` indica `image/png`, `image/jpeg`, `image/webp` o `application/pdf` según el formato; cualquier otro contenido se entrega como `application/octet-stream`. */
             200: {
                 headers: {
-                    /** @description Presentación en línea con un nombre derivado del identificador de la validación y la extensión del formato. */
+                    /** @description `inline` para una imagen y `attachment` para un PDF, con un nombre derivado del identificador de la validación y la extensión del formato. */
                     "Content-Disposition"?: string;
                     /** @description Permite un caché privado durante 1 hora. */
                     "Cache-Control"?: string;
                     /** @description Restringe el uso del recurso al mismo origen. */
                     "Cross-Origin-Resource-Policy"?: string;
+                    /** @description Sólo con un PDF. `sandbox` impide ejecutar scripts y trata el documento como de otro origen si un visor lo abre. */
+                    "Content-Security-Policy"?: string;
                     /** @description Impide que el navegador deduzca un tipo de contenido distinto. */
                     "X-Content-Type-Options"?: string;
                     [name: string]: unknown;
@@ -5897,6 +5991,7 @@ export interface operations {
                     "image/png": string;
                     "image/jpeg": string;
                     "image/webp": string;
+                    "application/pdf": string;
                     "application/octet-stream": string;
                 };
             };