API impuesto vehicular Colombia: saldo pendiente por placa

Qué problema resuelve

Cada departamento tiene su propio portal de impuesto vehicular, con su propio formulario y su propia forma de mostrar el saldo. Consolidar cuánto se debe por vehículos matriculados en distintos departamentos es inviable a mano; este endpoint normaliza esa consulta en una sola respuesta JSON.

Para quién sirve

Compraventas, gestores de trámites, flotas multi-departamento y fintechs que evalúan cargas pendientes antes de un traspaso o un crédito.

Datos requeridos

• placa — placa del vehículo.
• docType y docNumber — documento del propietario (con el que se deriva el departamento de matrícula en el RUNT).

Fuentes y cobertura

• Secretarías de hacienda departamentalSaldo del impuesto vehicular por año. Hoy con consulta en línea directa en 22 entidades: Bogotá D.C., Antioquia, Valle del Cauca, Risaralda, Santander, Boyacá, Arauca, Caldas, Cauca, Tolima, Bolívar, Córdoba, Norte de Santander, Huila, Meta, Cesar, Magdalena, Sucre, Casanare, Putumayo, Caquetá, Guaviare.
• RUNTDepartamento de matrícula del vehículo, del que depende qué secretaría gestiona el impuesto.

¿Cuánto cuesta una consulta de impuesto vehicular?

2 créditos, y solo cuando la fuente responde con la cuenta del vehículo. Si el departamento no tiene consulta en línea y la respuesta se queda en el enlace al portal oficial (data en null), el crédito se reembolsa: no cobramos por un enlace.

¿Cubre todos los departamentos?

Con consulta en línea directa cubrimos 22 de las 33 entidades: Bogotá D.C., Antioquia, Valle del Cauca, Risaralda, Santander, Boyacá, Arauca, Caldas, Cauca, Tolima, Bolívar, Córdoba, Norte de Santander, Huila, Meta, Cesar, Magdalena, Sucre, Casanare, Putumayo, Caquetá, Guaviare. Para las demás la respuesta devuelve data en null y un enlace (portalUrl) al portal oficial, sin inventar datos.

Ejemplo de solicitud

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

curl -X POST 'https://placapi.com/api/impuestos' \
  -H 'x-api-key: pk_live_TU_CLAVE' \
  -H 'content-type: application/json' \
  -d '{"placa":"ABC123","docType":"CC","docNumber":"1020304050"}'

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

Ejemplo de respuesta

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

{
  "source": "Bogotá D.C.",
  "status": "warn",
  "data": {
    "departamento": "Bogotá D.C.",
    "totalPendiente": 320000,
    "anios": [
      {
        "anio": 2025,
        "pagado": false,
        "valor": 320000
      }
    ]
  },
  "mode": "live"
}

Explicación campo por campo

Limitaciones y posibles errores

• Hay consulta en línea directa en 14 entidades: Antioquia, Arauca, Bogotá D.C., Bolívar, Caldas, Caquetá, Casanare, Córdoba, Huila, Norte de Santander, Putumayo, Risaralda, Santander y Valle del Cauca. En el resto la respuesta trae data en null, status "info" y el enlace (portalUrl) al portal oficial correspondiente.
• Algunos departamentos publican QUÉ vigencias se deben pero no cuánto. En ese caso llega deudaSinMonto: true con la lista en vigenciasAdeudadas y totalPendiente en 0: es deuda real, no un paz y salvo. Y si la entidad afirma que la placa no tiene deuda en cobro llega sinDeudaEnCobro: true, que tampoco es un paz y salvo: puede haber una declaración pendiente o errada. Nunca se estima un monto que la fuente no dé.
• Bogotá lista lo que está EN MORA. Que no haya filas no equivale a estar al día, así que ahí la respuesta cae al portal oficial en vez de afirmar un paz y salvo. Su formulario además no acepta placas de moto.
• Un municipio con tránsito propio (Cereté, Arjona, Los Patios, Villamaría…) puede no estar en el portal de su gobernación aunque la placa sí sea de ese departamento.
• Un pago reciente puede tardar en reflejarse en el portal departamental.
• PlacApi no recauda impuestos; reporta el saldo que publica cada secretaría de hacienda.
• El impuesto vive en su propio endpoint (/api/impuestos); no viene dentro de la ficha del RUNT de /api/consulta.

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

Otras preguntas frecuentes

Seguir explorando

• API SIMIT (multas)→
• API FASECOLDA (avalúo)→
• API consulta vehicular (ficha RUNT)→
• Precios por consulta→
• API de pico y placa por ciudad→
• Avalúo por código FASECOLDA→