Referencia · 06

Endpoints

Cinco rutas bajo una sola base. Todas responden JSON y, ante un error, un objeto {"codigo", "mensaje"} con código estable.

Generado a partir de openapi.yaml (OpenAPI 3.1.0, versión de la API 1.0.0). Base: https://rab-api-production.up.railway.app.

Rutas

POST /v1/verificaciones — Pedir una verificacion
GET /v1/verificaciones/{verificacion_id} — Sondear una verificacion
GET /v1/verificaciones — Base de reportes emitidos del socio
GET /v1/cuenta/consumo — Consumo del socio
GET /_salud — Gate de readiness del sidecar

POST `/v1/verificaciones`

Pedir una verificacion

Crea una verificación de un solicitante por su CURP (Ruta CURP). Responde de inmediato con estado: en_proceso; el resultado se obtiene consultando o por webhook. Exige Idempotency-Key igual al solicitud_id.

Autenticación: Authorization: Bearer <llave del socio>

Parámetros

Nombre	En	Tipo	Restricciones
`Idempotency-Key` obligatorio	encabezado	string \| null
`X-Canal`	encabezado	`"api"` \| `"mcp"`	opcional; ausente es `api`. El canal MCP envía `mcp`. Otro valor responde `400 peticion_invalida`.

Cuerpo

PeticionDeVerificacion (JSON, máximo 64 KB)

Respuesta 200

RespuestaDeVerificacion

Errores posibles

Ejemplo

curl -X POST "$RAB/v1/verificaciones" \
  -H "Authorization: Bearer $RAB_LLAVE" \
  -H "Idempotency-Key: 7f3c2a9e-5b1d-4e8a-9c0f-2d6b8a1e4f70" \
  -H "Content-Type: application/json" \
  -d '{
    "solicitud_id": "7f3c2a9e-5b1d-4e8a-9c0f-2d6b8a1e4f70",
    "solicitante": { "curp": "<CURP del solicitante>" },
    "consentimiento": {
      "otorgado": true,
      "otorgado_en": "2026-09-22T16:05:00-06:00",
      "version_aviso": "aviso-2026-09",
      "evidencia_id": "ev-000123"
    },
    "webhook_url": "https://tu-dominio.mx/revisame/eventos"
  }'

GET `/v1/verificaciones/{verificacion_id}`

Sondear una verificacion

Devuelve el estado actual de una verificación de tu cuenta. Úsalo para sondear hasta emitida o no_concluyente. Una verificación de otra cuenta responde 404, nunca 403.

Autenticación: Authorization: Bearer <llave del socio>

Parámetros

Nombre	En	Tipo	Restricciones
`verificacion_id` obligatorio	ruta	string	largo ≤ 200

Respuesta 200

RespuestaDeVerificacion

Errores posibles

Ejemplo

curl "$RAB/v1/verificaciones/$VERIFICACION_ID" \
  -H "Authorization: Bearer $RAB_LLAVE"

GET `/v1/verificaciones`

Base de reportes emitidos del socio

Lista las verificaciones de tu cuenta, de la más reciente a la más vieja. Filtra por solicitud_id o estado.

Autenticación: Authorization: Bearer <llave del socio>

Parámetros

Nombre	En	Tipo	Restricciones
`solicitud_id`	query	string \| null	largo ≤ 200
`estado`	query	string \| null	largo ≤ 200
`limite`	query	integer	≥ 1, ≤ 100, por omisión 20

Respuesta 200

RespuestaDeLista

Errores posibles

Ejemplo

curl "$RAB/v1/verificaciones?estado=emitida&limite=20" \
  -H "Authorization: Bearer $RAB_LLAVE"

GET `/v1/cuenta/consumo`

Consumo del socio

Modo de cobro de tu cuenta, precio por verificación y, en modo consumo, el saldo disponible. En modo connect el saldo es null (no aplica; no es un cero).

Autenticación: Authorization: Bearer <llave del socio>

Respuesta 200

RespuestaDeConsumo

Errores posibles

Ejemplo

curl "$RAB/v1/cuenta/consumo" \
  -H "Authorization: Bearer $RAB_LLAVE"

GET `/_salud`

Gate de readiness del sidecar

Disponibilidad del servicio. Responde 200 solo si el canal está arriba y alcanza su base de datos; si no, 503. No requiere llave.

Autenticación: ninguna

Respuesta 200

RespuestaDeSalud

Errores posibles

503 base_no_alcanzable

Ejemplo

curl "$RAB/_salud"
# {"estado": "arriba", "base": "alcanzable"}

Esquemas

`PeticionDeVerificacion`

Cuerpo de POST /v1/verificaciones. Esquema cerrado: cualquier campo no declarado se rechaza con campo_desconocido. Aunque consentimiento figure como opcional en el esquema, sin él la petición se rechaza con 422 consentimiento_faltante.

Campo	Tipo	Notas
`cobro`	CobroEntrada \| null
`consentimiento`	Consentimiento \| null
`documento`	DocumentoEntrada \| null	Reservado. No enviar.
`propiedad_id`	string \| null	Identificador opaco de la propiedad en tu sistema. largo ≥ 1, largo ≤ 200
`solicitante` obligatorio	SolicitanteEntrada
`solicitud_id` obligatorio	string	Tu identificador único y opaco (recomendado: UUID). Debe coincidir con `Idempotency-Key`. No debe describir a la persona. largo ≥ 1, largo ≤ 200
`webhook_url` obligatorio	string	URL https donde recibirás `verificacion.emitida`. Usa una ruta neutra. largo ≥ 1, largo ≤ 2000

`SolicitanteEntrada`

Quién se verifica. Solo la CURP es obligatoria; no se piden más datos personales de los necesarios.

Campo	Tipo	Notas
`apellido_materno`	string \| null	largo ≥ 1, largo ≤ 200
`apellido_paterno`	string \| null	largo ≥ 1, largo ≤ 200
`curp` obligatorio	string	largo ≥ 1, largo ≤ 32
`nombre`	string \| null	largo ≥ 1, largo ≤ 200

`Consentimiento`

El permiso expreso del solicitante, como objeto versionado y auditable (no un booleano suelto).

Campo	Tipo	Notas
`evidencia_id` obligatorio	string	Referencia a la evidencia del consentimiento en tu sistema. largo ≥ 1, largo ≤ 200
`ip`	string \| null	Opcional; no es necesario enviarlo.
`otorgado` obligatorio	boolean	Debe ser `true`.
`otorgado_en` obligatorio	string (date-time)	Fecha y hora ISO 8601 con zona horaria.
`version_aviso` obligatorio	string	Versión del aviso de privacidad aceptado. largo ≥ 1, largo ≤ 200

`CobroEntrada`

Cómo paga el socio esta verificación. Es informativo para tu conciliación: el modo que rige es el configurado en tu cuenta.

Campo	Tipo	Notas
`modo` obligatorio	`"connect"` \| `"consumo"`
`payment_intent_id`	string \| null	Modo `connect`: identificador del pago del solicitante en tu plataforma. largo ≥ 1, largo ≤ 200

`DocumentoEntrada`

Ruta con documento (INE). Reservada: hoy responde 501 ruta_no_disponible. No la envíes.

Campo	Tipo	Notas
`anverso`	string \| null	largo ≤ 8000
`reverso`	string \| null	largo ≤ 8000
`tipo` obligatorio	string	largo ≥ 1, largo ≤ 200

`RespuestaDeVerificacion`

La verificación tal como la ve el socio. estado es en_proceso, emitida o no_concluyente. recomendacion solo existe cuando está emitida.

Campo	Tipo	Notas
`cobertura_fuentes`	CoberturaFuentes \| null
`cobro` obligatorio	BloqueDeCobro
`consentimiento` obligatorio	ConsentimientoRegistrado
`creado_en`	string \| null
`environment`	`"sandbox"` \| `"production"` \| null	`sandbox` o `production`.
`estado` obligatorio	string
`real_motor_e2e`	`"NO_MEDIDO"` \| null	Marca técnica de medición; ignórala.
`recomendacion`	Recomendacion \| null
`resuelto_en`	string \| null
`solicitud_id`	string \| null
`source`	`"synthetic_fixture"` \| `"motor_real"` \| null	Origen del resultado: `motor_real` o `synthetic_fixture` (datos sintéticos de prueba).
`verificacion_id` obligatorio	string
`version_prompt`	string \| null	Versión del motor que produjo la recomendación, para trazabilidad.
`vigencia_hasta`	string \| null	Hasta cuándo la verificación sigue siendo utilizable sin volver a cobrarse.

`Recomendacion`

La acción sugerida al arrendador con su respaldo. Nunca es un juicio sobre la persona.

Campo	Tipo	Notas
`accion` obligatorio	`"puede_continuar"` \| `"continuar_con_reservas"` \| `"no_continuar_todavia"`
`mensaje` obligatorio	string	largo ≥ 1, largo ≤ 2000
`siguientes_pasos`	array<PasoSugerido>	Pasos sugeridos, de catálogo cerrado; el último es siempre `DECISION_DEL_ARRENDADOR`. elementos ≤ 5
`sustento_documental` obligatorio	SustentoDocumental

`SustentoDocumental`

Qué tan sólido es el respaldo documental de la recomendación (no de la persona), con sus factores.

Campo	Tipo	Notas
`factores` obligatorio	array<Factor>	elementos ≥ 1, elementos ≤ 50
`microexplicacion`	string	Texto fijo que conviene mostrar junto al nivel. por omisión "Indica qué tan completa y consistente es la información que respalda esta recomendación. No califica a la persona."
`nivel` obligatorio	`"alto"` \| `"medio"` \| `"bajo"`
`por_que_este_nivel`	ExplicacionDelNivel \| null

`Factor`

Elemento concreto que fortalece o limita el sustento documental. codigo es de catálogo cerrado; programa contra él, no contra texto.

Campo	Tipo	Notas
`codigo` obligatorio	string
`efecto` obligatorio	`"fortalece"` \| `"limita"`
`fuente`	string \| null	De qué fuente sale el factor; `null` en los de cobertura. largo ≥ 1, largo ≤ 200
`que_se_reviso`	string \| null	Qué se consultó, en una frase. No incluye el contenido de ningún registro. largo ≥ 1, largo ≤ 2000
`que_significa`	string \| null	Qué quiere decir el resultado para la decisión del arrendador. largo ≥ 1, largo ≤ 2000
`texto` obligatorio	string	largo ≥ 1, largo ≤ 2000

`ExplicacionDelNivel`

Por qué el sustento quedó en ese nivel: un texto fijo por caso y los códigos de factor que lo definieron. Ver Acciones.

Campo	Tipo	Notas
`determinantes`	array<string>	Códigos de factor que definieron el nivel; todos aparecen en `factores`. Puede venir vacía. elementos ≤ 50
`explicacion` obligatorio	string	largo ≥ 1, largo ≤ 2000

`PasoSugerido`

Un paso sugerido al arrendador, de catálogo cerrado. Programa contra codigo; muestra texto.

Campo	Tipo	Notas
`codigo` obligatorio	string
`texto` obligatorio	string	largo ≥ 1, largo ≤ 2000

`CoberturaFuentes`

Cuántas de las fuentes que se intentaron consultar se pudieron consultar. Es independiente del sustento documental.

Campo	Tipo	Notas
`consultadas` obligatorio	integer	≥ 0, ≤ 50
`detalle`	array<FuenteConsultada>	elementos ≤ 50
`disponibles` obligatorio	integer	≥ 0, ≤ 50

`FuenteConsultada`

Una fuente y cómo le fue.

Campo	Tipo	Notas
`estado` obligatorio	`"consultada"` \| `"no_disponible"`
`fuente` obligatorio	string	largo ≥ 1, largo ≤ 200

`BloqueDeCobro`

Estado del cobro de la verificación. monto y moneda pueden venir en null al sondear: el canal no reconstruye montos que no decidió en esa llamada.

Campo	Tipo	Notas
`estatus`	string \| null	`cargada` (modo consumo), `transferencia_encolada` (modo connect) o `no_aplicada`; `null` mientras está en proceso. `transferida` está reservado.
`modo`	string \| null
`moneda`	string \| null
`monto`	number \| null
`motivo_no_aplicada`	string \| null	Por qué no se cobró, p. ej. `recomendacion_no_emitida`.

`ConsentimientoRegistrado`

Referencia al consentimiento con el que se trabajó la verificación.

Campo	Tipo	Notas
`consentimiento_id`	string \| null

`RespuestaDeLista`

Listado de verificaciones del socio, de la más reciente a la más vieja.

Campo	Tipo	Notas
`verificaciones` obligatorio	array<RespuestaDeVerificacion>

`RespuestaDeConsumo`

Consumo del socio que presenta la llave, y de nadie más.

Campo	Tipo	Notas
`modo` obligatorio	string
`moneda` obligatorio	string
`monto_por_verificacion` obligatorio	number	El precio de tu plan por verificación emitida.
`saldo`	number \| null	`null` en modo `connect`: no hay saldo que agotar.
`tenant` obligatorio	string

`RespuestaDeError`

Todo error trae un codigo estable y un mensaje fijo. El mensaje nunca repite datos de tu petición. Programa contra codigo.

Campo	Tipo	Notas
`codigo` obligatorio	`"base_no_alcanzable"` \| `"campo_desconocido"` \| `"cobro_no_verificado"` \| `"conflicto_idempotencia"` \| `"consentimiento_faltante"` \| `"consumo_agotado"` \| `"cuerpo_demasiado_grande"` \| `"curp_invalida"` \| `"error_interno"` \| `"idempotency_key_ausente"` \| `"limite_excedido"` \| `"llave_ausente"` \| `"llave_invalida"` \| `"peticion_invalida"` \| `"respuesta_retenida"` \| `"ruta_no_disponible"` \| `"verificacion_no_encontrada"` \| `"vocabulario_no_permitido"`
`mensaje` obligatorio	string

`RespuestaDeSalud`

Estado de disponibilidad del servicio.

Campo	Tipo	Notas
`base` obligatorio	string
`esquema`	`"mas_nuevo_que_el_codigo"` \| null	Normalmente ausente o `null`. `mas_nuevo_que_el_codigo` indica que la base va en una revisión posterior y compatible a la del servicio (por ejemplo, tras revertir un despliegue): el servicio sigue atendiendo y no requiere acción de tu parte.
`estado` obligatorio	string
`version`	string \| null

Endpoints

Rutas

POST /v1/verificaciones

Parámetros

Cuerpo

Respuesta 200

Errores posibles

Ejemplo

GET /v1/verificaciones/{verificacion_id}

Parámetros

Respuesta 200

Errores posibles

Ejemplo

GET /v1/verificaciones

Parámetros

Respuesta 200

Errores posibles

Ejemplo

GET /v1/cuenta/consumo

Respuesta 200

Errores posibles

Ejemplo

GET /_salud

Respuesta 200

Errores posibles

Ejemplo

Esquemas

PeticionDeVerificacion

SolicitanteEntrada

Consentimiento

CobroEntrada

DocumentoEntrada

RespuestaDeVerificacion

Recomendacion

SustentoDocumental

Factor

ExplicacionDelNivel

PasoSugerido

CoberturaFuentes

FuenteConsultada

BloqueDeCobro

ConsentimientoRegistrado

RespuestaDeLista

RespuestaDeConsumo

RespuestaDeError

RespuestaDeSalud

POST `/v1/verificaciones`

GET `/v1/verificaciones/{verificacion_id}`

GET `/v1/verificaciones`

GET `/v1/cuenta/consumo`

GET `/_salud`

`PeticionDeVerificacion`

`SolicitanteEntrada`

`Consentimiento`

`CobroEntrada`

`DocumentoEntrada`

`RespuestaDeVerificacion`

`Recomendacion`

`SustentoDocumental`

`Factor`

`ExplicacionDelNivel`

`PasoSugerido`

`CoberturaFuentes`

`FuenteConsultada`

`BloqueDeCobro`

`ConsentimientoRegistrado`

`RespuestaDeLista`

`RespuestaDeConsumo`

`RespuestaDeError`

`RespuestaDeSalud`