API impuesto vehicular Colombia: saldo pendiente por placa

PlacApi expone un endpoint REST dedicado, POST /api/impuestos, para consultar el impuesto vehicular de un vehículo colombiano. Con la placa y el documento del propietario, PlacApi deriva el departamento de matrícula desde el RUNT, consulta la secretaría de hacienda correspondiente y devuelve en JSON el total pendiente y el desglose por año.

Probar en el sandbox y generar API keyVer precios por consulta

¿No eres desarrollador? Consulta el RUNT por placa aquí sin escribir código.

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: Bogotá D.C., Antioquia y Valle del Cauca.
  • RUNTDepartamento de matrícula del vehículo, del que depende qué secretaría gestiona el impuesto.

¿Cubre todos los departamentos?

Con consulta en línea directa cubrimos Bogotá D.C., Antioquia y Valle del Cauca. Para los demás departamentos la respuesta devuelve data en null y un enlace (portalUrl) al portal oficial, sin inventar datos.

¿Incluye intereses de mora?

El valor por año refleja lo que reporta la secretaría de hacienda, que suele incluir intereses; revisa el desglose en data.anios[].

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.

Ejemplo cURL de la solicitud
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"}'

Ejemplo de respuesta

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

Ejemplo de respuesta JSON
{
  "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

CampoTipoDescripción
sourcestringSecretaría o departamento que gestiona el impuesto (ej. "Bogotá D.C.").
statusstring"ok" sin saldo, "warn" con saldo pendiente, "info" si el departamento no tiene consulta en línea.
data.departamentostringDepartamento de matrícula que gestiona el impuesto.
data.totalPendientenumber (COP)Total pendiente por pagar sumando todos los años.
data.anios[].anionumberAño gravable del impuesto.
data.anios[].pagadobooleantrue si ese año está pagado.
data.anios[].valornumber (COP)Valor del impuesto de ese año.
datanullEs null cuando el departamento no tiene consulta en línea; entonces la respuesta trae portalUrl al portal oficial y status "info".

Tiempo de respuesta

Entre 30 y 90 segundos la primera vez —es lo que tardan los portales oficiales en responder—. Reconsultar la misma placa es casi instantáneo porque el resultado queda en caché.

Precio y cobro

1 crédito por consulta con datos, desde 349 COP. El precio por crédito baja por volumen: 349 COP desde 30, 249 COP desde 1.000, 149 COP desde 5.000, 139 COP desde 10.000, 119 COP desde 20.000, 99 COP desde 50.000. Los créditos se compran por adelantado (mínimo 30 = 10.470 COP), no vencen y no hay mensualidad. El mismo precio aplica por la web y por API. Solo se cobra cuando la consulta devuelve datos; por API, las consultas sin resultado (404) tienen 10 gratis al mes por cada tipo de respuesta sin datos y después cobran igual.

Caché y actualización

El saldo del impuesto se cachea por horas o días según el departamento; conviene refrescar antes de un trámite de traspaso.

Seguridad y privacidad

La placa y el documento se usan solo para ejecutar la consulta; el resultado queda en caché temporal. No se almacenan datos de tarjetas (los pagos los procesa Wompi). Ver privacidad y seguridad.

Limitaciones y posibles errores

  • Solo hay consulta en línea directa para Bogotá D.C., Antioquia y Valle del Cauca; para el resto de departamentos la respuesta trae data en null, status "info" y el enlace (portalUrl) al portal oficial correspondiente.
  • 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

¿Necesito el documento del propietario?

+

Sí. Con placa y documento PlacApi deriva el departamento de matrícula desde el RUNT y consulta la secretaría correcta.

Seguir explorando

Última revisión: 27 de julio de 2026 · Versión de la API: v1 · Fuentes y metodología

Contacto