Esquemas
Catálogo de modelos JSON utilizados por la API. Cada esquema incluye descripción bilingüe, propiedades y referencias.
Sin resultados.
Public
BankResourceBanco 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).BinLookupResponseRespuesta de `GET /v1/public/bin-lookup/{bin}`. Un único recurso con el banco emisor SPEI resuelto contra el catálogo local `bin_directory` (lectura pura, sin consulta externa). Un BIN desconocido devuelve `404`, no este cuerpo.BinResourceResultado de resolución de un BIN contra el catálogo local `bin_directory`, 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ó).ListBanksResponseRespuesta 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.
Beneficiaries
BeneficiaryCuenta 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.BeneficiaryImportJobImportació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.BeneficiaryImportJobResponseRespuesta de `GET /v1/beneficiaries/imports/{id}`. Devuelve la importación completo con su estado actual y los contadores por grupo. Sondea hasta `preview_ready` (para mostrar la vista previa), `committed`/`completed` (para finalizar la UI) o `failed`/`cancelled` (para terminar el flujo).BeneficiaryImportPreviewResponseRespuesta de `GET /v1/beneficiaries/imports/{id}/preview`. Filas parseadas paginadas con un snapshot de la importación en `meta`. Las CLABEs y celulares se muestran en claro al propietario de la importación; las tarjetas también van completas en la vista del propietario (la vista admin cross-user las enmascara).BeneficiaryImportRowFila extraída de un archivo de importación de beneficiarios, con su grupo de clasificación y los campos parseados. Los números de tarjeta (PANs) aparecen enmascarados; las CLABEs se muestran en claro al dueño de la importación. Envuelta bajo `{ type, id, attributes }` siguiendo el formato JSON:API.BeneficiaryLookupResourceRecurso JSON:API con la cuenta beneficiaria resuelta para el usuario.CommitBeneficiaryImportResourceRecurso JSON:API mínimo con el ID de la importación y su nuevo estado tras la confirmación.CommitBeneficiaryImportResponseRespuesta de `POST /v1/beneficiaries/imports/{id}/commit` (HTTP 202). Envoltorio JSON:API mínimo con el ID de la importación y su nuevo estado (`committing`). La confirmación lo ejecuta el trabajador; sondea `GET /v1/beneficiaries/imports/{id}` hasta `completed` o `failed`.CreateBeneficiaryImportRequestCuerpo multipart de `POST /v1/beneficiaries/imports`. Sube un archivo con beneficiarios y dispara una importación asíncrono. El usuario solo puede tener una importación activo simultáneamente — un upload mientras hay otra importación no terminal devuelve 422.CreateBeneficiaryImportResourceRecurso JSON:API mínimo con el ID de la importación y su estado inicial.CreateBeneficiaryImportResponseRespuesta de `POST /v1/beneficiaries/imports` (HTTP 202). Devuelve un envoltorio JSON:API mínimo con el ID de la importación y su estado inicial (`pending`). Sondea `GET /v1/beneficiaries/imports/{id}` cada 2s hasta que el estado sea `preview_ready` o `failed`.CreateBeneficiaryRequestCuerpo 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.CreateBeneficiaryResponseRespuesta de `POST /v1/beneficiaries`. Cuando el endpoint crea un registro nuevo, devuelve `201` con el beneficiario completo en `data`. Cuando el endpoint reactiva una cuenta archivada (mismo `account_number` que un registro `status=inactive`), devuelve `200` con `meta.reactivated=true`.ListBeneficiariesResponseRespuesta de `GET /v1/beneficiaries`. Contiene un arreglo plano (sin paginación) con todas las cuentas beneficiarias del usuario autenticado. El filtro tri-state `?with_archived` controla si se incluyen las cuentas archivadas.LookupBeneficiaryAccountResponseRespuesta de `GET /v1/beneficiaries/lookup?account=`. Devuelve los metadatos del beneficiario cuando la cuenta exacta existe en la lista blanca del usuario autenticado.PatchBeneficiaryImportRowRequestCuerpo 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.PatchBeneficiaryImportRowResponseRespuesta de `PATCH /v1/beneficiaries/imports/{id}/rows/{row_id}` con la fila tras aplicar la corrección y re-procesar. El grupo (`status`) puede haber cambiado si la corrección movió la fila entre `valid`, `correctable`, `fatal`, `duplicate_account` o `duplicate_alias`.UpdateBeneficiaryRequestCuerpo 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.UpdateBeneficiaryResponseRespuesta de `PUT /v1/beneficiaries/{id}` con el beneficiario actualizado.ValidateAccountResourceRecurso JSON:API con el resultado estructural de la cuenta validada.ValidateAccountResponseRespuesta 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.
Validations
CancelValidationRetriesAttributesAtributos del recurso devuelto al cancelar los reintentos pendientes de una validación (estado de reintento completo).CommitValidationImportAttributesResultado de confirmar el lote: cuántas filas traía y cuántas quedaron encoladas para procesarse.CommitValidationImportRequestCuerpo para confirmar un lote de validaciones ya revisado y mandarlo a procesar.CreateValidationImportAttributesEstado inicial del lote recién creado, antes de revisar sus filas.CreateValidationImportRequestCuerpo discriminado de la petición para crear una importación masiva de validaciones (entrada de texto o entrada de imágenes).DownloadValidationImportTemplateResponseRespuesta (cuerpo vacío) cuando el endpoint sirve la plantilla CSV directamente como contenido binario con `Content-Disposition`.OcrValidationRequestParámetros para validar una transferencia SPEI a partir de la imagen de un comprobante (OCR). Debe enviarse al menos uno de `image` o `image_url`; si ambos se omiten el servidor devuelve 422.PatchValidationImportRowRequestCuerpo para corregir una fila del lote antes de confirmarlo.RetryAttemptRegistro de un intento individual de reintento automático. Devuelto en el array `attempts` de `GET /v1/validations/{id}/retry-attempts`.RetryPolicyPolítica de reintentos automáticos. Configura cuándo y cuántas veces el sistema reintenta una validación cuyo resultado es elegible (`not_found`, `cep_unavailable` o `error` por defecto).RetryStateCompactEstado compacto del ciclo de reintentos, incluido en respuestas de lista (`GET /v1/validations`). Contiene los 4 campos más relevantes para una vista de lista; los detalles de la política (`max_retries`, `interval_seconds`, `outcomes`) son siempre `null` aquí y se exponen únicamente en `RetryStateFull`.RetryStateFullEstado completo del ciclo de reintentos, incluido en la respuesta de una validación individual (`GET /v1/validations/{id}`). Expone tanto los campos de estado como los detalles de la política configurada.UpdateValidationRetryPolicyAttributesAtributos del recurso devuelto tras actualizar la política de reintentos de una validación (estado de reintento completo).UpdateValidationRetryPolicyRequestCuerpo de la petición para actualizar la política de reintentos de una validación (estrategia de backoff y límites).ValidationRegistro completo de una validación SPEI en forma de JSON:API. Devuelto por `GET /v1/validations/{id}` y `POST /v1/validate` síncrono.ValidationErrorCodeCódigo de error de una validación en estado terminal `error` o `failed`. Los códigos `network`, `captcha` y `max_retries_exceeded` disparan el evento webhook `validation.error`; los demás solo son consultables por GET.ValidationImportImagesInputParámetros de importación masiva en modo imágenes. Envía una o varias imágenes de comprobante (PNG / JPG / WEBP) o un ZIP de imágenes. Cada imagen pasa por el pipeline canónico de OCR y normalización.ValidationImportJobEnvelope JSON:API de la importación masiva de validaciones. Lifecycle de estados: pending → parsing → preview_ready → committing → completed (o failed / cancelled).ValidationImportRowFila parseada de un lote de importación de validaciones. Representa el estado de una validación individual dentro del lote, desde el parseo hasta la respuesta de Banxico.ValidationImportTextInputParámetros de importación masiva en modo texto. Envía un único archivo CSV / XLSX / XLS / TXT / JSON. El campo `parse_mode` selecciona entre encabezados canónicos (`template`) o barrido libre por línea (`free`).ValidationListItemValidación abreviada para vistas de lista. Envuelta bajo `{ type, id, attributes }` siguiendo el formato JSON:API; los campos a continuación describen el bloque `attributes`. Las filas eliminadas (soft-delete) también aparecen — `is_deleted` y `deleted_at` permiten a la UI distinguirlas sin una petición adicional.ValidationRequestParámetros para validar una transferencia SPEI contra el CEP Banxico. Se requiere al menos uno de `clave_rastreo` o `referencia_numerica`; si ambos se omiten el servidor devuelve 422.ValidationStatsContadores agregados de las validaciones del usuario autenticado. Devuelto por `GET /v1/validations/stats`. Honra los mismos filtros que `GET /v1/validations` (`date_from`, `date_to`, `type`, `search`, `with_deleted`, `playground`, `batch_id`).
Account Directory
AccountDirectoryLookupResourceRecurso JSON:API con la entrada del directorio que coincide con el sufijo consultado.LookupAccountDirectoryResponseRespuesta de `GET /v1/account-directory/lookup?last_digits=`. Entrada más reciente del catálogo global de cuentas cuyo sufijo coincide con los dígitos enviados. **No incluye `account_number`** — solo el banco y la fecha de última observación, para evitar enumeración del catálogo.
Webhooks
CreateWebhookRequestCuerpo de la petición para crear un endpoint webhook saliente (URL HTTPS, lista de eventos suscritos y etiqueta opcional).SendWebhookTestAttributesResultado del envío de prueba al receptor: si contestó, con qué código y en cuánto tiempo — o el error que dio.UpdateWebhookRequestCuerpo para cambiar un receptor de webhooks: su dirección, los eventos que escucha y si sigue activo.WebhookDeliveryRegistro de una entrega individual de un webhook (incluyendo cada reintento, que aumenta `attempt`). Devuelto por `GET /webhooks/deliveries` (cross-endpoint del usuario) y `GET /webhooks/{id}/deliveries` (por endpoint). El cross-endpoint añade `endpoint_url` ya joineado para evitar lookups extra.WebhookEndpointEndpoint de webhook configurado por el usuario. La firma de las entregas usa HMAC-SHA256 sobre el cuerpo JSON con el `secret` como clave; la firma se envía en el header `X-{Brand}-Signature: sha256=<hex>` y se acompaña de `X-{Brand}-Event`, `X-{Brand}-Delivery-Id` y `X-{Brand}-Timestamp`. El valor de `X-{Brand}-Timestamp` es ISO 8601 UTC (`format: date-time`, sufijo `Z`), por ejemplo `2026-05-29T12:00:00Z`. El `secret` se devuelve sin censurar SOLO al crear (`POST /webhooks`) y al regenerar (`POST /webhooks/{id}/regenerate-secret`); en cualquier otra respuesta se sustituye por `secret_hint` con los últimos 4 caracteres.
Insights
InsightsOverviewAttributesKPIs de overview de validaciones. Disponible en alcance propio (`self`) y global de plataforma (`global`). Devuelto por `GET /v1/insights/overview`.InsightsTopBanksAttributesRanking de bancos por métrica seleccionada. Devuelto por `GET /v1/insights/top-banks`.InsightsTopBeneficiariesAttributesTop de beneficiarios del usuario por número de validaciones (últimos 90 días). Devuelto por `GET /insights/top-beneficiaries`. Cuando el usuario tiene una etiqueta en `/admin/beneficiaries` o `/beneficiaries`, el `label` proviene de ahí; si no, se cae al nombre del receptor capturado por OCR. Solo se exponen los últimos 4 dígitos del número de cuenta — el resto se censura por privacidad.InsightsTrendsAttributesDatos de series temporales de validaciones por métrica y rango. Devuelto por `GET /v1/insights/trends`. Para `metric=volume`, cada punto contiene `direct`, `ocr`, `valid` y `errored`. Para `metric=latency`, contiene percentiles `p50`, `p95`, `p99` y `avg`.
Finance
FinancePreviewResourceEnvoltorio JSON:API de la vista previa.FinancePreviewResponseRespuesta de vista previa de un reporte financiero (`format=preview`). Devuelve las cabeceras del CSV y las primeras 20 filas de datos para que la UI pueda mostrar una vista previa antes de la descarga completa.FinanceSummaryAttributesKPIs financieros del usuario para un mes calendario. Incluye conteos por veredicto Banxico, agregados monetarios, desglose diario, top contrapartes y bancos, distribución de veredicto, y comparativa con el mes anterior.FinanceSummaryResourceEnvoltorio JSON:API del resumen financiero.FinanceSummaryResponseRespuesta de `GET /finance/summary?month=YYYY-MM`. Contiene todos los KPIs financieros del mes en un solo bloque bajo `data.attributes`.FinanceTopBankBanco en el ranking de volumen verificado (emisor o receptor).
Usage
ApiUsageEstadísticas de uso de la API y estado del servicio Banxico. Devuelto por `GET /v1/api/usage`.GetUsageBreakdownAttributesAtributos del recurso devuelto al consultar el desglose de uso del período actual por tipo de operación (validaciones, OCR, etc.).GetUsageHeatmapResponseRespuesta de `GET /v1/usage/heatmap`. Densidad de validaciones por combinación (día de la semana, hora del día) sobre la ventana consultada.GetUsageHistoryAttributesAtributos del recurso devuelto al consultar el histórico de uso mensual del usuario (período, validaciones usadas y tope aplicable).GetUsageLimitsAttributesAtributos del recurso devuelto al consultar los límites de uso efectivos del usuario (rate-limits por IP y por email + notas).UsageHeatmapResourceRecurso JSON:API con el heatmap.UsageSummarySnapshot del consumo de validaciones del usuario en el mes en curso. Devuelto por `GET /usage/summary`. `tone` mapea el porcentaje a un grupo visible (`ok`, `warn`, `danger`) que la UI usa para colorear el indicador.
Plans
ListPlanPricesResponseRespuesta de `GET /v1/plans/{slug}/prices`. Lista los precios activos del plan más un mini-resumen del plan en `meta.plan` para evitar un round-trip extra a `/v1/plans/{slug}`.ListPlansItemUn plan del catálogo público, con su precio y las viñetas que lo describen en los dos idiomas.ListPublicPlansResponseRespuesta de `GET /v1/plans/public`. Lista todos los planes activos del catálogo público (visitor-scope), con sus precios y features.PlanPlan de suscripción disponible en la plataforma. Devuelto por `GET /v1/plans` para que el usuario pueda comparar opciones y elegir un plan.PlanComparisonResourceLa comparativa de planes fila a fila: cada característica y qué ofrece cada plan en ella.PlanComparisonResponseMatriz comparativa de los planes públicos (`GET /v1/plans/public/comparison`). Columnas alineadas al catálogo público; contenido editable en BD.PlanFeatureViñeta bilingüe de característica del plan, mostrada en el pricing card. El bloque `attributes` dentro del envelope JSON:API; el campo `id` vive a nivel de envelope.PlanPriceAttributesPrecio Stripe asociado a un plan, expuesto al cliente sin revelar `stripe_price_id`. Cada plan puede tener varios precios para combinaciones de moneda × intervalo × tipo (`base` para tarifa fija + opcional `metered_overage` para excedente medido).PlanPriceResourceUn precio del plan, con su moneda, su cadencia y el precio de Stripe al que corresponde.PublicPlanResourceUn plan tal como se publica: lo que incluye y lo que cuesta, sin nada de la administración interna.
Billing
BillingSubscriptionAttributesSuscripción activa del usuario. Cada usuario tiene exactamente una fila activa: el origen viene en `source`. Los campos `trial_*`, `cancel_*` y `stripe_subscription_id` son nulos cuando no aplican (planes gratuitos por defecto, concesiones de administrador o estados estables). Todos los timestamps están en UTC con sufijo `Z`.BillingSubscriptionQuotaMetaResumen de cuota del ciclo activo. Devuelto en `meta.quota` por `GET /v1/billing/subscription`.BillingSubscriptionResourceRecurso JSON:API con la suscripción de billing activa del usuario.BillingSubscriptionResponseRespuesta de `GET /v1/billing/subscription`. La suscripción activa se expone en `data`; el resumen de uso vive en `meta.quota` para que clientes legacy que ya leían `effective_plan_slug` no se vean afectados.
Users
UpdateUserRetryPolicyRequestCuerpo de la petición para actualizar la política de reintentos por defecto del usuario (aplica a futuras validaciones).UserMeBundleBundle consolidado del usuario autenticado. Devuelto por GET /v1/users/me. Incluye perfil, metadatos de API key, suscripción activa, estado de 2FA, permisos del rol y resumen de notificaciones en un solo roundtrip.UserSessionUna sesión abierta —o ya cerrada— de la cuenta. Nace al entrar, al superar el segundo factor o al cambiar la contraseña, y de cada una se guarda desde dónde se abrió y hasta cuándo vale.UserSessionsListBloque `attributes` devuelto por `GET /v1/users/me/sessions`. Contiene la lista de sesiones activas del usuario autenticado más su cardinalidad. Las sesiones revocadas o expiradas se filtran server-side. Las sesiones vienen ordenadas por uso reciente.
Banxico Status
BanxicoPublicStatusEstado público del servicio Banxico CEP. Devuelto por `GET /v1/banxico/status` sin autenticación. Muestra el estado operativo actual y una explicación legible.BanxicoPublicStatusResourceRecurso JSON:API con la lectura actual del estado público.BanxicoPublicStatusResponseRespuesta de `GET /v1/status/banxico`. Vista pública reducida del estado del servicio Banxico CEP, sin detalles internos. Cacheada 60s (por `Cache-Control` en la respuesta) — pensada para health badges en dashboards de clientes.BanxicoPublicTimeseriesSerie temporal de métricas de salud del servicio Banxico CEP en grupos de tiempo. Devuelto por `GET /v1/banxico/timeseries`.BanxicoPublicTimeseriesResourceRecurso JSON:API con la serie temporal del par métrica/ventana solicitado.BanxicoPublicTimeseriesResponseRespuesta 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`).
Dashboard
Playground
PlaygroundProxyRequestEnvoltorio 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 API key del propio usuario (descifrada del lado servidor), de modo que la clave nunca llega al navegador.PlaygroundTemplatesResponseEnvoltorio JSON:API con las categorías y plantillas disponibles para el playground, filtradas por los permisos del usuario que llama.
Comunes
DatetimeMetaDescriptor 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.ErrorObjectUn 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.ErrorResponseWrapper 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`.JsonApiResourceBaseIdentidad 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`.PlanQuotaStateEstado de la cuota de validaciones del plan vigente: cuántas incluye, cuántas se llevan consumidas, cuántas quedan y cuándo se reinicia la cuenta.SuccessEnvelopeWrapper 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.TimestampUTCTimestamp ISO 8601 en UTC con sufijo `Z` explícito. Ejemplo: `"2026-05-01T05:14:38Z"`. Cada campo `*_at`, `*_end`, `*_start`, `*_date` de la API usa esta forma. El descriptor compañero en `meta.datetime` permite afirmar el contrato en tiempo de ejecución sin volver a leer este spec. El `new Date(value)` nativo del navegador, el `datetime.fromisoformat` (≥3.11) de Python y el `time.Parse(time.RFC3339)` de Go parsean este formato directamente.ValidationQueuedRespuesta 202 del flujo de validación asíncrona (`POST /v1/validate?async=1` y `POST /v1/validate-ocr?async=1`). Indica que la validación fue encolada; consultar `GET /v1/validations/{id}` periódicamente para el resultado final.