@veriko-mx/sdk 0.4.10 → 0.4.12

package/CHANGELOG.md

@@ -7,6 +7,57 @@ versiones según [SemVer](https://semver.org/lang/es/).
 
 Sin cambios todavía.
 
+## [0.4.12] — 2026-10-02
+
+### Añadido
+
+- `validations.recheck()` (`POST /v1/validations/{id}/recheck`): vuelve a consultar a Banxico el
+  estado de pago de una validación `valid` creada hace 72 horas como máximo, sin consumir cuota.
+  Devuelve `RecheckResult` con la validación y con `checkedAt`, `changed` y `previousStatus`. Si
+  Banxico reporta la devolución, la validación pasa a `returned`. No se reintenta sola.
+- `validations.preparePurge()` y `validations.executePurge()`: el borrado definitivo de una
+  validación, en dos pasos. Devuelven `PurgePreparation` y `PurgeResult`. `executePurge()` no se
+  reintenta sola. Los tipos de `Validation` añaden `purged_at`.
+- `cuentasCandidatas` en `validateTransfer()`, `validations.validate()`, `validations.validateOcr()`,
+  `validations.enqueue()` y `validations.enqueueOcr()`: de 2 a 3 cuentas en una sola validación y con
+  una sola unidad de cuota. Los tipos de `Validation` añaden `candidate_match`, con la posición y los
+  últimos 4 dígitos de la cuenta que coincidió.
+- `retainImage` en `validations.validateOcr()` y `validations.enqueueOcr()`, y `image_retained` en los
+  tipos de `Validation`: con `retainImage: false` la plataforma no conserva el archivo del
+  comprobante.
+- El evento `validation.returned` en `WEBHOOK_EVENTS`, que avisa cuando una validación `valid` pasa
+  después a `returned`, y `payment_status` (`PaymentStatus`) en `evento.data.attributes`.
+
+### Cambiado
+
+- `cuentaBeneficiaria` deja de ser obligatoria cuando se envía `cuentasCandidatas`. Sin ninguna de
+  las dos, el SDK lanza `InvalidRequestError` con `cuenta_required`, y con las dos, con
+  `cuenta_y_candidatas_excluyentes`. En los dos casos no llama a la API.
+
+## [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

package/README.md

@@ -46,25 +46,27 @@ La API consulta el CEP y devuelve un veredicto en el campo `status`:
 | `invalid`         | Los datos enviados no forman una consulta válida                                       |
 | `error`           | Fallo durante el procesamiento; el motivo viaja en `error_code`                        |
 
-Con veredicto `valid`, el comprobante queda disponible en XML y en PDF.
+Con veredicto `valid`, el comprobante queda disponible en XML y en PDF. Un `valid` es el veredicto
+del momento de la consulta: Banxico puede reportar la devolución hasta 72 horas después, y la
+validación pasa a `returned`.
 
 ## Las familias de operaciones
 
-El cliente agrupa las 66 operaciones M2M de la API en once familias:
-
-| familia                | qué cubre                                                                                                             |
-| ---------------------- | --------------------------------------------------------------------------------------------------------------------- |
-| `client.validations`   | Validar por campos o por imagen, consultar, listar, exportar, la política de reintentos y la descarga del comprobante |
-| `client.webhooks`      | Registrar endpoints, rotar su secreto, enviar un evento de prueba y leer el historial de entregas                     |
-| `client.catalog`       | Catálogo de bancos SPEI, banco emisor de una tarjeta y estado del servicio de Banxico                                 |
-| `client.beneficiaries` | Cuentas beneficiarias guardadas y la importación masiva, como ciclo completo                                          |
-| `client.usage`         | Cuota de validaciones, límites de tasa y registro de actividad de la API                                              |
-| `client.account`       | Perfil y política de reintentos predeterminada de la cuenta                                                           |
-| `client.dashboard`     | Resumen del panel                                                                                                     |
-| `client.plans`         | Catálogo y comparación de planes públicos, sin clave de API                                                           |
-| `client.insights`      | Resumen, tendencias, bancos y beneficiarios principales                                                               |
-| `client.finance`       | Resumen, estado de cuenta, vistas previas y descargas financieras                                                     |
-| `client.billing`       | Suscripción activa                                                                                                    |
+El cliente agrupa las 69 operaciones M2M de la API en once familias:
+
+| familia                | qué cubre                                                                                                                                                |
+| ---------------------- | -------------------------------------------------------------------------------------------------------------------------------------------------------- |
+| `client.validations`   | Validar por campos o por imagen, consultar, listar, exportar, revisar el estado de pago, borrar, la política de reintentos y la descarga del comprobante |
+| `client.webhooks`      | Registrar endpoints, rotar su secreto, enviar un evento de prueba y leer el historial de entregas                                                        |
+| `client.catalog`       | Catálogo de bancos SPEI, banco emisor de una tarjeta y estado del servicio de Banxico                                                                    |
+| `client.beneficiaries` | Cuentas beneficiarias guardadas y la importación masiva, como ciclo completo                                                                             |
+| `client.usage`         | Cuota de validaciones, límites de tasa y registro de actividad de la API                                                                                 |
+| `client.account`       | Perfil y política de reintentos predeterminada de la cuenta                                                                                              |
+| `client.dashboard`     | Resumen del panel                                                                                                                                        |
+| `client.plans`         | Catálogo y comparación de planes públicos, sin clave de API                                                                                              |
+| `client.insights`      | Resumen, tendencias, bancos y beneficiarios principales                                                                                                  |
+| `client.finance`       | Resumen, estado de cuenta, vistas previas y descargas financieras                                                                                        |
+| `client.billing`       | Suscripción activa                                                                                                                                       |
 
 Las tres operaciones de uso más frecuente están también en la raíz del cliente, como atajo:
 `validateTransfer()`, `getValidation()` y `getCep()`.
@@ -99,9 +101,11 @@ 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: no la busca entre los beneficiarios guardados. Cuando no se sabe cuál fue la cuenta,
+`cuentasCandidatas` sustituye a `cuentaBeneficiaria`.
 
 ```ts
 import { Veriko } from '@veriko-mx/sdk';
@@ -141,6 +145,8 @@ El SDK lee el archivo y lo codifica en base64. `imageUrl` recibe un comprobante
 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.
 
+`cuentasCandidatas` reemplaza a `cuentaBeneficiaria` cuando la imagen no muestra la cuenta.
+
 El comprobante de una validación por OCR se descarga con `client.validations.image(id)`.
 
 ### Sin esperar al veredicto
@@ -170,6 +176,82 @@ 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.
+
+### Varias cuentas candidatas
+
+`cuentasCandidatas` lleva de 2 a 3 cuentas en una sola validación, con una sola unidad de cuota.
+
+```ts
+const validation = await client.validateTransfer({
+  fecha: '2025-03-15',
+  monto: 15000.5,
+  claveRastreo: 'MXBA20250315001234',
+  cuentasCandidatas: ['012180004412345678', '002010077777777771'],
+});
+
+console.log(validation.attributes.candidate_match?.index); // posición en la lista enviada, desde 0
+console.log(validation.attributes.candidate_match?.account_last4); // 7771
+```
+
+`validateOcr()`, `enqueue()` y `enqueueOcr()` también la aceptan. La API consulta las cuentas en el
+orden enviado y adopta la primera que coincide con la transferencia. `attributes.candidate_match`
+trae su posición y sus últimos 4 dígitos, y la cuenta completa queda en
+`attributes.normalized_data.cuenta_beneficiaria`. El veredicto no cambia.
+
+Se envía una de las dos formas, no las dos: el tipo de los argumentos lo impide, y con
+`cuentaBeneficiaria` y `cuentasCandidatas` juntas, o sin ninguna, el SDK lanza
+`InvalidRequestError` (`cuenta_y_candidatas_excluyentes` o `cuenta_required`) y no llama a la API.
+Una lista que no cumple se rechaza con `422` (`cuentas_candidatas_invalidas`).
+
+### Conservar el comprobante
+
+La plataforma conserva el archivo de una validación por imagen, y `client.validations.image(id)` lo
+descarga. Con `retainImage: false` lo borra en cuanto la validación llega a un estado terminal del
+que ya no lo necesita. El veredicto y los datos extraídos se conservan.
+
+```ts
+const validation = await client.validations.validateOcr({
+  image: 'comprobante.png',
+  retainImage: false,
+});
+console.log(validation.attributes.image_retained); // false
+```
+
+`enqueueOcr()` también acepta `retainImage`. `image()` responde `410` con `image_not_retained`
+cuando el archivo no se conserva, y la API rechaza con `422` (`invalid_retain_image`) un valor que
+no es booleano.
+
 ### Listar y recorrer el historial
 
 ```ts
@@ -186,7 +268,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.
 
@@ -215,6 +297,59 @@ con `cep_not_available` y el SDK lanza `NotFoundError`.
 Las descargas y las exportaciones devuelven el archivo y no un enlace: `content`, `contentType` y
 el `filename` que propone la API en `Content-Disposition`.
 
+## Revisar el pago después
+
+`client.validations.recheck(id)` vuelve a consultar a Banxico el estado de pago de una validación
+`valid` creada hace 72 horas como máximo, sin consumir cuota.
+
+```ts
+const result = await client.validations.recheck(validation.id);
+
+console.log(result.changed); // true si pasó de valid a returned
+console.log(result.previousStatus); // 'valid'
+console.log(result.validation.attributes.status); // 'returned'
+```
+
+Si Banxico reporta `devuelto` o `en_proceso_devolucion`, la validación pasa a `returned`, conserva su
+CEP y la API emite el webhook `validation.returned`. El estado del pago queda en
+`attributes.banxico_result._payment_status`. Una validación que ya estaba en `returned` responde su
+estado actual sin consultar a Banxico, y `checkedAt` vale `null`.
+
+Cada validación admite una consulta cada 10 minutos: antes, el SDK lanza `RateLimitError` con
+`recheck_rate_limited`, y `retryAfter` trae los segundos que faltan. Una validación en otro estado,
+o con más de 72 horas, lanza `InvalidRequestError` con `recheck_not_eligible` o
+`recheck_window_expired`. Si Banxico no entrega un estado legible, lanza `ServerError` con
+`recheck_unavailable`: la validación conserva su intervalo y se puede reintentar de inmediato.
+
+## Borrar una validación
+
+`client.validations.delete(id)` retira una validación del historial, pero el registro, el CEP, los
+datos extraídos y el archivo del comprobante siguen existiendo. El borrado definitivo los elimina en
+dos pasos: el primero describe lo que se borraría y emite un token de un solo uso, y el segundo lo
+confirma.
+
+```ts
+const preparation = await client.validations.preparePurge(validation.id);
+
+console.log(preparation.attributes.will_delete); // lo que se borraría
+console.log(preparation.attributes.expires_in); // segundos de vigencia del token
+
+const result = await client.validations.executePurge(validation.id, {
+  confirmationToken: preparation.attributes.confirmation_token,
+});
+console.log(result.attributes.purged_at, result.attributes.file_removal);
+```
+
+**El borrado es irreversible y no devuelve cuota.** La validación queda como una lápida: conserva el
+veredicto, las fechas y el monto, y trae `attributes.purged_at`. Después, el CEP, el comprobante, los
+reintentos y `recheck()` responden `410` con `validation_purged`. `file_removal` vale `pending`
+cuando algún archivo no se pudo borrar en ese momento y el barrido diario lo termina.
+
+Una validación en curso lanza `ConflictError` con `purge_validation_in_progress`. Un token vencido,
+mal formado o de otra validación lanza `InvalidRequestError`, y uno ya usado, `ConflictError` con
+`confirmation_token_already_used`. Si la respuesta de `executePurge()` no llega,
+`client.getValidation(id)` dice si el borrado se completó.
+
 ## Registrar un webhook
 
 ```ts
@@ -370,6 +505,32 @@ 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).
 
+### Una devolución posterior
+
+`validation.returned` avisa cuando una validación que había salido `valid` pasa después a
+`returned`. El endpoint recibe sólo los eventos a los que se suscribió, así que hay que añadirlo
+además de `validation.completed`:
+
+```ts
+const endpoint = await client.webhooks.create({
+  url: 'https://miapp.example.com/hooks/pagos',
+  events: ['validation.completed', 'validation.returned'],
+});
+```
+
+El cuerpo es el de `validation.completed` más `attributes.payment_status`, que `parseWebhook()`
+entrega en `evento.data.attributes.payment_status`:
+
+```ts
+if (evento.event === 'validation.returned') {
+  console.log(evento.data?.attributes.payment_status?.code); // devuelto o en_proceso_devolucion
+}
+```
+
+`checked_at` es el instante de la consulta. En el resto de los eventos `payment_status` está
+ausente. El evento no se emite al crear la validación: una operación que llega ya devuelta se
+entrega con `validation.completed` y `status=returned`.
+
 ### Lo que Banxico confirmó
 
 Cuando `banxico_status` es `valid`, o `returned` con CEP descargado, `evento.data.attributes`
@@ -378,24 +539,58 @@ 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.
 
 **Los del cliente** repiten una petición que falló por causas pasajeras. El SDK reintenta los
 `5xx`, el `408` y el `429`, y respeta el `Retry-After` de la respuesta cuando lo trae. El resto de
-los `4xx` no se reintenta, porque la petición hay que corregirla antes de repetirla.
+los `4xx` no se reintenta, porque la petición hay que corregirla antes de repetirla. `recheck()` y
+`executePurge()` no se reintentan solas: la primera tiene su propio tope de una consulta cada 10
+minutos, y el borrado es irreversible.
 
 ```ts
 const client = new Veriko({ maxRetries: 3 }); // 0 los desactiva; por omisión son 2
@@ -473,18 +668,19 @@ try {
 }
 ```
 
-| excepción                    | estado                                          |
-| ---------------------------- | ----------------------------------------------- |
-| `AuthenticationError`        | `401`                                           |
-| `ForbiddenError`             | `403`                                           |
-| `NotFoundError`              | `404`                                           |
-| `ConflictError`              | `409`                                           |
-| `InvalidRequestError`        | `400`, `413`, `422`                             |
-| `RateLimitError`             | `429`                                           |
-| `ServerError`                | `5xx`                                           |
-| `ConnectionError`            | Sin respuesta, con los reintentos agotados      |
-| `TimeoutError`               | `waitFor()` o `importWait()` agotaron su tiempo |
-| `SignatureVerificationError` | La firma de un webhook no cuadra                |
+| excepción                    | estado                                             |
+| ---------------------------- | -------------------------------------------------- |
+| `AuthenticationError`        | `401`                                              |
+| `ForbiddenError`             | `403`                                              |
+| `NotFoundError`              | `404`                                              |
+| `ConflictError`              | `409`                                              |
+| `InvalidRequestError`        | `400`, `413`, `422`                                |
+| `RateLimitError`             | `429`                                              |
+| `ServerError`                | `5xx`                                              |
+| `ApiError`                   | Cualquier otro estado de la API, por ejemplo `410` |
+| `ConnectionError`            | Sin respuesta, con los reintentos agotados         |
+| `TimeoutError`               | `waitFor()` o `importWait()` agotaron su tiempo    |
+| `SignatureVerificationError` | La firma de un webhook no cuadra                   |
 
 Cada error de la API trae `requestId`, que identifica la petición en los registros del sistema.
 
@@ -516,7 +712,7 @@ completos, por si hace falta una operación que el SDK todavía no envuelve.
 
 ## Superficie M2M
 
-El SDK cubre exactamente las 66 operaciones del spec público: `security: []` para las públicas y
+El SDK cubre exactamente las 69 operaciones del spec público: `security: []` para las públicas y
 `ApiKeyAuth` para las autenticadas.
 
 Entre ellas están el perfil y su política de reintentos, el resumen del panel, los dos endpoints

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.10";
+export declare const VERSION = "0.4.12";
 export interface VerikoOptions {
     /** La clave de API. Por omisión, `VERIKO_API_KEY`. */
     apiKey?: string;
@@ -95,8 +95,11 @@ 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`, o `cuentasCandidatas` cuando no se
+     * sabe cuál fue la cuenta (una de las dos, no las dos), 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,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;;;;;;;;;;;;;;;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;;;;;;;;;;;;;;;;;;OAkBG;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.10';
+exports.VERSION = '0.4.12';
 /**
  * Cliente de la API de Veriko.
  *
@@ -107,8 +107,11 @@ 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`, o `cuentasCandidatas` cuando no se
+     * sabe cuál fue la cuenta (una de las dos, no las dos), 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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"}