API de traspaso de vehículos en Colombia: saber si un carro se puede traspasar

Qué problema resuelve

Un traspaso que se cae en la ventanilla del organismo de tránsito ya costó plata: el comprador giró, el vendedor firmó y el registro no deja. Los bloqueos que lo impiden están publicados en el RUNT, pero su portal pide captcha, se consulta de a una placa y devuelve una ficha de cuarenta campos donde hay que saber cuáles cinco importan y cómo se llaman. Este endpoint hace esa lectura por ti: pregunta lo que pregunta el trámite y responde sí o no, con el motivo. La alternativa —integrar la ficha completa y escribir la regla en cada cliente— funciona hasta que dos equipos la escriben distinto.

Para quién sirve

Concesionarios y patios de usados que revisan un vehículo antes de recibirlo en parte de pago; plataformas de compraventa que validan una publicación antes de aceptarla; gestores y trámites de traspaso; aseguradoras; empresas de leasing y renting que necesitan saber si su garantía es transferible; fintechs de crédito vehicular; y cualquier aplicación que prefiera mostrarle a un usuario un semáforo en vez de una ficha técnica.

Datos requeridos

• placa — la placa del vehículo, carro o moto. De 5 a 7 caracteres alfanuméricos; los guiones y espacios se ignoran.
• docType — tipo de documento del propietario: CC, CE, NIT, PA, TI, CD, PPT o RC. Se aceptan alias comunes (PAS y PASAPORTE se normalizan a PA; P.P.T. y P.P., como lo abrevia la tarjeta de propiedad, se normalizan a PPT).
• docNumber — número de documento del propietario ACTIVO. No sirve el del comprador ni el del dueño anterior: con esos la respuesta es 404 con code propietario_no_coincide, que no es lo mismo que un aptoTraspaso en false.
• refresh — opcional. Salta el caché de 24 horas y vuelve a consultar el RUNT. Es la palanca para verificar un levantamiento de prenda registrado hoy mismo; una consulta refrescada con datos siempre cobra.

Fuentes y cobertura

• RUNT (runt.gov.co)De la ficha del vehículo salen las cinco señales: los campos tieneGravamenes y prendas de informacionGeneral, el arreglo de limitaciones a la propiedad, el de garantías mobiliarias y estadoDelVehiculo. El endpoint no hace un scrape adicional: reutiliza la misma consulta que alimenta la ficha completa, y por eso comparte su caché.
• RGM de ConfecámarasEl RUNT marca la bandera de prenda, pero no dice quién es el acreedor. Ese detalle —acreedor, deudor o garante con su documento, folio electrónico, fecha de inscripción y última operación— está en el registro de garantías mobiliarias y se consulta aparte con /api/garantias-rgm, que cuesta 1 crédito y solo pide la placa.

¿Qué bloquea un traspaso en Colombia?

El endpoint marca aptoTraspaso en false cuando encuentra al menos una de cinco condiciones. Cada una llega dos veces en la respuesta, a propósito: como una frase en el arreglo bloqueos, lista para mostrarle a una persona sin reescribirla, y como un dato estructurado dentro de detalle, para decidir en código sin hacer coincidencia de texto. Si no hay ninguna, bloqueos llega vacío y aptoTraspaso es true.

¿Cómo leer status: ok, warn y danger?

status califica el HALLAZGO, no la llamada. Las tres respuestas son HTTP 200 y las tres cobran 1 crédito, porque en las tres se entregó el dato que se vino a comprar. Confundir esto es el error de integración más común: tratar warn o danger como un fallo y reintentar la consulta produce un segundo cargo por el mismo resultado.

status ok significa aptoTraspaso en true y bloqueos vacío: ninguna de las cinco condiciones apareció y el registro está ACTIVO. Es la respuesta que deja pasar el flujo.

status danger significa que el bloqueo es patrimonial: gravamen, prenda, limitación a la propiedad o garantía mobiliaria. Alguien tiene un derecho inscrito sobre ese vehículo y hay que levantarlo antes de traspasar. Es el caso que conviene frenar en seco en un flujo de compraventa.

status warn queda para el caso en el que no hay derechos de terceros pero el estado del registro no es ACTIVO. No es un vehículo comprometido; es un registro que hay que revisar en el organismo de tránsito antes de intentar el trámite. Separar warn de danger permite que una plataforma muestre una advertencia en un caso y un bloqueo duro en el otro, sin leer el texto de los bloqueos.

Y hay un cuarto caso que no es un status sino un código HTTP: el 404 con code propietario_no_coincide. Significa que el documento enviado no corresponde a un propietario activo de esa placa. En un flujo de compraventa eso suele ser información valiosa por sí sola —quien dice ser el dueño no figura como tal— pero no es un aptoTraspaso en false, y tratarlo así le pondría un impedimento inventado a un vehículo que quizá esté limpio.

¿Qué NO responde este endpoint?

El semáforo mira cinco cosas del registro automotor y nada más. Decirlo explícitamente evita la peor forma de fallar: que alguien lea aptoTraspaso en true como una garantía de que el trámite va a salir.

No mira multas ni comparendos: eso lo consolida /api/multas por placa más documento, a 1 crédito. No verifica el SOAT ni la tecnomecánica, que vienen con su histórico completo en la ficha de /api/consulta. No liquida el impuesto vehicular —ningún departamento lo expone por API— aunque /api/impuestos resuelve gratis dónde está matriculado el vehículo y enlaza al portal que sí lo liquida. No consulta el historial de pérdida total, que vive en /api/perdida-total con datos de FASECOLDA desde 2008 y cuesta 2 créditos. Y no valida la identidad ni la capacidad de las partes.

Tampoco es un certificado de tradición. Es la lectura, en el momento de la consulta, de lo que el RUNT publica en la ficha del vehículo. Los requisitos exactos del traspaso los fija el organismo de tránsito donde se haga el trámite, y pueden incluir documentos que ningún registro expone por consulta.

¿Cómo saber si un carro se puede traspasar en Colombia?

Hay que revisar cinco cosas en el registro automotor del RUNT: que no tenga gravámenes, que no tenga prenda vigente, que no tenga limitaciones a la propiedad (los embargos entran aquí), que no tenga garantías mobiliarias inscritas y que el estado del vehículo sea ACTIVO. Este endpoint hace esas cinco lecturas en una llamada por placa y documento del propietario, y devuelve aptoTraspaso en true o false con la lista de los bloqueos que encontró. Cuesta 1 crédito y responde entre 2 y 4 segundos.

¿Qué significa que un vehículo tenga prenda?

Que hay una garantía inscrita sobre el vehículo, típicamente porque se compró financiado y el acreedor la registró para respaldar el crédito. Mientras esa prenda esté vigente el registro no permite el traspaso, aunque el vendedor esté al día y el vehículo no tenga ningún otro problema. En la respuesta aparece como detalle.tienePrendas en true y como el bloqueo Tiene prenda vigente. El RUNT solo marca la bandera; para saber quién es el acreedor, el folio electrónico y la fecha de inscripción hay que consultar el registro de garantías mobiliarias con /api/garantias-rgm.

Ejemplo de solicitud

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

curl -X POST 'https://placapi.com/api/apto-traspaso' \
  -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).

{
  "source": "vehiculo",
  "status": "danger",
  "data": {
    "placa": "ABC123",
    "aptoTraspaso": false,
    "estado": "ACTIVO",
    "bloqueos": [
      "Tiene prenda vigente",
      "Garantía mobiliaria sobre el vehículo (1)"
    ],
    "detalle": {
      "tieneGravamenes": false,
      "tienePrendas": true,
      "limitaciones": 0,
      "garantias": 1,
      "estadoDelVehiculo": "ACTIVO"
    }
  },
  "mode": "live",
  "fetchedAt": "2026-07-24T15:04:05.000Z"
}

Explicación campo por campo

Limitaciones y posibles errores

• No es un certificado de tradición ni de libertad. Es la lectura, en el momento de la consulta, de lo que el RUNT publica en la ficha del vehículo.
• aptoTraspaso en true no promete que el trámite salga. No mira multas, impuesto, SOAT, tecnomecánica ni la documentación de las partes; el organismo de tránsito donde se haga el traspaso fija sus propios requisitos.
• El documento tiene que ser el del propietario ACTIVO. Con el del dueño anterior o el del comprador la respuesta es 404 con code propietario_no_coincide, no un aptoTraspaso en false.
• detalle.limitaciones y detalle.garantias son conteos, no descripciones: dicen cuántas hay, no cuál es cada una ni a favor de quién. El detalle de las prendas está en /api/garantias-rgm.
• Si el RUNT no responde, la respuesta es 502 con code source_error y no cobra crédito; ahí reintentar sí sirve. Un 404 es definitivo y reintentarlo devuelve lo mismo.
• El caché es de 24 horas por placa + documento. Un levantamiento de prenda registrado hoy puede tardar hasta un día en verse, y el escape es refresh en true, que vuelve a consultar el RUNT y vuelve a cobrar.

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

Otras preguntas frecuentes

Seguir explorando

• Consulta masiva: verificar un inventario completo→
• API del RUNT: la ficha de la que deriva el semáforo→
• API de consulta vehicular por placa→
• Revisar un carro usado antes de comprarlo→
• Paz y salvo de tránsito, sin escribir código→
• Generar API key y probar en el sandbox→