API de consulta vehicular completa: todas las fuentes en una llamada

Qué problema resuelve

Un informe vehicular completo obliga a orquestar ocho integraciones con ocho modos de falla distintos, y a decidir qué hacer cuando la tercera se cae a mitad del recorrido. Ese trabajo —la concurrencia, los reintentos, el caché por fuente y la normalización de campos que cada registro escribe a su manera— es el que absorbe este endpoint. El que integra hace una llamada y recibe un solo objeto con todo lo que respondió, y cada bloque dice por sí mismo si trajo dato o no.

Para quién sirve

Concesionarios y plataformas de carros usados que arman el informe de un vehículo antes de venderlo, peritos y talleres que certifican estado, aseguradoras que suscriben pólizas, financieras que evalúan un vehículo como garantía, y cualquier producto que hoy encadena a mano varias consultas de PlacApi y quiere una sola.

Datos requeridos

• placa — placa del vehículo, de 5 a 7 caracteres alfanuméricos.
• docType y docNumber — tipo y número de documento del propietario. El RUNT exige que sea el del propietario ACTIVO: si no coincide, la consulta falla y no cobra.
• primerApellido — opcional pero recomendado: sin él, el bloque licencia puede llegar vacío. Lo pide la fuente desde agosto de 2026.
• ciudad o lat/lng — opcional: filtra el pico y placa a esa ciudad y agrega picoYPlaca.ubicacion. Sin ubicación devuelve todas las ciudades monitoreadas.

Fuentes y cobertura

• RUNT — Registro Único Nacional de TránsitoFicha del vehículo, datos técnicos, histórico de trámites, SOAT y tecnomecánica con todas sus vigencias, garantías, limitaciones y la licencia de conducción del propietario.
• SIMITMultas y comparendos del vehículo, con el departamento, el estado de cartera y el detalle de los acuerdos de pago.
• FASECOLDAAvalúo comercial del vehículo y la ficha técnica de la guía de valores, con su origen para saber si salió por código o por catálogo.
• Secretarías de Hacienda departamentales y distritalesImpuesto vehicular del año en curso y los saldos pendientes donde el departamento los publica.

¿Qué trae la consulta full que no traiga la consulta normal?

La consulta normal (/api/consulta) trae el bundle vehicular. La full agrega la licencia de conducción del propietario por la misma cédula y devuelve todo en una sola respuesta, incluidos los históricos de SOAT, tecnomecánica y trámites.

¿Cuánto cuesta una consulta full?

3 créditos por consulta, frente a los 8 que costarían las fuentes por separado. Si un bloque no responde, ese bloque llega vacío y la llamada se cobra igual porque las demás sí se consultaron.

Ejemplo de solicitud

POST https://placapi.com/api/consulta-full. Autenticación por API key en el header x-api-key. Los datos del ejemplo son ficticios.

curl -X POST 'https://placapi.com/api/consulta-full' \
  -H 'x-api-key: pk_live_TU_CLAVE' \
  -H 'content-type: application/json' \
  -d '{"placa":"ABC123","docType":"CC","docNumber":"1020304050","primerApellido":"PÉREZ","ciudad":"Bogotá"}'

Parámetros, errores y ejemplos en cURL, JavaScript y Python: documentación de POST /api/consulta-full.

Ejemplo de respuesta

Respuesta JSON (fragmento con los campos de esta consulta; la API integral devuelve todas las fuentes en el mismo objeto).

{
  "vehicle": {
    "plate": "ABC123",
    "marca": "MAZDA",
    "linea": "CX-30",
    "modelo": 2022
  },
  "soat": {
    "vigente": true,
    "vence": "2026-11-30"
  },
  "rtm": {
    "vigente": true,
    "vence": "2027-02-14"
  },
  "simit": {
    "totalDeuda": 0,
    "comparendos": []
  },
  "impuesto": {
    "anio": 2026,
    "saldo": 0
  },
  "avaluo": {
    "valor": 78400000,
    "origen": "codigo"
  },
  "picoYPlaca": {
    "aplica": false,
    "ubicacion": "Bogotá"
  },
  "licencia": {
    "vigente": true,
    "categorias": [
      "B1",
      "C1"
    ]
  },
  "mode": "live",
  "fetchedAt": "2026-09-16T14:03:11.000Z"
}

Explicación campo por campo

Limitaciones y posibles errores

• Cuesta 3 créditos, no 1. Sigue siendo la mitad de lo que valen sueltas las fuentes que reúne, pero no es la consulta para un chequeo rápido: para eso está /api/consulta.
• El documento tiene que ser el del propietario ACTIVO del vehículo. Es el modo de falla dominante de la consulta por placa; si solo se tiene el VIN, la vía es /api-consulta-por-vin-colombia.
• Cada bloque llega null o vacío cuando su fuente no reportó nada para ese vehículo, y eso no siempre significa que el dato no exista: significa que el registro no lo publicó.
• El caché es por fuente y no por llamada: una consulta puede traer el RUNT desde caché y el SIMIT en vivo. Es lo que evita pagar ocho veces por lo que no cambió.

Códigos de error del endpoint (401, 402, 429, 5xx) en la referencia de errores.

Otras preguntas frecuentes

Seguir explorando

• API de consulta vehicular por placa→
• API del RUNT→
• API SIMIT: multas por placa→
• API de avalúo FASECOLDA→
• API de consulta por VIN→
• API de licencias de conducción→
• Documentación e integración→
• Documentación del endpoint POST /api/consulta-full→