Esquemas

Banco participante del catálogo SPEI, en formato JSON:API. `id` y `attributes.code` son siempre iguales (`id` se conserva como identificador estable del recurso aunque `code` lo duplique).

Resultado de resolución de un BIN contra el catálogo local de BIN, en formato JSON:API. `id` y `attributes.bin` son iguales: el BIN de 6-8 dígitos que efectivamente coincidió (nunca el número completo que se envió).

Calendario de días inhábiles SPEI de un año, en formato JSON:API. `id` y `attributes.year` son siempre iguales: el año del calendario.

Respuesta de `GET /v1/public/bin-lookup/{bin}`. Un único recurso con el banco emisor SPEI resuelto contra el catálogo local de BIN (lectura pura, sin consulta externa). Un BIN desconocido devuelve `404`, no este cuerpo.

Respuesta de `GET /v1/public/banks`. Catálogo completo (~95 instituciones) de participantes SPEI activos. Cacheable con ETag — el snapshot cambia semanalmente cuando el sincronizador de Banxico refresca el catálogo.

Respuesta de `GET /v1/public/spei-calendar/{year}`. Un único recurso con los días inhábiles SPEI del año y su fuente, y en `meta.covered_years` los años que tienen calendario. Un año sin calendario responde `404`, no este cuerpo.

Cuenta beneficiaria registrada como recurso JSON:API. Puede ser una CLABE, un número de tarjeta o un número de celular DiMo. El tipo de cuenta se autodetecta por longitud al momento de inserción.

Cupo de beneficiarios activos del plan y ocupación actual de la cuenta autenticada.

Fila extraída de un archivo de importación de beneficiarios, con su grupo de clasificación y los campos parseados. La cuenta viaja completa para el dueño de la importación, que la revisa y corrige antes de confirmar; la vista admin de otro usuario la enmascara. Envuelta bajo `{ type, id, attributes }` siguiendo el formato JSON:API.

Recurso JSON:API con la cuenta beneficiaria resuelta para el usuario.

Recurso JSON:API mínimo con el ID de la importación y su nuevo estado tras la confirmación.

Cuerpo multipart de `POST /v1/beneficiaries/imports`: el archivo a importar y el modo de lectura con el que se procesa.

Recurso JSON:API mínimo con el ID de la importación y su estado inicial.

Cuerpo de `POST /v1/beneficiaries`. Acepta dos formas: un objeto plano con los atributos en la raíz, o el envoltorio JSON:API `{ data: { attributes: {...} } }`. El servidor prueba primero `data.attributes` y, si está ausente, toma el objeto raíz. El tipo de cuenta (`clabe`, `card`, `phone`) se autodetecta por la longitud de los dígitos: 18 = CLABE, 16 = tarjeta, 10 = celular (DiMo). Cuando el tipo detectado es `phone`, `bank_code` es **obligatorio**; para CLABE y tarjeta el `bank_code` enviado por el cliente se ignora y se deriva del prefijo CLABE o del BIN.

Cuerpo de `PATCH /v1/beneficiaries/imports/{id}/rows/{row_id}`. Acepta envoltorio JSON:API `{ data: { attributes: {...} } }` o un objeto plano. Todos los atributos son opcionales — solo se sobreescriben los presentes. Cinco campos editables: `parsed_account`, `parsed_label`, `parsed_account_type`, `parsed_bank_code`, `parsed_bank_name`. Cualquier otra clave se ignora. Si el cuerpo no contiene ningún campo editable reconocido → `422 no_valid_fields`. Si la importación no está en estado `preview_ready` → `422 job_not_editable`. Tras persistir la corrección, el servidor re-procesa la fila (re-deriva banco a partir del prefijo CLABE / BIN nuevos) para que los contadores de la importación y la columna Banco de la vista previa queden sincronizados sin esperar a la confirmación.

Cuerpo de `PUT /v1/beneficiaries/{id}`. Acepta envoltorio JSON:API `{ data: { attributes: {...} } }` o un objeto plano. Todos los campos son opcionales — solo se actualizan los presentes. Si el cuerpo no contiene ningún campo editable, el servidor responde `422 no_valid_fields`. Hay tres rutas de actualización. Con solo `label`, se sanea y se guarda. Con un `account_number` nuevo, se vuelven a derivar `account_type`, `bank_code` y `bank_name` con las mismas reglas que `POST /v1/beneficiaries`. Con solo `bank_code`, el cambio vale únicamente si el beneficiario es de tipo `phone`: En CLABE y tarjeta se ignora sin avisar—, y deja el evento de auditoría `beneficiary.phone_bank_updated` cuando el código cambia.

Recurso JSON:API con el resultado estructural de la cuenta validada.

Importación masiva de beneficiarios. Ciclo de vida: `pending` → `parsing` → `preview_ready` → `committing` → `completed` (o `failed` / `cancelled`). Envuelto bajo `{ type, id, attributes }` siguiendo el formato JSON:API.

Respuesta `202` de `POST /v1/beneficiaries/imports/{id}/commit`: el ID de la importación y su estado tras encolar la confirmación (`committing`).

Respuesta `202` de `POST /v1/beneficiaries/imports`: el ID de la importación recién creada y su estado inicial (`pending`).

Respuesta de `POST /v1/beneficiaries` con el beneficiario en `data`. Devuelve `201` al crear un registro nuevo, y `200` cuando reactiva una cuenta archivada con el mismo `account_number`: Ahí `meta.reactivated` viene en `true`.

Respuesta de `GET /v1/beneficiaries`: las cuentas beneficiarias del usuario autenticado, en un arreglo plano y sin paginar. El parámetro `?with_archived` decide cuáles entran.

Respuesta de `GET /v1/beneficiaries/lookup`: los metadatos del beneficiario cuando la cuenta consultada está entre las del usuario autenticado.

Respuesta de `PATCH /v1/beneficiaries/imports/{id}/rows/{row_id}`: la fila ya corregida y reprocesada. Su grupo de clasificación (`status`) puede haber cambiado con la corrección.

Respuesta de `PUT /v1/beneficiaries/{id}`: el beneficiario actualizado, con los campos derivados ya recalculados.

Respuesta de `GET /v1/beneficiaries/validate-account?account=`. Resultado estructural de un número de cuenta. Bajo `data.attributes` se reporta el tipo detectado, el checksum, los metadatos del banco resuelto (cuando se puede) y, para CLABEs parciales de 17 dígitos, la versión auto-completada. Este endpoint **no** consulta Banxico — solo validación local.

Respuesta de `GET /v1/beneficiaries/imports/{id}`: la importación con su estado actual y los contadores por grupo de clasificación.

Respuesta de `GET /v1/beneficiaries/imports/{id}/preview`: las filas parseadas, paginadas, con una instantánea de la importación en `meta`. Las cuentas viajan completas para el propietario de la importación; la vista admin de otro usuario las enmascara.

Estado inicial de la ejecución de un trabajo de importación confirmado.

Cuerpo opcional de `POST /v1/validations/imports/{id}/commit`.

Estado de un trabajo de importación recién creado.

Plantilla de importación en JSON entregada como archivo descargable.

Cuerpo de `PATCH /v1/validations/imports/{id}/rows/{row_id}`.

Política de reintentos de una validación: activación, límite, intervalo y resultados elegibles.

Estado resumido del ciclo de reintentos, con la configuración representada como `null`.

Estado completo del ciclo de reintentos, con configuración, avance y situación actual.

Código estable del fallo de una validación. La lista no es cerrada: un fallo inesperado trae `internal_error` y otros fallos pueden traer el código de su causa, así que trata un valor desconocido como un fallo genérico.

Entrada de una importación masiva en modo `images`, con una o varias imágenes PNG, JPG o WEBP.

Recurso JSON:API de un trabajo de importación masiva y su estado de ejecución.

Fila interpretada de un trabajo de importación, desde la lectura del archivo hasta el resultado de la validación.

Entrada de una importación masiva en modo `text`, con un archivo CSV, XLSX, XLS, TXT o JSON.

Cuerpo de `POST /v1/validations/{id}/purge/execute`: el token del paso de preparación.

Respuesta de `POST /v1/validations/{id}/purge/execute`: la validación quedó purgada y esto es lo que se borró.

Respuesta de `POST /v1/validations/{id}/purge/prepare`: lo que borraría el borrado definitivo, lo que conservaría y el token que lo confirma. Todavía no ha cambiado nada.

Resultado de la revisión que acompaña, dentro de `meta`, la respuesta de `POST /v1/validations/{id}/recheck`.

Recurso JSON:API con contadores por `banxico_status`, estado del ciclo de vida y modalidad de validación.

Estado completo del ciclo después de cancelar los reintentos pendientes de una validación.

Entrada de una importación masiva cuyo `upload_type` selecciona texto o imágenes.

Cuerpo de `POST /v1/validate-ocr` con el comprobante en `image` o `image_url`; exige al menos uno de ambos campos. `cuenta_beneficiaria` y `cuentas_candidatas` no pueden ir juntas.

Recurso JSON:API resumido de una validación en el historial de la cuenta.

Intento de reintento automático de una validación.

Estado completo del ciclo después de actualizar su política de reintentos.

Cuerpo de `PUT /v1/validations/{id}/retry-policy`.

Recurso JSON:API de una validación SPEI devuelto por la consulta individual y la validación síncrona.

Cuerpo de `POST /v1/validate` para una validación manual SPEI; exige `clave_rastreo` o `referencia_numerica`, y una sola de las dos formas de indicar la cuenta: `cuenta_beneficiaria` o `cuentas_candidatas`.

Cuerpo de `POST /v1/webhooks` con la URL HTTPS receptora, los eventos suscritos y una etiqueta opcional.

Resultado de una entrega de prueba: respuesta del receptor, latencia o error.

Cuerpo de `PUT /v1/webhooks/{id}` con los campos del endpoint que deben actualizarse.

Recurso JSON:API de una entrega de webhook, con receptor, intento, respuesta y estado.

Recurso JSON:API de un endpoint webhook, con URL receptora, eventos suscritos, estado y representación del secreto.

Indicadores agregados de las validaciones de la cuenta.

Ranking de bancos de la cuenta según la métrica solicitada.

Ranking de beneficiarios de la cuenta por validaciones durante los últimos 90 días.

Series temporales de validaciones cuyos puntos contienen métricas de volumen o latencia según `metric`.

Recurso JSON:API de la vista previa de un reporte financiero.

Entrada del ranking de bancos por volumen verificado.

Respuesta de vista previa de un reporte financiero con las cabeceras y hasta 20 filas del CSV.

Indicadores financieros de la cuenta para un mes calendario, con agregados, desgloses y comparación con el mes anterior.

Recurso JSON:API del resumen financiero.

Respuesta de `GET /v1/finance/summary` con los indicadores del mes solicitado en `data.attributes`.

Estadísticas de uso de la API, cuota de validaciones y estado de Banxico para la cuenta.

Consumo de la cuenta por tipo de operación durante el periodo consultado.

Historial mensual de consumo para el número de meses solicitado.

Límites de tasa aplicables a la cuenta.

Recurso JSON:API con el mapa de calor de validaciones.

Cuota de validaciones de la cuenta para el ciclo de suscripción vigente.

Respuesta de `GET /v1/usage/heatmap` con la densidad de validaciones por día de la semana y hora.

Recurso JSON:API de la comparativa, con planes por columna y características por fila.

Característica bilingüe de un plan, con indicador visual, orden y estado.

Atributos públicos de un precio de plan: moneda, intervalo, tipo, importe unitario y tratamiento fiscal.

Atributos de un plan de suscripción: límites de uso, modelo de facturación, visibilidad y orden dentro del catálogo.

Respuesta de `GET /v1/plans/public/comparison` con la matriz de planes públicos.

Recurso JSON:API de un precio activo del plan.

Plan del catálogo público con sus precios y características activas.

Respuesta de `GET /v1/plans/{slug}/prices` con los precios activos y un resumen del plan en `meta.plan`.

Un plan activo del catálogo autenticado, con sus características bilingües activas.

Respuesta de `GET /v1/plans/public` con los planes activos del catálogo público, sus precios y características.

Suscripción activa del usuario, con su origen, estado, ciclo y límites. Cada usuario tiene exactamente una. Los campos `trial_*`, `cancel_*` y `stripe_subscription_id` son nulos cuando no aplican.

Resumen de cuota del ciclo activo. Devuelto en `meta.quota` por `GET /v1/billing/subscription`.

Recurso JSON:API con la suscripción activa del usuario.

Suscripción activa y resumen de cuota devueltos por `GET /v1/billing/subscription`.

Límites efectivos de reintentos del plan activo, con los valores globales cuando no hay una sobreescritura.

Política de reintentos guardada de la cuenta: activación, límite, intervalo y resultados elegibles. Desactivada o sin configurar, trae `enabled=false`, `max_retries=0`, `interval_seconds=0` y `outcomes` vacío.

Conjunto consolidado del usuario autenticado que devuelve `GET /v1/users/me`: perfil, metadatos de la clave de API, suscripción activa, estado de la autenticación de 2 factores (2FA), permisos del rol y resumen de notificaciones en una sola llamada.

Una sesión de la cuenta. Nace al entrar, al superar la autenticación de 2 factores (2FA) o al cambiar la contraseña, y de cada una se guarda desde dónde se abrió y hasta cuándo vale.

Cuerpo de la petición para actualizar la política de reintentos por defecto del usuario (aplica a futuras validaciones).

Las sesiones activas del usuario autenticado, con su cantidad. Las revocadas y las caducadas quedan fuera, y la lista viene ordenada por uso reciente.

Estado público del servicio de verificación de Banxico, tal como lo devuelve `GET /v1/status/banxico`. Muestra el estado operativo actual y una explicación legible.

Serie temporal de métricas de salud del servicio de verificación de Banxico, agrupada por intervalos de tiempo, tal como la devuelve `GET /v1/status/banxico/timeseries`.

Recurso JSON:API con la lectura actual del estado público.

Recurso JSON:API con la serie temporal del par métrica/ventana solicitado.

Respuesta de `GET /v1/status/banxico`. Vista pública reducida del estado del servicio de verificación de Banxico, sin detalles internos. Cacheada 60s (por `Cache-Control` en la respuesta) — pensada para health badges en dashboards de clientes.

Respuesta de `GET /v1/status/banxico/timeseries`. Puntos de datos agrupados por grupo de tiempo para la métrica y ventana solicitadas. Solo expone métricas seguras (`probe_latency`, `verdict`); valores de query inválidos caen silenciosamente a los defaults (`probe_latency`, `24h`).

Resumen JSON:API del panel de la cuenta, con métricas agregadas, progreso de configuración y validaciones recientes.

Envoltorio JSON:API de la petición del proxy del Playground. El servidor reenvía la operación descrita en `data.attributes` al endpoint `/v1` destino usando la clave de API del propio usuario (descifrada del lado servidor), de modo que la clave nunca llega al navegador.

Envoltorio JSON:API con las categorías y plantillas disponibles para el playground, filtradas por los permisos del usuario que llama.

Descriptor compañero presente en el bloque `meta` de cada respuesta (y en el `meta` del cuerpo de los webhooks salientes). Permite a los clientes afirmar el contrato de zona horaria sin releer el spec.

Un error individual: el código estable por el que ramifica el cliente, el mensaje legible —ese sí traducido—, el estado HTTP y, cuando el fallo es de un campo concreto, el puntero que lo señala.

Wrapper estándar de respuesta de error. El campo `code` dentro de cada error es el contrato estable legible por máquina — los clientes deben ramificar por `code`, no por `detail`.

Identidad de un recurso dentro de la envoltura JSON:API: el tipo al que pertenece y su identificador. Todo recurso que viaja en `data` la lleva, junto con sus `attributes`.

Estado de la cuota de validaciones vigente: límite, consumo, saldo y reinicio.

Wrapper estándar de respuesta exitosa. El payload de la respuesta está en `data`; los metadatos de la petición en `meta`; los enlaces de paginación o relacionados en `links` cuando aplica.

Timestamp ISO 8601 en UTC con sufijo `Z` explícito; por ejemplo, `"2026-05-01T05:14:38Z"`. Los campos `*_at`, `*_end`, `*_start` y `*_date` adoptan esta forma. `meta.datetime` describe el mismo contrato en la respuesta.

Respuesta asíncrona de `POST /v1/validate?async=1` y `POST /v1/validate-ocr?async=1`. Contiene la validación encolada y los datos necesarios para consultar su resultado en `GET /v1/validations/{id}`.