API de prendas, embargos y garantías mobiliarias de un vehículo por placa

Qué problema resuelve

En el mostrador de un concesionario la pregunta no es «¿este carro tiene problemas?», es «¿me lo puedo llevar hoy?». Y la respuesta está partida en dos portales que no hablan entre sí: el del RUNT, que pide captcha y el documento del propietario para mostrar la bandera de gravamen y las limitaciones a la propiedad, y el del Registro de Garantías Mobiliarias, que busca por número de bien y devuelve el detalle de la prenda en una tabla ASP.NET pensada para leerse a mano, una placa a la vez. Nadie cierra una compraventa con dos pestañas abiertas y un captcha en la mitad. Estos endpoints devuelven lo mismo en JSON, en una llamada por registro, para que el bloqueo se pinte en la pantalla que ya está usando el vendedor.

Para quién sirve

Concesionarios y compraventas de usados que verifican en el mostrador, plataformas de marketplace vehicular que necesitan bloquear una publicación con prenda vigente, financieras y bancos que originan crédito con garantía sobre el vehículo, aseguradoras que revisan la titularidad antes de expedir, y equipos de tránsito o gestoría que arman el expediente de un traspaso.

Datos requeridos

• placa — para las prendas del registro de garantías mobiliarias es el ÚNICO dato: 5 a 7 caracteres alfanuméricos, con o sin guiones. Cubre AAA000, AAA00A y los formatos menos comunes (AAA00, AAAA00).
• docType y docNumber — solo para los embargos y la bandera de gravamen, que salen del RUNT: tipo y número de documento del propietario ACTIVO. El RUNT no entrega la ficha si el documento no corresponde al dueño de hoy.
• refresh — opcional. Salta el caché y vuelve a consultar el registro. Úsalo cuando acaban de levantar una prenda y necesitas la confirmación del mismo día.

Fuentes y cobertura

• Registro de Garantías Mobiliarias (garantiasmobiliarias.com.co)Registro que administra Confecámaras desde la Ley 1676 de 2013. Consultado por número de bien (la placa) devuelve, por cada folio: el folio electrónico, los acreedores a cuyo favor está la garantía, el deudor o garante con su nombre y número de documento, la fecha y hora de inscripción, y el nombre del último formulario registral radicado sobre ese folio.
• RUNT — bandera de gravamen (runt.gov.co)Dentro de informacionGeneral, los campos gravamenes y prendas responden SI/NO. Es la señal primaria de si el registro automotor considera que el vehículo está afectado, y es la que manda cuando el registro de garantías sale en blanco.
• RUNT — garantías del vehículoDetalle de cada prenda tal como la ve el registro automotor: acreedor, número y tipo de documento del acreedor, fecha de inscripción y un indicador de si esa misma garantía figura también en el registro de Confecámaras.
• RUNT — limitaciones a la propiedadLos embargos y demás medidas que impiden mover el vehículo: tipo de limitación, entidad jurídica que la ordenó, fecha de expedición, fecha de radicación y el municipio y departamento de origen.

¿Qué diferencia hay entre una prenda y un embargo sobre un vehículo?

Una prenda es voluntaria. El dueño la constituyó a favor de un acreedor —casi siempre el banco o la financiera que prestó la plata con la que se compró el carro— y quedó inscrita como garantía mobiliaria sobre el vehículo. Mientras esté vigente, el carro responde por esa deuda: se puede usar, asegurar y hasta vender, pero el traspaso necesita que el acreedor levante la garantía o autorice la operación. Es un bloqueo con un teléfono al que llamar y un número al que apuntarle: el saldo de la obligación.

Un embargo no lo pidió nadie. Lo ordena una autoridad —un juzgado, una entidad en cobro coactivo, una secretaría de tránsito— y el RUNT lo registra como limitación a la propiedad. Ahí no hay nada que negociar con el vendedor: hasta que la autoridad que la impuso levante la medida y el levantamiento llegue al registro, el vehículo no se mueve. Un embargo tiene un expediente, no un saldo.

Esa diferencia es la razón de que la API las devuelva por separado en vez de agregarlas en un solo campo «tiene problemas». Un semáforo de un solo bit obliga al vendedor a llamar para averiguar cuál de los dos casos le tocó, y son conversaciones distintas: la prenda se resuelve el mismo día con un paz y salvo del acreedor; el embargo, no.

¿Por qué una misma prenda aparece en dos registros que no coinciden?

Porque son dos sistemas con dueños distintos. El registro automotor (RUNT) guarda lo que le reportaron sobre ESE vehículo. El Registro de Garantías Mobiliarias guarda folios sobre bienes muebles en general —de un vehículo a una maquinaria o un inventario— y lo administra Confecámaras. Cuando un acreedor inscribe la garantía en Confecámaras, el RUNT la marca con un indicador propio; cuando la inscribió solo por la vía del registro automotor, el folio de Confecámaras no existe y la consulta por placa vuelve vacía.

El número al que hay que ponerle atención: medido sobre nuestro propio barrido de placas, el registro de garantías mobiliarias devuelve un folio en cerca del 3 % de las consultas. Eso NO es una tasa de acierto de la fuente. La mayoría de las placas salen con tienePrenda: false porque la mayoría de los carros, sencillamente, no tienen una garantía inscrita ahí. Lo decimos aquí, en la página del producto, porque un integrador que espere una cobertura alta va a leer los false como «no tiene prenda» y va a autorizar un traspaso que no debía autorizar.

La regla operativa que usamos nosotros: la bandera del RUNT decide SI HAY prenda; el registro de garantías mobiliarias aporta el DETALLE de esa prenda. Un tienePrenda: false del registro de garantías con la bandera del RUNT en SI significa «hay prenda y el folio no está en Confecámaras», no «no hay prenda». Al revés casi no pasa; en ese orden, sí.

Y cuando el RUNT marca la bandera pero su propio recurso de detalle viene vacío —pasa, y no es raro—, la API no se queda callada: emite una prenda con el acreedor en «Prenda vigente (sin detalle disponible)» y las fechas en null. Preferimos entregar un ítem incompleto que una lista vacía, porque una lista vacía se lee como un vehículo limpio y ese es el peor error que puede cometer este endpoint.

¿Qué significa ultimaOperacion y por qué es el campo que hay que mirar?

El registro de garantías mobiliarias no publica un estado «vigente / cancelada». Publica un folio con la historia de los formularios registrales que se le han radicado encima, y el último de esos formularios es la mejor pista del estado real de la garantía. Por eso ultimaOperacion viaja en la respuesta con el texto exacto del portal, sin normalizar.

Dos ejemplos de lo que se ve en producción: «Formulario Registral de Modificación» dice que la garantía sigue viva y que algo cambió sobre ella —monto, plazo, acreedor—; «Formulario Registral de Ejecución» dice que el acreedor arrancó el cobro de la garantía, que es la señal más fuerte que puede traer este endpoint. Un vehículo con una ejecución encima no es un vehículo que se compra hoy y se arregla después.

No convertimos ese texto a un booleano ni a un enum propio a propósito: el vocabulario es del registro, no nuestro, y aplanarlo obligaría a decidir a qué categoría pertenece un formulario que no hayamos visto todavía. Ese es exactamente el tipo de decisión que produce falsos «vehículo limpio». El campo se pasa como llega y el cliente decide cómo mostrarlo.

Mismo criterio con fechaInscripcion: llega en el formato del portal (dd/mm/aaaa hh:mm:ss, con «a. m.» y «p. m.» en español) y así se entrega. Es la fecha que va impresa en el certificado que cualquiera puede pedir con el folio, así que convertirla a ISO haría que el JSON y el papel no se parecieran.

¿Cómo se usa esto en el mostrador de un concesionario?

El orden importa más de lo que parece, porque los dos registros piden datos distintos y en el mostrador los datos llegan en un orden fijo: primero la placa del carro que te están ofreciendo, y mucho después la cédula del dueño.

¿Se puede saber si un carro tiene prenda solo con la placa?

El detalle de la prenda sí: POST /api/garantias-rgm pide únicamente la placa y devuelve el folio, los acreedores, el deudor y la fecha de inscripción, sin documento del propietario ni captcha. Lo que NO se puede con la placa sola es el veredicto completo, porque la bandera oficial de gravamen y los embargos viven en el RUNT, que exige placa más el documento del dueño actual.

¿Cómo consultar los embargos de un vehículo desde una aplicación?

Con POST /api/apto-traspaso o POST /api/consulta, enviando placa, docType y docNumber del propietario activo. El primero devuelve el semáforo aptoTraspaso más una lista bloqueos en texto; el segundo trae la ficha completa del RUNT con el bloque de antecedentes, donde cada embargo llega estructurado con su tipo de limitación, la entidad jurídica que lo ordenó, las fechas de expedición y radicación y la ciudad.

Ejemplo de solicitud

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

curl -X POST 'https://placapi.com/api/garantias-rgm' \
  -H 'x-api-key: pk_live_TU_CLAVE' \
  -H 'content-type: application/json' \
  -d '{"placa":"ABC123"}'

Ejemplo de respuesta

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

{
  "source": "garantias",
  "status": "warn",
  "data": {
    "placa": "ABC123",
    "tienePrenda": true,
    "garantias": [
      {
        "folio": "20210930000036900",
        "acreedores": [
          "ENTIDAD FINANCIERA DE EJEMPLO S.A."
        ],
        "deudor": "NOMBRE DEL DEUDOR",
        "docDeudor": "73140250",
        "fechaInscripcion": "30/09/2021 10:55:38 a. m.",
        "ultimaOperacion": "Formulario Registral de Modificación"
      }
    ],
    "fuente": "Prendas y garantías mobiliarias registradas"
  },
  "mode": "live",
  "fetchedAt": "2026-08-20T14:32:10.000Z"
}

Explicación campo por campo

Limitaciones y posibles errores

• El registro de garantías mobiliarias devuelve un folio en cerca del 3 % de las placas que consultamos. Un tienePrenda: false no equivale a «vehículo sin prenda»: equivale a «sin folio inscrito en ese registro». Si necesitas el veredicto y no el detalle, la bandera del RUNT es la que manda.
• El registro no publica un estado «vigente / cancelada». Lo más cerca es ultimaOperacion, que se entrega con el texto del portal sin normalizar; interpretarlo es decisión del cliente.
• Los embargos y la bandera de gravamen NO salen de este endpoint: salen del RUNT (apto-traspaso o consulta) y exigen el documento del propietario activo. Con la placa sola no se pueden ver.
• La búsqueda es por número de bien y nosotros enviamos la placa. Si el acreedor inscribió el vehículo con otro identificador, esa garantía no aparece consultando por placa.
• Cuando el portal está caído o tarda más de 45 segundos, la respuesta llega con status unknown y data en null. Ese caso no se cobra, y se cachea 30 minutos para no volver a golpear un portal que ya está sufriendo.
• El deudor llega con nombre y número de documento pero sin tipo de documento: el portal no lo discrimina y no lo inferimos.

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

Otras preguntas frecuentes

Seguir explorando

• API de pérdida total y siniestros por placa→
• API del RUNT: ficha completa del vehículo→
• API de consulta vehicular por placa→
• Revisar un usado antes de comprar→
• Paz y salvo de tránsito por placa→
• Documentación e integración→