Consultas RUNT y caché

Dos endpoints consultan el RUNT en vivo:

Endpoint	Consulta	Scope
`POST /consults/vehicle`	Vehículo por placa: datos, SOAT y tecnomecánica	`consults.vehicle`
`POST /consults/license`	Licencias por documento y primer apellido	`consults.license`

A diferencia de los endpoints de flota, funcionan con cualquier placa o documento: no hace falta que esté registrado en tu organización.

Consultar un vehículo

curl -X POST https://api.notiauto.co/v1/consults/vehicle \
  -H "X-API-Key: TU_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "plate": "ABC123",
    "type_document": "C",
    "document": "12345678"
  }'

El RUNT exige la placa y el documento del propietario. Con la placa sola no responde.

{
  "success": true,
  "cached": false,
  "data": {
    "plate": "ABC123",
    "marca": "CHEVROLET",
    "linea": "NPR",
    "modelo": "2020",
    "color": "BLANCO",
    "tipo_servicio": "Particular",
    "clase_vehiculo": "CAMION",
    "estado": "ACTIVO",
    "no_serie": "...",
    "no_motor": "...",
    "no_chasis": "...",
    "no_vin": "...",
    "fecha_matricula": "2020-03-14"
  },
  "soat": {
    "numero": "...",
    "estado": "VIGENTE",
    "vigente": true,
    "fecha_expedicion": "2026-01-15",
    "fecha_vencimiento": "2027-01-15",
    "aseguradora": "SEGUROS DEL ESTADO"
  },
  "rtm": {
    "numero": "...",
    "fecha_revision": "2025-11-30",
    "fecha_vencimiento": "2026-11-30",
    "vigente": true
  }
}

soat y rtm traen la más reciente de cada tipo, no el histórico.

Consultar licencias

curl -X POST https://api.notiauto.co/v1/consults/license \
  -H "X-API-Key: TU_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{ "type_document": "C", "document": "12345678", "first_surname": "GOMEZ" }'

first_surname es obligatorio y debe contener el primer apellido de la persona, tal como aparece en su documento.

{
  "success": true,
  "cached": false,
  "data": {
    "nombres": "ANA",
    "apellidos": "GOMEZ",
    "documento": "12345678",
    "estado_conductor": "ACTIVO"
  },
  "licenses": [
    {
      "numero": "123456789",
      "category": "B1",
      "expedition_date": "2021-05-10",
      "expiration_date": "2031-05-10",
      "status": "VIGENTE",
      "sustrato": "ACTIVA"
    }
  ],
  "total_licenses": 1
}

Una persona puede tener varias categorías, y cada una llega como un elemento propio en licenses. Las categorías que el RUNT reporta como NA se descartan.

Dos campos parecidos que no son lo mismo:

status lo calcula NotiAuto comparando expiration_date contra hoy: VIGENTE o VENCIDA.
sustrato es el estado que reporta el RUNT para el documento físico de la licencia, por ejemplo ACTIVA.

Una licencia puede tener sustrato: "ACTIVA" y status: "VENCIDA" al mismo tiempo. Para saber si la persona puede conducir hoy, mira status.

Tipos de documento

type_document es un código de una letra, y las listas válidas son distintas para vehículo y para persona:

Código	Documento	Vehículo	Persona
`C`	Cédula de ciudadanía	Sí	Sí
`E`	Cédula de extranjería	Sí	Sí
`N`	NIT	Sí	No
`P`	Pasaporte	Sí	Sí
`D`	Carnet diplomático	Sí	Sí
`U`	Registro civil	Sí	Sí
`T`	Tarjeta de identidad	Sí	Sí
`Y`	Permiso por Protección Temporal	No	Sí

Un vehículo puede estar a nombre de una empresa, así que acepta N (NIT). Una licencia es de una persona, así que no. A la inversa, Y solo aplica a personas.

Mandar un código de la lista equivocada devuelve 422.

Validación

Campo	Regla	Ejemplos válidos
`plate`	`ABC123`, `123ABC` o `ABC12D`. No distingue mayúsculas	`ABC123`, `abc123`, `123ABC`, `ABC12D`
`document`	Solo dígitos, de 6 a 10	`12345678`
`type_document`	Un código de la tabla de arriba	`C`
`first_surname`	Primer apellido de la persona, máximo 100 caracteres	`GOMEZ`

Cualquier cosa fuera de eso devuelve 422 sin llegar al RUNT.

El caché

Cada consulta se cachea 24 horas, con esta clave:

Vehículo: (placa, tipo de documento, documento)
Licencia: (tipo de documento, documento, primer apellido)

El campo cached de la respuesta te dice de dónde salió: false es una consulta nueva al RUNT, true es caché.

Para forzar una consulta nueva, manda refresh: true:

curl -X POST https://api.notiauto.co/v1/consults/vehicle \
  -H "X-API-Key: TU_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{ "plate": "ABC123", "type_document": "C", "document": "12345678", "refresh": true }'

Úsalo cuando sepas que algo cambió —un SOAT que se acabó de renovar—, no por costumbre. Una consulta al RUNT es lenta y el caché existe por una razón.

Qué se cachea y qué no

Esta es la parte que conviene entender bien, porque determina si vale la pena reintentar:

Situación	¿Se cachea?	Consecuencia
Consulta completa y correcta	Sí, 24 horas	Las siguientes salen del caché
El RUNT no responde, o rechaza (503)	No	Reintentar más tarde puede funcionar
Falla una sección principal (SOAT o RTM)	No	Llega `null` en esa sección; reintentar puede completarla
Falla solo una sección secundaria	Unos minutos, no 24 horas	Se reintenta pronto por su cuenta

Un fallo nunca se queda pegado 24 horas. Ese es el punto.

`null` no significa “no tiene”

Una consulta puede responder 200 con soat en null:

{
  "success": true,
  "cached": false,
  "data": { "plate": "ABC123", "marca": "CHEVROLET" },
  "soat": null,
  "rtm": { "vigente": true }
}

Lo mismo aplica a rtm. Y en POST /consults/license, un array licenses vacío con total_licenses: 0 sí es una respuesta válida del RUNT: esa persona no tiene licencias vigentes registradas.

Errores

Código	Causa
402	Sin saldo de consultas. Compra una bolsa; reintentar no sirve
403	La key no tiene `consults.vehicle` o `consults.license`, o el plan no incluye API
422	Placa, documento o tipo de documento con formato inválido
429	Pasaste las 60 peticiones por minuto
503	El RUNT no respondió o rechazó la consulta. El `message` trae el detalle

Cada consulta exitosa descuenta una unidad del saldo prepago de tu organización, venga del RUNT o del caché. Una consulta que termina en 503 no cuesta nada.

Antes de perseguir un 503, revisa GET /health: el campo runt dentro de dependencies te dice si el problema es del RUNT y no tuyo.