Esquemas
Catálogo de modelos JSON utilizados por la API. Cada esquema incluye descripción bilingüe, propiedades y referencias.
Sin resultados.
Bank data
Banxico
-
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. -
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 buckets de tiempo. Devuelto por `GET /v1/banxico/timeseries`. -
BanxicoPublicTimeseriesResponseRespuesta de `GET /v1/status/banxico/timeseries`. Puntos de datos agrupados por bucket 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`).
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. -
BeneficiaryImportJobJob de 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. -
BeneficiaryImportJobResponseRespuesta de `GET /v1/beneficiaries/imports/{id}`. Devuelve el job completo con su estado actual y los contadores por bucket. Sondea hasta `preview_ready` (para mostrar el preview), `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 del job en `meta`. Las CLABEs y celulares se muestran en claro al propietario del job; 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 bucket de clasificación y los campos parseados. Los números de tarjeta (PANs) aparecen enmascarados; las CLABEs se muestran en claro al dueño del job. Envuelta bajo `{ type, id, attributes }` siguiendo el formato JSON:API.
Envelopes & meta
Errors
Other
-
ApiUsageEstadísticas de uso de la API y estado del servicio Banxico. Devuelto por `GET /v1/api/usage`. -
BillingSubscriptionAttributesSuscripción activa del usuario resuelta por `SubscriptionResolver::resolveActive`. 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`. -
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. -
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ó). -
CancelValidationRetriesAttributesAtributos del recurso devuelto al cancelar los reintentos pendientes de una validación (estado de reintento completo). -
CommitBeneficiaryImportResponseRespuesta de `POST /v1/beneficiaries/imports/{id}/commit` (HTTP 202). Envoltorio JSON:API mínimo con el ID del job y su nuevo estado (`committing`). El commit lo ejecuta el worker; sondea `GET /v1/beneficiaries/imports/{id}` hasta `completed` o `failed`. -
CommitValidationImportAttributes -
CommitValidationImportRequest -
CreateBeneficiaryImportRequestCuerpo multipart de `POST /v1/beneficiaries/imports`. Sube un archivo con beneficiarios y dispara un job de importación asíncrono. El usuario solo puede tener un job activo simultáneamente — un upload mientras hay otro job no terminal devuelve 422. -
CreateBeneficiaryImportResponseRespuesta de `POST /v1/beneficiaries/imports` (HTTP 202). Devuelve un envoltorio JSON:API mínimo con el ID del job 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, 13–19 (≠18) = 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`. -
CreateValidationImportAttributes -
CreateValidationImportRequestCuerpo discriminado de la petición para crear un job de importación masiva de validaciones (entrada de texto o entrada de imágenes). -
CreateWebhookRequestCuerpo de la petición para crear un endpoint webhook saliente (URL HTTPS, lista de eventos suscritos y etiqueta opcional). -
DashboardSummarySnapshot del dashboard del usuario. Devuelto por `GET /summary`. `attributes` cuenta validaciones agregadas; `relationships.recent_validations` lista hasta 10 validaciones recientes (parámetro `?limit=N`, default 5). `comenzar_milestones_completed` mide el progreso del wizard `/comenzar` y lo usa el flujo de post-login para decidir si saltarse esa pantalla. -
DownloadValidationImportTemplateResponseRespuesta (cuerpo vacío) cuando el endpoint sirve la plantilla CSV directamente como contenido binario con `Content-Disposition`. -
FinancePreviewResponseRespuesta de preview de un reporte financiero (`format=preview`). Devuelve las cabeceras del CSV y las primeras 20 filas de datos para que la UI pueda mostrar un preview 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. -
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). -
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). -
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`. -
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. -
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. -
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}`. -
ListPlansItem -
ListPublicPlansResponseRespuesta de `GET /v1/plans/public`. Lista todos los planes activos del catálogo público (visitor-scope), con sus precios y features. -
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. -
LookupBeneficiaryAccountResponseRespuesta de `GET /v1/beneficiaries/lookup?account=`. Devuelve los metadatos del beneficiario cuando la cuenta exacta existe en la lista blanca del usuario autenticado. -
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. -
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 el job no está en estado `preview_ready` → `422 job_not_editable`. Tras persistir el override, el servidor re-procesa la fila (re-deriva banco a partir del prefijo CLABE / BIN nuevos) para que los contadores del job y la columna Banco del preview queden sincronizados sin esperar al commit. -
PatchBeneficiaryImportRowResponseRespuesta de `PATCH /v1/beneficiaries/imports/{id}/rows/{row_id}` con la fila tras aplicar el override y re-procesar. El bucket (`status`) puede haber cambiado si la corrección movió la fila entre `valid`, `correctable`, `fatal`, `duplicate_account` o `duplicate_alias`. -
PatchValidationImportRowRequest -
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. -
SendWebhookTestAttributes -
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`. Tres rutas de actualización: - Solo `label`: se sanea y persiste. - `account_number` nuevo: re-deriva `account_type`, `bank_code` y `bank_name` con las mismas reglas que `POST /v1/beneficiaries`. - Solo `bank_code`: válido únicamente cuando el beneficiario existente es de tipo `phone`; para CLABE/card se ignora silenciosamente. Dispara el evento de auditoría `beneficiary.phone_bank_updated` cuando el código cambia. -
UpdateBeneficiaryResponseRespuesta de `PUT /v1/beneficiaries/{id}` con el beneficiario actualizado. -
UpdateUserRetryPolicyRequestCuerpo de la petición para actualizar la política de reintentos por defecto del usuario (aplica a futuras validaciones). -
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). -
UpdateWebhookRequest -
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. -
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.
Plans
-
PlanPlan de suscripción disponible en la plataforma. Devuelto por `GET /v1/plans` para que el usuario pueda comparar opciones y elegir un plan. -
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).
Primitives
-
DatetimeMetaDescriptor compañero presente en el bloque `meta` de cada respuesta (y en el `meta` de los payloads de webhooks salientes). Permite a los clientes afirmar el contrato de zona horaria sin parsear el spec. -
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.
Retry policy
-
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.
Users
-
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. -
UserSessionRepresenta una sesión JWT activa (o histórica) del usuario autenticado. Una sesión equivale a un par cookie/JWT minted en login, 2FA verify o el re-issue de password-change; cada sesión queda anclada a un `jti` embebido en el JWT y registrada en `user_sessions` con su IP/UA y ventana de vida. Surface user-facing introducida en v1.49.5 (ADR-0089). -
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. Introducido en v1.49.5 (ADR-0089).
Validations
-
ValidationRegistro completo de una validación SPEI en forma de JSON:API. Devuelto por `GET /v1/validations/{id}` y `POST /v1/validate` síncrono. -
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 del job de 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. -
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. -
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`).
Webhooks
-
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.