@veriko-mx/sdk 0.4.9 → 0.4.11

package/CHANGELOG.md

@@ -7,6 +7,40 @@ versiones según [SemVer](https://semver.org/lang/es/).
 
 Sin cambios todavía.
 
+## [0.4.11] — 2026-10-01
+
+### Añadido
+
+- `clientRef` en `validateTransfer()`, `validations.validate()`, `validations.validateOcr()`,
+  `validations.enqueue()` y `validations.enqueueOcr()`: una referencia propia de 1 a 64 caracteres
+  que vuelve en `attributes.client_ref`.
+- El filtro `clientRef`, de coincidencia exacta, en `validations.list()`, `validations.iter()`,
+  `validations.stats()` y `validations.export()`.
+- Los tipos de `Validation` añaden `client_ref`, `duplicate_of` y `account_conflict`.
+- `verifyWebhookTimestamped()` comprueba la cabecera `X-Webhook-Signature-Timestamped`
+  (`t=<segundos>,v1=<hex>`): compara en tiempo constante el HMAC-SHA256 de `<t>.<cuerpo>` con cada
+  `v1` y rechaza la entrega cuando `t` se aleja del reloj más de `toleranceSeconds`, 300 por
+  omisión. `timestampedSignatureFromHeaders()` encuentra la cabecera en cualquiera de sus grafías.
+  `verifyWebhook()` no cambia.
+- `parseWebhook()` entrega el `client_ref` en `evento.data.attributes` cuando el webhook de
+  validación lo trae.
+
+### Cambiado
+
+- `cuentaBeneficiaria` es obligatoria en `validateTransfer()`, `validations.validate()` y
+  `validations.enqueue()`. Sin ella, el SDK lanza `InvalidRequestError` con `cuenta_required` y no
+  llama a la API.
+
+## [0.4.10] — 2026-09-29
+
+### Cambiado
+
+- Las descripciones de los tipos documentan los códigos por campo con que el `422` de la
+  validación rechaza una petición cuyos datos se contradicen, antes de consultar a Banxico:
+  `clabe_receptor_mismatch`, `tarjeta_receptor_mismatch` y `clave_longitud_invalida`. Llegan en
+  `errors[].code` de `InvalidRequestError`. Ningún rechazo `preflight_failed` de esa ruta consume
+  cuota, sea por datos que se contradicen o por un campo mal formado.
+
 ## [0.4.9] — 2026-09-28
 
 ### Añadido

package/README.md

@@ -99,9 +99,10 @@ const client = new Veriko({ apiKey: 'veriko_tu_clave_aqui' });
 
 ## Validar una transferencia
 
-La operación exige la fecha de envío, el importe y **la clave de rastreo o la referencia
-numérica**. Enviar las dos precisa la búsqueda. El banco emisor, el receptor y la cuenta
-beneficiaria son opcionales y mejoran la identificación.
+La operación exige la fecha de envío, el importe, la cuenta beneficiaria y **la clave de rastreo
+o la referencia numérica**. Enviar las dos precisa la búsqueda. El banco emisor y el receptor son
+opcionales y mejoran la identificación. La API rechaza con `422` (`preflight_failed`) una petición
+sin `cuenta_beneficiaria`: no la busca entre los beneficiarios guardados.
 
 ```ts
 import { Veriko } from '@veriko-mx/sdk';
@@ -170,6 +171,38 @@ El tiempo de espera se fija con `timeoutMs` (cinco minutos por omisión) y la pa
 
 La alternativa a sondear es suscribirse al webhook `validation.completed`.
 
+### Referencia propia
+
+`clientRef` es una referencia propia de 1 a 64 caracteres, sin saltos de línea ni emoji. Sirve para
+relacionar la validación con un pedido propio. No debe contener datos personales.
+
+```ts
+const validation = await client.validateTransfer({
+  fecha: '2025-03-15',
+  monto: 15000.5,
+  claveRastreo: 'MXBA20250315001234',
+  cuentaBeneficiaria: '012180004412345678',
+  clientRef: 'orden-4812',
+});
+console.log(validation.attributes.client_ref); // orden-4812
+
+const page = await client.validations.list({ clientRef: 'orden-4812' });
+```
+
+`validateOcr()`, `enqueue()` y `enqueueOcr()` también la aceptan. Vuelve en
+`attributes.client_ref`, en los listados y en los webhooks de validación, y `list()`, `stats()` y
+`export()` la usan como filtro de coincidencia exacta. En un webhook, `parseWebhook()` la entrega en
+`evento.data.attributes.client_ref`. La API rechaza con `422` (`invalid_client_ref`) una referencia
+que no cumple las reglas.
+
+### Duplicado y conflicto de cuenta
+
+`attributes.duplicate_of` trae el `id` y el `created_at` de una validación previa `valid`, de la
+misma cuenta y con la misma clave de rastreo. `attributes.account_conflict` trae los últimos 4
+dígitos de la cuenta enviada (`sent_last4`) y de la que muestra la imagen (`read_last4`) en una
+validación por OCR. Ninguno cambia el veredicto, y los dos están ausentes cuando la API no los
+informa.
+
 ### Listar y recorrer el historial
 
 ```ts
@@ -186,7 +219,7 @@ for await (const item of client.validations.iter({ from: '2025-03-01', to: '2025
 `totalPages` y `hasNext`.
 
 Los filtros (`status`, `type`, `from`, `to`, `search`, `playground`, `withDeleted`, `batchId`,
-`bank`, `amountMin`, `amountMax` y `retryState`) van en `camelCase`. `status` acepta un estado o una
+`bank`, `amountMin`, `amountMax`, `clientRef` y `retryState`) van en `camelCase`. `status` acepta un estado o una
 lista, y `withDeleted: true` devuelve sólo las validaciones retiradas, mientras que `false` devuelve
 sólo las activas.
 
@@ -378,17 +411,49 @@ del beneficiario (enmascarada a los últimos 4 dígitos), tal como los confirmó
 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
+### Las cinco cabeceras de una entrega
 
-| cabecera               | contenido                                             |
-| ---------------------- | ----------------------------------------------------- |
-| `X-Webhook-Signature`  | `sha256=` seguido del HMAC en hexadecimal             |
-| `X-Veriko-Event`       | Tipo de evento, por ejemplo `validation.completed`    |
-| `X-Veriko-Delivery-Id` | Identificador de la entrega, estable entre reintentos |
-| `X-Veriko-Timestamp`   | Momento del envío, ISO 8601 con sufijo `Z`            |
+| cabecera                          | contenido                                                                |
+| --------------------------------- | ------------------------------------------------------------------------ |
+| `X-Webhook-Signature`             | `sha256=` seguido del HMAC en hexadecimal                                |
+| `X-Webhook-Signature-Timestamped` | `t=<segundos>,v1=<hex>`: firma de `<t>.<cuerpo>` con la hora del intento |
+| `X-Veriko-Event`                  | Tipo de evento, por ejemplo `validation.completed`                       |
+| `X-Veriko-Delivery-Id`            | Identificador de la entrega, estable entre reintentos                    |
+| `X-Veriko-Timestamp`              | Momento del envío, ISO 8601 con sufijo `Z`                               |
 
 El `Delivery-Id` es el valor que permite descartar entregas repetidas.
 
+### Firma con marca de tiempo
+
+`X-Webhook-Signature-Timestamped` firma la hora del intento junto con el cuerpo, de modo que el
+receptor puede descartar una entrega vieja que alguien vuelva a enviar. `X-Webhook-Signature` no
+cambia.
+
+```ts
+import { verifyWebhookTimestamped } from '@veriko-mx/sdk';
+
+if (
+  !verifyWebhookTimestamped(
+    request.body, // el cuerpo crudo
+    request.get('X-Webhook-Signature-Timestamped'),
+    SECRET,
+  )
+) {
+  return response.sendStatus(400);
+}
+```
+
+`verifyWebhookTimestamped(payload, header, secret, { toleranceSeconds, now })` devuelve `true` o
+`false`. Calcula el HMAC-SHA256 de `<t>.<cuerpo>`, lo compara en tiempo constante con cada `v1` de
+la cabecera y rechaza la entrega si `t` se aleja del reloj del receptor más de `toleranceSeconds`,
+300 por omisión. `now` fija la hora actual con un `Date`, para las pruebas.
+`timestampedSignatureFromHeaders(headers)` encuentra la cabecera en cualquiera de sus grafías.
+
+La ventana se aplica a `t`, la hora del intento, y no al campo `timestamp` del cuerpo, que es la hora
+del evento. Un reintento llega hasta unas 8,6 horas después del evento, pero lleva una `t` recién
+generada. Medir la ventana contra el `timestamp` del cuerpo rechazaría reintentos legítimos. La
+ventana no sustituye a la deduplicación: guarda el `Delivery-Id` al menos 24 horas.
+
 ## Reintentos
 
 Hay dos mecanismos distintos con el mismo nombre.

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.9";
+export declare const VERSION = "0.4.11";
 export interface VerikoOptions {
     /** La clave de API. Por omisión, `VERIKO_API_KEY`. */
     apiKey?: string;
@@ -95,8 +95,10 @@ export declare class Veriko {
      * Devuelve el veredicto en `attributes.status`: `valid`, `not_found`,
      * `cep_unavailable`, `returned` o `error`.
      *
-     * La operación exige `claveRastreo` o `referenciaNumerica`. Enviar las dos
-     * precisa la búsqueda. La fecha es la de envío, en `YYYY-MM-DD`.
+     * La operación exige `cuentaBeneficiaria`, y `claveRastreo` o
+     * `referenciaNumerica`. Enviar las dos últimas precisa la búsqueda. La fecha
+     * es la de envío, en `YYYY-MM-DD`. `clientRef` es una referencia propia que
+     * vuelve en la validación y en los webhooks.
      *
      * Un `not_found` inmediato no equivale a una transferencia inexistente: un
      * CEP tarda en publicarse. `retryPolicy` deja a la API consultando de nuevo y

package/dist/cjs/client.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"client.d.ts","sourceRoot":"","sources":["../../src/client.ts"],"names":[],"mappings":"AAAA,mEAAmE;AAEnE,OAAO,EAAiB,SAAS,EAAE,KAAK,WAAW,EAAE,MAAM,WAAW,CAAC;AACvE,OAAO,EACL,OAAO,EACP,aAAa,EACb,OAAO,EACP,OAAO,EACP,SAAS,EACT,OAAO,EACP,QAAQ,EACR,KAAK,EACL,KAAK,EACL,WAAW,EACX,QAAQ,EACT,MAAM,gBAAgB,CAAC;AACxB,OAAO,KAAK,EACV,WAAW,EACX,SAAS,EACT,oBAAoB,EACpB,sBAAsB,EACtB,UAAU,EACV,kBAAkB,EACnB,MAAM,YAAY,CAAC;AAEpB,eAAO,MAAM,gBAAgB,6BAA6B,CAAC;AAC3D,eAAO,MAAM,kBAAkB,QAAS,CAAC;AACzC,eAAO,MAAM,eAAe,mBAAmB,CAAC;AAChD,eAAO,MAAM,gBAAgB,oBAAoB,CAAC;AAElD,oGAAoG;AACpG,eAAO,MAAM,OAAO,UAAU,CAAC;AAE/B,MAAM,WAAW,aAAa;IAC5B,sDAAsD;IACtD,MAAM,CAAC,EAAE,MAAM,CAAC;IAChB,sEAAsE;IACtE,OAAO,CAAC,EAAE,MAAM,CAAC;IACjB,0CAA0C;IAC1C,SAAS,CAAC,EAAE,MAAM,CAAC;IACnB;;;OAGG;IACH,UAAU,CAAC,EAAE,MAAM,CAAC;IACpB,qDAAqD;IACrD,cAAc,CAAC,EAAE,MAAM,CAAC;IACxB,qEAAqE;IACrE,KAAK,CAAC,EAAE,OAAO,CAAC,WAAW,CAAC,CAAC;IAC7B,eAAe,CAAC,EAAE,MAAM,CAAC;IACzB,4EAA4E;IAC5E,SAAS,CAAC,EAAE,SAAS,CAAC;CACvB;AAED;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GAiCG;AACH,qBAAa,MAAM;IACjB,OAAO,CAAC,QAAQ,CAAC,SAAS,CAAY;IAEtC,kDAAkD;IAClD,QAAQ,CAAC,WAAW,EAAE,WAAW,CAAC;IAClC,uDAAuD;IACvD,QAAQ,CAAC,QAAQ,EAAE,QAAQ,CAAC;IAC5B,2DAA2D;IAC3D,QAAQ,CAAC,OAAO,EAAE,OAAO,CAAC;IAC1B,+DAA+D;IAC/D,QAAQ,CAAC,aAAa,EAAE,aAAa,CAAC;IACtC,8CAA8C;IAC9C,QAAQ,CAAC,KAAK,EAAE,KAAK,CAAC;IACtB,sDAAsD;IACtD,QAAQ,CAAC,OAAO,EAAE,OAAO,CAAC;IAC1B,yBAAyB;IACzB,QAAQ,CAAC,SAAS,EAAE,SAAS,CAAC;IAC9B,kCAAkC;IAClC,QAAQ,CAAC,KAAK,EAAE,KAAK,CAAC;IACtB,uCAAuC;IACvC,QAAQ,CAAC,QAAQ,EAAE,QAAQ,CAAC;IAC5B,yCAAyC;IACzC,QAAQ,CAAC,OAAO,EAAE,OAAO,CAAC;IAC1B,uCAAuC;IACvC,QAAQ,CAAC,OAAO,EAAE,OAAO,CAAC;gBAEd,OAAO,GAAE,aAAkB;IA+BvC,IAAI,OAAO,IAAI,MAAM,CAEpB;IAED;;;;;;;;;;;;;;;OAeG;IACH,gBAAgB,CAAC,MAAM,EAAE,sBAAsB,GAAG,OAAO,CAAC,UAAU,CAAC;IAIrE;;;;;;;OAOG;IACH,aAAa,CACX,YAAY,EAAE,MAAM,EACpB,OAAO,GAAE,oBAAyB,GACjC,OAAO,CAAC,kBAAkB,CAAC;IAI9B;;;;;;OAMG;IACH,MAAM,CAAC,YAAY,EAAE,MAAM,EAAE,OAAO,GAAE;QAAE,MAAM,CAAC,EAAE,SAAS,CAAA;KAAO,GAAG,OAAO,CAAC,WAAW,CAAC;CAGzF"}
+{"version":3,"file":"client.d.ts","sourceRoot":"","sources":["../../src/client.ts"],"names":[],"mappings":"AAAA,mEAAmE;AAEnE,OAAO,EAAiB,SAAS,EAAE,KAAK,WAAW,EAAE,MAAM,WAAW,CAAC;AACvE,OAAO,EACL,OAAO,EACP,aAAa,EACb,OAAO,EACP,OAAO,EACP,SAAS,EACT,OAAO,EACP,QAAQ,EACR,KAAK,EACL,KAAK,EACL,WAAW,EACX,QAAQ,EACT,MAAM,gBAAgB,CAAC;AACxB,OAAO,KAAK,EACV,WAAW,EACX,SAAS,EACT,oBAAoB,EACpB,sBAAsB,EACtB,UAAU,EACV,kBAAkB,EACnB,MAAM,YAAY,CAAC;AAEpB,eAAO,MAAM,gBAAgB,6BAA6B,CAAC;AAC3D,eAAO,MAAM,kBAAkB,QAAS,CAAC;AACzC,eAAO,MAAM,eAAe,mBAAmB,CAAC;AAChD,eAAO,MAAM,gBAAgB,oBAAoB,CAAC;AAElD,oGAAoG;AACpG,eAAO,MAAM,OAAO,WAAW,CAAC;AAEhC,MAAM,WAAW,aAAa;IAC5B,sDAAsD;IACtD,MAAM,CAAC,EAAE,MAAM,CAAC;IAChB,sEAAsE;IACtE,OAAO,CAAC,EAAE,MAAM,CAAC;IACjB,0CAA0C;IAC1C,SAAS,CAAC,EAAE,MAAM,CAAC;IACnB;;;OAGG;IACH,UAAU,CAAC,EAAE,MAAM,CAAC;IACpB,qDAAqD;IACrD,cAAc,CAAC,EAAE,MAAM,CAAC;IACxB,qEAAqE;IACrE,KAAK,CAAC,EAAE,OAAO,CAAC,WAAW,CAAC,CAAC;IAC7B,eAAe,CAAC,EAAE,MAAM,CAAC;IACzB,4EAA4E;IAC5E,SAAS,CAAC,EAAE,SAAS,CAAC;CACvB;AAED;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GAiCG;AACH,qBAAa,MAAM;IACjB,OAAO,CAAC,QAAQ,CAAC,SAAS,CAAY;IAEtC,kDAAkD;IAClD,QAAQ,CAAC,WAAW,EAAE,WAAW,CAAC;IAClC,uDAAuD;IACvD,QAAQ,CAAC,QAAQ,EAAE,QAAQ,CAAC;IAC5B,2DAA2D;IAC3D,QAAQ,CAAC,OAAO,EAAE,OAAO,CAAC;IAC1B,+DAA+D;IAC/D,QAAQ,CAAC,aAAa,EAAE,aAAa,CAAC;IACtC,8CAA8C;IAC9C,QAAQ,CAAC,KAAK,EAAE,KAAK,CAAC;IACtB,sDAAsD;IACtD,QAAQ,CAAC,OAAO,EAAE,OAAO,CAAC;IAC1B,yBAAyB;IACzB,QAAQ,CAAC,SAAS,EAAE,SAAS,CAAC;IAC9B,kCAAkC;IAClC,QAAQ,CAAC,KAAK,EAAE,KAAK,CAAC;IACtB,uCAAuC;IACvC,QAAQ,CAAC,QAAQ,EAAE,QAAQ,CAAC;IAC5B,yCAAyC;IACzC,QAAQ,CAAC,OAAO,EAAE,OAAO,CAAC;IAC1B,uCAAuC;IACvC,QAAQ,CAAC,OAAO,EAAE,OAAO,CAAC;gBAEd,OAAO,GAAE,aAAkB;IA+BvC,IAAI,OAAO,IAAI,MAAM,CAEpB;IAED;;;;;;;;;;;;;;;;;OAiBG;IACH,gBAAgB,CAAC,MAAM,EAAE,sBAAsB,GAAG,OAAO,CAAC,UAAU,CAAC;IAIrE;;;;;;;OAOG;IACH,aAAa,CACX,YAAY,EAAE,MAAM,EACpB,OAAO,GAAE,oBAAyB,GACjC,OAAO,CAAC,kBAAkB,CAAC;IAI9B;;;;;;OAMG;IACH,MAAM,CAAC,YAAY,EAAE,MAAM,EAAE,OAAO,GAAE;QAAE,MAAM,CAAC,EAAE,SAAS,CAAA;KAAO,GAAG,OAAO,CAAC,WAAW,CAAC;CAGzF"}

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.9';
+exports.VERSION = '0.4.11';
 /**
  * Cliente de la API de Veriko.
  *
@@ -107,8 +107,10 @@ class Veriko {
      * Devuelve el veredicto en `attributes.status`: `valid`, `not_found`,
      * `cep_unavailable`, `returned` o `error`.
      *
-     * La operación exige `claveRastreo` o `referenciaNumerica`. Enviar las dos
-     * precisa la búsqueda. La fecha es la de envío, en `YYYY-MM-DD`.
+     * La operación exige `cuentaBeneficiaria`, y `claveRastreo` o
+     * `referenciaNumerica`. Enviar las dos últimas precisa la búsqueda. La fecha
+     * es la de envío, en `YYYY-MM-DD`. `clientRef` es una referencia propia que
+     * vuelve en la validación y en los webhooks.
      *
      * Un `not_found` inmediato no equivale a una transferencia inexistente: un
      * CEP tarda en publicarse. `retryPolicy` deja a la API consultando de nuevo y

package/dist/cjs/client.js.map

@@ -1 +1 @@
-{"version":3,"file":"client.js","sourceRoot":"","sources":["../../src/client.ts"],"names":[],"mappings":"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"}
+{"version":3,"file":"client.js","sourceRoot":"","sources":["../../src/client.ts"],"names":[],"mappings":"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"}

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

@@ -67,6 +67,8 @@ export interface paths {
          *     - Banco receptor.
          *     - Cuenta beneficiaria.
          *
+         *     La cuenta beneficiaria (`cuenta_beneficiaria`) es obligatoria en esta operación. Si falta, la petición se rechaza con `422 preflight_failed` y el error de campo `cuenta_required`: el servicio no la busca entre los beneficiarios guardados.
+         *
          *     El veredicto final (estado terminal) de una validación puede ser alguno de estos:
          *
          *     - `valid`: El CEP de la transacción fue encontrado y validado.
@@ -133,7 +135,7 @@ export interface paths {
          *
          *     {% 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.\
-         *     Puedes guardar esa cuenta como beneficiario (en `POST /v1/beneficiaries`) para no enviarla en cada validación, el sistema detectará en automático los dígitos visibles en cada imagen.
+         *     Un beneficiario guardado (con `POST /v1/beneficiaries`) no sustituye a este campo: solo sirve para completar los dígitos de la cuenta que la imagen sí muestra. Si la imagen no trae dígitos suficientes, la validación se rechaza con `cuenta_unresolvable`, porque las cuentas guardadas no se prueban una por una.
          *
          *     {% /callout %}
          *
@@ -194,7 +196,7 @@ export interface paths {
          *
          *     - `status`: Acepta un estado, o varios separados por comas.
          *     - `with_deleted`: Distingue entre los registros activos y los retirados.
-         *     - **Los demás** acotan por: modalidad, fecha, contenido, banco, importe, origen y ciclo de reintentos.
+         *     - **Los demás** acotan por: modalidad, fecha, contenido, banco, importe, origen, referencia propia (`client_ref`) y ciclo de reintentos.
          *
          *     La forma de la respuesta está descrita en {% concept slug="pagination" %}la paginación{% /concept %}.
          *
@@ -1080,6 +1082,7 @@ export interface paths {
          *     **Firma secreta:**\
          *     El `secret` de firma se devuelve **únicamente en esta respuesta** y no puede recuperarse después. Un secreto perdido se sustituye con `POST /v1/webhooks/{id}/regenerate-secret`, que devuelve el nuevo e invalida el anterior de inmediato — el endpoint no hay que volver a registrarlo.\
          *     Ese secreto verifica cada entrega: el HMAC-SHA256 del cuerpo recibido debe coincidir con la cabecera `X-Webhook-Signature: sha256=<hex>`.\
+         *     Cada entrega lleva además `X-Webhook-Signature-Timestamped: t=<segundos>,v1=<hex>`, donde `v1` es el HMAC-SHA256 de `<t>.<cuerpo>`. Esa firma incluye la hora del intento, y la ventana de tolerancia recomendada es de 5 minutos contra `t`, no contra el `timestamp` del cuerpo: los reintentos llegan hasta unas 8,6 horas después del evento.\
          *     \
          *     La firma, y más detalles se describen en {% concept slug="webhooks-architecture" %}la arquitectura de webhooks{% /concept %}.
          *
@@ -2177,7 +2180,7 @@ export interface components {
              */
             outcomes?: ("not_found" | "cep_unavailable" | "error")[];
         };
-        /** @description Cuerpo de `POST /v1/validate` para una validación manual SPEI; exige `clave_rastreo` o `referencia_numerica`. */
+        /** @description Cuerpo de `POST /v1/validate` para una validación manual SPEI; exige `cuenta_beneficiaria` y `clave_rastreo` o `referencia_numerica`. */
         ValidationRequest: {
             /**
              * Format: date
@@ -2212,10 +2215,10 @@ export interface components {
              */
             receptor?: string;
             /**
-             * @description Cuenta bancaria receptora de la transferencia. Puede ser CLABE (18 dígitos), tarjeta (16 dígitos) o celular DiMo (10 dígitos), y el tipo se identifica por la longitud de sus dígitos. Los espacios y guiones que separan grupos ("0121 8000 4412 345678") se ignoran automáticamente antes de contar la longitud. Para celular DiMo, si el banco receptor no puede resolverse por el campo `receptor`, por los beneficiarios registrados ni por el directorio de cuentas, la respuesta es un estado HTTP `422` (con `bank_code_unresolvable_for_phone` en el cuerpo).
+             * @description Cuenta bancaria receptora de la transferencia. Es obligatoria: si falta, la respuesta es un estado HTTP `422` (con `preflight_failed` y el error de campo `cuenta_required`). Puede ser CLABE (18 dígitos), tarjeta (16 dígitos) o celular DiMo (10 dígitos), y el tipo se identifica por la longitud de sus dígitos. Los espacios y guiones que separan grupos ("0121 8000 4412 345678") se ignoran automáticamente antes de contar la longitud. Para celular DiMo, si el banco receptor no puede resolverse por el campo `receptor`, por los beneficiarios registrados ni por el directorio de cuentas, la respuesta es un estado HTTP `422` (con `bank_code_unresolvable_for_phone` en el cuerpo).
              * @example 012180004412345678
              */
-            cuenta_beneficiaria?: string;
+            cuenta_beneficiaria: string;
             /**
              * @description Indica si el beneficiario de la transferencia es directamente la institución receptora del pago («Pago a Banco» en el CEP de Banxico) y no uno de sus cuentahabientes. `0` para una transferencia a un cuentahabiente (valor por defecto); `1` para pagos cuyo beneficiario es el banco —pago de tarjeta de crédito, de crédito o de servicios a la propia institución. Opcional: si se omite se asume `0`.
              * @default 0
@@ -2225,6 +2228,11 @@ export interface components {
             receptor_participante: 0 | 1;
             /** @description Política de **reintentos automáticos** para esta validación. Si se omite, se aplica la política general configurada para el usuario. Los reintentos NO consumen cuota de validaciones. */
             retry_policy?: components["schemas"]["RetryPolicy"];
+            /**
+             * @description Referencia propia que se devuelve tal cual en la validación, en los webhooks de validación y como filtro exacto de `GET /v1/validations`. Texto de 1 a 64 caracteres, sin saltos de línea ni emoji; se recorta antes de guardarse. Un valor que no cumple se rechaza con un estado HTTP `422` (con `invalid_client_ref` en el cuerpo). No debe contener datos personales.
+             * @example orden-4812
+             */
+            client_ref?: string;
         } | unknown | unknown;
         /**
          * @description Código estable del fallo de una validación.
@@ -2324,6 +2332,11 @@ export interface components {
                 request_data?: {
                     [key: string]: unknown;
                 };
+                /**
+                 * @description Referencia propia que se envió en la petición (`client_ref`), devuelta tal cual. Solo aparece cuando la petición la incluyó. Sirve para relacionar la validación con un pedido propio, y `GET /v1/validations` la acepta como filtro exacto. No debe contener datos personales.
+                 * @example orden-4812
+                 */
+                client_ref?: string;
                 /**
                  * Format: date-time
                  * @description Fecha y hora, en ISO 8601 UTC, de creación de la validación.
@@ -2385,7 +2398,43 @@ export interface components {
                 } | null;
                 /** @description Advertencias de normalización presentes. Permiten explicar un resultado `not_found` inesperado. */
                 normalization_warnings?: string[] | null;
-                /** @description Indica si el número de tarjeta está enmascarado en el comprobante cargado (solo si `validation_type` es del tipo `ocr`). */
+                /**
+                 * @description Validación previa que ya había confirmado esta misma transferencia en la misma cuenta. Solo aparece cuando existe una validación `valid`, no retirada, con la misma clave de rastreo; nunca apunta a una validación de otra cuenta.
+                 *
+                 *     Es la forma estructurada del aviso que también se añade a `normalization_warnings`. No cambia el veredicto: la validación se consulta y se cobra igual.
+                 */
+                duplicate_of?: {
+                    /**
+                     * Format: uuid
+                     * @description Identificador de la validación previa.
+                     * @example 3fa85f64-5717-4562-b3fc-2c963f66afa6
+                     */
+                    id: string;
+                    /**
+                     * Format: date-time
+                     * @description Fecha y hora, en ISO 8601 UTC, de creación de la validación previa.
+                     * @example 2026-10-01T15:04:05Z
+                     */
+                    created_at: string;
+                };
+                /**
+                 * @description Conflicto entre la cuenta enviada y la que muestra la imagen. Solo aparece en validaciones de tipo `ocr`, cuando se envió `cuenta_beneficiaria` y la imagen muestra otra cuenta completa de la misma longitud, válida y con confianza suficiente.
+                 *
+                 *     Prevalece la cuenta enviada, que es la que se consulta en Banxico: el campo no cambia el veredicto. Si el pago fue a la cuenta de la imagen, lo esperable es un `not_found`. Solo trae los últimos 4 dígitos de cada cuenta, y el conflicto también se añade a `normalization_warnings`.
+                 */
+                account_conflict?: {
+                    /**
+                     * @description Últimos 4 dígitos de la cuenta enviada en `cuenta_beneficiaria`.
+                     * @example 5678
+                     */
+                    sent_last4: string;
+                    /**
+                     * @description Últimos 4 dígitos de la cuenta completa que muestra la imagen.
+                     * @example 9012
+                     */
+                    read_last4: string;
+                };
+                /** @description Indica si la cuenta beneficiaria viene enmascarada en el comprobante cargado, sea una CLABE, una tarjeta o un celular. Solo se incluye cuando vale `true` y solo si `validation_type` es del tipo `ocr`. */
                 is_masked?: boolean | null;
                 /**
                  * @description Datos devueltos por Banxico. Las propiedades tipadas abajo son las 20 que declara el esquema oficial del complemento SPEI.
@@ -2545,6 +2594,11 @@ export interface components {
                     expires_at?: components["schemas"]["TimestampUTC"];
                     /** @description Estado del ciclo de reintentos automáticos al momento del encolamiento. Siempre presente; si no se configuró `retry_policy` en el body ni en la política del usuario, `enabled=false` y los campos de política son `null`. */
                     retry_state?: components["schemas"]["RetryStateFull"];
+                    /**
+                     * @description Referencia propia enviada en la petición (`client_ref`), devuelta tal cual. Solo aparece cuando la petición la incluyó.
+                     * @example orden-4812
+                     */
+                    client_ref?: string;
                 };
             };
             /** @description Metadatos de control del flujo de polling. */
@@ -2576,12 +2630,17 @@ export interface components {
              */
             image_url?: string;
             /**
-             * @description Cuenta receptora de la transferencia (útil cuando falta o está incompleta en la imagen). Requerida para celular DiMo; opcional si la cuenta está guardada como beneficiario. Acepta CLABE (18 dígitos), tarjeta (16 dígitos) o celular DiMo (10 dígitos).
+             * @description Cuenta receptora de la transferencia (útil cuando falta o está incompleta en la imagen). Requerida para celular DiMo; opcional si la imagen muestra la cuenta completa o sus últimos dígitos, que se completan con los beneficiarios guardados (estos no sustituyen a este campo). Acepta CLABE (18 dígitos), tarjeta (16 dígitos) o celular DiMo (10 dígitos).
              * @example 012180004412345678
              */
             cuenta_beneficiaria?: string;
             /** @description Política de reintentos automáticos para esta validación. Si se omite, se aplica la política general del usuario, configurada en `PUT /v1/users/me/retry-policy`. **Los reintentos no consumen cuota de validaciones**. */
             retry_policy?: components["schemas"]["RetryPolicy"];
+            /**
+             * @description Referencia propia que se devuelve tal cual en la validación, en los webhooks de validación y como filtro exacto de `GET /v1/validations`. Texto de 1 a 64 caracteres, sin saltos de línea ni emoji; se recorta antes de guardarse. Un valor que no cumple se rechaza con un estado HTTP `422` (con `invalid_client_ref` en el cuerpo). No debe contener datos personales.
+             * @example orden-4812
+             */
+            client_ref?: string;
         } | unknown | unknown;
         /** @description Estado resumido del ciclo de reintentos, con la configuración representada como `null`. */
         RetryStateCompact: {
@@ -2668,6 +2727,11 @@ export interface components {
                 /** @description Fecha de retiro del historial, en ISO 8601 UTC. */
                 deleted_at?: components["schemas"]["TimestampUTC"] | null;
                 retry_state?: components["schemas"]["RetryStateCompact"];
+                /**
+                 * @description Referencia propia enviada al validar (`client_ref`), devuelta tal cual. Solo aparece cuando la petición la incluyó.
+                 * @example orden-4812
+                 */
+                client_ref?: string;
             };
         } & WithRequired<components["schemas"]["JsonApiResourceBase"], "type" | "id">;
         /** @description Recurso JSON:API con contadores por `banxico_status`, estado del ciclo de vida y modalidad de validación. */
@@ -3838,7 +3902,7 @@ export interface components {
                 /** @description Fecha y hora de la última entrega exitosa, en ISO 8601 UTC. `null` cuando el endpoint aún no completó ninguna entrega. */
                 last_delivery_at: components["schemas"]["TimestampUTC"] | null;
                 /**
-                 * @description Clave compartida para verificar firmas. **Solo presente** en la respuesta de creación y de rotación del endpoint; se omite en cualquier otra respuesta. Se usa para validar la cabecera `X-Webhook-Signature` de cada entrega.
+                 * @description Clave compartida para verificar firmas. **Solo presente** en la respuesta de creación y de rotación del endpoint; se omite en cualquier otra respuesta. Se usa para validar las cabeceras `X-Webhook-Signature` y `X-Webhook-Signature-Timestamped` de cada entrega.
                  * @example a0b1c2d3e4f5061728394a5b6c7d8e9f00112233445566778899aabbccddeeff
                  */
                 secret?: string;
@@ -5348,7 +5412,7 @@ export interface operations {
             };
         };
         responses: {
-            /** @description Veredicto final de la validación. El campo `status` puede ser: `valid`, `not_found`, `cep_unavailable`, `returned` o `error`. Cuando `has_cep: true` el certificado CEP está disponible vía `GET /v1/validations/{id}/cep`. */
+            /** @description Veredicto final de la validación. El campo `status` puede ser: `valid`, `not_found`, `cep_unavailable`, `returned` o `error`. Cuando la respuesta trae `links.cep_pdf` y `links.cep_xml`, el certificado CEP está disponible en `GET /v1/validations/{id}/cep`. */
             200: {
                 headers: {
                     /** @description Presente solo cuando la petición incluyó la cabecera `Idempotency-Key`. `false` para respuestas frescas; `true` cuando la respuesta es reutilizada desde el caché de idempotencia, con una vigencia de 24 horas por combinación de cuenta, endpoint y clave. */
@@ -5366,7 +5430,7 @@ export interface operations {
             401: components["responses"]["Unauthorized"];
             409: components["responses"]["IdempotencyKeyInProgress"];
             413: components["responses"]["PayloadTooLarge"];
-            /** @description Falló la validación de la petición. Códigos típicos: `clave_or_ref_required`, `required` (fecha/monto), `invalid_date`, `invalid_amount`, `invalid_account_format`, `invalid_account_length`, `invalid_clabe_checksum`, `invalid_card_luhn`, `invalid_bank_code` (`emisor`/`receptor` no reconocidos), `intra_bank_no_cep` (emisor y receptor son el mismo banco), `invalid_field_type` (un campo que debe ser texto llegó como arreglo u objeto — p. ej. `emisor`, `receptor` o `referencia_numerica`), `invalid_receptor_participante`, `retry_policy_invalid`, `retry_pending_cap_exceeded`. También se emite cuando se reutiliza `Idempotency-Key` con un cuerpo distinto (`idempotency_key_reused`). */
+            /** @description Falló la validación de la petición. Códigos típicos: `clave_or_ref_required`, `required` (fecha/monto), `invalid_date`, `invalid_amount`, `invalid_account_format`, `invalid_account_length`, `invalid_clabe_checksum`, `invalid_card_luhn`, `invalid_bank_code` (`emisor`/`receptor` no reconocidos), `intra_bank_no_cep` (emisor y receptor son el mismo banco), `invalid_field_type` (un campo que debe ser texto llegó como arreglo u objeto — p. ej. `emisor`, `receptor` o `referencia_numerica`), `invalid_receptor_participante`, `retry_policy_invalid`, `retry_pending_cap_exceeded`. También se emite cuando se reutiliza `Idempotency-Key` con un cuerpo distinto (`idempotency_key_reused`). Cuando los datos se contradicen entre sí, la petición se rechaza antes de consultar a Banxico con `preflight_failed` y el detalle por campo en `errors` (`clabe_receptor_mismatch` y `tarjeta_receptor_mismatch`: la cuenta pertenece a otro banco que el `receptor`; `cuenta_invalid_luhn`; `clave_fecha_incoherente`; `clave_longitud_invalida`). También se rechaza con `preflight_failed` cuando falta `cuenta_beneficiaria` (`cuenta_required`). Ningún rechazo `preflight_failed` de esta ruta consume cuota, sea por datos que se contradicen, por un campo mal formado o por una cuenta ausente. */
             422: {
                 headers: {
                     [name: string]: unknown;
@@ -5483,6 +5547,11 @@ export interface operations {
                  * @example scotiabank
                  */
                 search?: string;
+                /**
+                 * @description Coincidencia exacta con la `client_ref` enviada al validar. Distingue mayúsculas, acentos y espacios internos. Un valor vacío o que no cumple las reglas de `client_ref` devuelve un estado HTTP `422` (con `invalid_filter` en el cuerpo).
+                 * @example orden-4812
+                 */
+                client_ref?: string;
                 /**
                  * @description Filtro — Muestra solo las validaciones del banco de pruebas (Playground). Si se envía, el único valor admitido es `1`; cualquier otro devuelve un estado HTTP `422`.
                  * @example 1
@@ -5583,6 +5652,11 @@ export interface operations {
                  * @example MXBA
                  */
                 search?: string;
+                /**
+                 * @description Coincidencia exacta con la `client_ref` enviada al validar. Distingue mayúsculas, acentos y espacios internos. Un valor vacío o que no cumple las reglas de `client_ref` devuelve un estado HTTP `422` (con `invalid_filter` en el cuerpo).
+                 * @example orden-4812
+                 */
+                client_ref?: string;
                 /**
                  * @description Filtro — Muestra solo las validaciones del banco de pruebas (Playground). Si se envía, el único valor admitido es `1`; cualquier otro devuelve un estado HTTP `422`.
                  * @example 1
@@ -5686,6 +5760,11 @@ export interface operations {
                  * @example MXBA20250315001234
                  */
                 search?: string;
+                /**
+                 * @description Coincidencia exacta con la `client_ref` enviada al validar. Distingue mayúsculas, acentos y espacios internos. Un valor vacío o que no cumple las reglas de `client_ref` devuelve un estado HTTP `422` (con `invalid_filter` en el cuerpo).
+                 * @example orden-4812
+                 */
+                client_ref?: string;
                 /**
                  * @description Filtro — Muestra solo las validaciones del banco de pruebas (Playground). Si se envía, el único valor admitido es `1`; cualquier otro devuelve un estado HTTP `422`.
                  * @example 1