Endpoint: impuesto vehicular por placa

Estado del impuesto vehicular por departamento. El departamento se resuelve desde el organismo de tránsito del RUNT por placa. En 22 departamentos (Antioquia, Arauca, Bogotá D.C., Bolívar, Boyacá, Caldas, Caquetá, Casanare, Cauca, Cesar, Córdoba, Guaviare, Huila, Magdalena, Meta, Norte de Santander, Putumayo, Risaralda, Santander, Sucre, Tolima y Valle del Cauca) data trae el histórico por vigencia en anios —año, valor, si está pagado y, cuando la fuente la publica, la fecha límite— más totalPendiente. En Cundinamarca la gobernación publica sus facturas oficiales por vigencia, pero no cuánto se debe hoy: data llega con deudaSinMonto cuando hay facturas sin pagar, o al día con vigenciasPagadas cuando la factura del año en curso existe y todas están pagadas. Nunca con un monto. Sin la factura del año en curso, data viene null. En el resto, data viene null y el valor está en portalUrl + el mensaje de error. `resultado` dice siempre en qué caso está la respuesta, para ramificar sin leer el texto. Con data (cobra 2): con_deuda, deuda_sin_monto, al_dia y sin_deuda_en_cobro. Sin data (no cobra): vehiculo_no_encontrado, documento_no_corresponde, no_sujeto (moto de hasta 125 cc o servicio público, Ley 488 de 1998, art. 141), sin_resultado (la entidad respondió y no tiene estado de cuenta que dar), sin_consulta_en_linea (solo portalUrl), departamento_no_identificado y fuente_no_disponible. El mismo campo viaja en el bloque impuestos de /api/consulta-full, que agrega no_consultado cuando no hubo ficha del vehículo. ⚠️ `deudaSinMonto: true` es deuda real. Algunos departamentos publican QUÉ vigencias se deben pero no cuánto: en ese caso totalPendiente llega en 0, las vigencias van en vigenciasAdeudadas y status es warn. No leas `totalPendiente: 0` como paz y salvo sin mirar `deudaSinMonto`. Nunca estimamos un monto que la fuente no dé. ⚠️ `sinDeudaEnCobro: true` tampoco es paz y salvo. Cuando la entidad afirma que esa placa no tiene deuda EN COBRO, data llega con sinDeudaEnCobro: true, totalPendiente en 0 y status info — nunca ok. Es un dato, pero acotado: puede haber una declaración pendiente o presentada con error que todavía no entra en cobro, y la advertencia viaja en error. 2 créditos, y solo cuando la fuente responde por la placa: cuenta con vigencias, deudaSinMonto o sinDeudaEnCobro. Si el departamento no tiene consulta en línea, o la fuente rechaza el documento o la placa, data viene null, el valor está en portalUrl + error, y se reembolsa. ℹ️ Cuando la entidad rechaza el documento o la placa, la respuesta trae además code (y errorCode, con el mismo valor) del contrato: propietario_no_coincide, vehiculo_no_registrado o consulta_sin_resultado. Va dentro de un `200`, no de un `404`: la respuesta sigue teniendo valor —el enlace al portal oficial— y este endpoint nunca cobra un sin-resultado. La única respuesta que no es 200 es fuente_no_disponible: `502` con code: source_error, como en el resto de la API; no cobra y reintentar sirve.

Para qué sirve, quién lo usa y cuánto cuesta: API impuesto vehicular.

Cuerpo de la solicitud

{
  "placa": "ABC123",
  "docType": "CC",
  "docNumber": "1020304050"
}

Ejemplos por lenguaje

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"}'

const res = await fetch("https://placapi.com/api/impuestos", {
  method: "POST",
  headers: {
    "x-api-key": "pk_live_TU_CLAVE",
    "content-type": "application/json",
  },
  body: JSON.stringify({"placa":"ABC123","docType":"CC","docNumber":"1020304050"}),
});
const data = await res.json();

import requests

res = requests.post(
    "https://placapi.com/api/impuestos",
    headers={"x-api-key": "pk_live_TU_CLAVE"},
    json={"placa":"ABC123","docType":"CC","docNumber":"1020304050"},
)
data = res.json()

Respuesta exitosa

{
  "source": "Risaralda",
  "status": "warn",
  "resultado": "deuda_sin_monto",
  "data": {
    "departamento": "Risaralda",
    "anios": [
      {
        "anio": 2024,
        "valor": 34000,
        "pagado": true
      },
      {
        "anio": 2025,
        "valor": 305000,
        "pagado": true
      },
      {
        "anio": 2026,
        "valor": 0,
        "pagado": false
      }
    ],
    "totalPendiente": 0,
    "deudaSinMonto": true,
    "vigenciasAdeudadas": [
      2026
    ]
  },
  "mode": "live",
  "fetchedAt": "2026-07-24T15:04:05.000Z",
  "cost": 2
}

Errores y cobro

Cuesta 2 créditos cuando devuelve datos. Códigos posibles: 400 401 402 404 429 500 502 — qué significa cada uno, cuál reintentar y cuál cobra, en errores y rate limits. Autenticación por x-api-key: cómo generar la clave.