API de pérdida total por placa: historial de siniestros de un vehículo

Qué problema resuelve

El historial de siniestros existe y es público, pero está detrás de un trámite: hay que aceptar términos, registrar un correo, esperar el código de acceso que llega a ese correo, validarlo y recién ahí consultar una placa — y el portal topa alrededor de diez consultas al día por correo y por IP. Eso funciona para quien revisa un carro; no funciona para una compraventa que verifica veinte al día, ni para un marketplace que quiere marcar las publicaciones antes de publicarlas. Este endpoint hace ese trámite completo por debajo y devuelve el historial ya clasificado por severidad, con la placa como único dato de entrada.

Para quién sirve

Compraventas y concesionarios de usados que tasan antes de comprar, marketplaces de vehículos que quieren advertir al comprador antes del contacto, peritos y talleres de latonería que necesitan saber dónde mirar, aseguradoras e intermediarios que revisan el historial antes de expedir una póliza, y financieras que prestan con el vehículo como garantía.

Datos requeridos

• placa — el único dato obligatorio. 5 a 7 caracteres alfanuméricos, con o sin guiones ni espacios. No se pide documento del propietario, así que la consulta se puede hacer sobre un carro que todavía no es tuyo.
• refresh — opcional. Salta el caché y vuelve a consultar la fuente. Con un caché de 180 días es la única forma de forzar una relectura, y conviene usarlo con cuidado: cada relectura gasta un cupo del portal.

Fuentes y cobertura

• Historial de accidentes de vehículos asegurados (siniestroshava.com.co)Registro de reclamaciones reportadas por las compañías de seguros, embebido en el portal de FASECOLDA. Por cada reclamación publica la fecha del siniestro y el amparo bajo el cual se indemnizó. Cobertura desde 2008 y únicamente para vehículos que estuvieron asegurados.
• Clasificación de severidad (derivada, PlacApi)El campo severidad no viene de la fuente: lo derivamos leyendo el texto del amparo. «mayor» cuando indica que se indemnizó el vehículo completo, «menor» cuando indica una reparación, y «desconocida» cuando el amparo no encaja en ninguna de las dos. El amparo original viaja íntegro en la respuesta para que la clasificación sea auditable.

¿Toda reclamación registrada es una pérdida total?

No, y confundirlas es el error caro de este dato. El historial devuelve un amparo por cada reclamación que una aseguradora reportó, y ese texto es lo único que separa la gravedad. «Pérdida Mayor Cuantía» significa que la aseguradora indemnizó el vehículo completo: eso es la pérdida total. «Pérdida Menor Cuantía» significa que pagó una reparación y el carro siguió andando. Misma placa, mismo endpoint, misma tabla; cambia una palabra.

Por eso perdidaTotal no se calcula contando registros, se calcula leyendo la severidad de cada uno. Un vehículo con dos reclamaciones menores devuelve perdidaTotal en false y totalSiniestros en 2. Si el campo se hubiera derivado del conteo, ese carro saldría marcado como pérdida total en la pantalla del comprador y la venta se caería por un dato que no dice eso.

Hay un tercer valor y es deliberado: «desconocida». Cuando el amparo no encaja en ninguna de las dos categorías, el registro se devuelve igual —con su fecha y su texto original— pero no levanta la bandera. Pintar de rojo un carro por un amparo que la fuente estrenó esta semana cuesta una venta que no había por qué perder; dejar el texto crudo en la respuesta permite que quien sepa leerlo decida. Si te llega una severidad desconocida, míralo como «hay algo aquí, léelo», no como «no pasó nada».

Ese matiz es exactamente lo que busca un perito y lo que casi ningún informe de usados entrega: la diferencia entre un vehículo reconstruido tras una indemnización total y uno que pasó por el taller con la aseguradora pagando el bómper.

¿Qué NO puedes concluir de un perdidaTotal en false?

La cobertura de esta fuente es parcial y lo decimos en la página del producto, no en la letra pequeña. El historial solo tiene vehículos que estuvieron asegurados, y solo desde 2008. Un carro que nunca tuvo póliza no tiene nada que reportar. Un choque de 2006 no está. Un golpe que el dueño pagó de su bolsillo para no perder el descuento por no reclamación, tampoco.

Traducido a lo que un integrador debe pintar en pantalla: perdidaTotal en true es un HECHO —una aseguradora indemnizó ese vehículo completo y lo reportó—, y perdidaTotal en false es una AUSENCIA DE REGISTRO. Redactar el segundo como «este vehículo nunca fue pérdida total» es la clase de afirmación que termina en una devolución y en un cliente que no vuelve. La redacción honesta es «no figura en el historial de asegurados».

Para que eso no dependa de que alguien haya leído esta página, la respuesta trae un campo cobertura con la advertencia en texto, listo para mostrarse al lado del resultado. Está pensado para copiarse tal cual en la interfaz.

Tampoco viene el valor indemnizado ni el nombre de la aseguradora: la fuente no los publica y no los inferimos. Lo que llega es fecha, amparo y severidad, y eso es todo lo que se puede afirmar.

¿Por qué esta consulta cuesta 2 créditos y las demás 1?

Porque la fuente no es un formulario público que se rellena y ya. Cada consulta arranca aceptando términos, registrando un correo, esperando el código de acceso que llega a ese correo, validándolo y recién entonces preguntando por la placa. Ese ida y vuelta tarda entre 30 y 60 segundos y no se puede saltar. Encima el portal topa alrededor de diez consultas por día por correo y por IP, así que cada consulta empieza con un correo nuevo para no chocar contra ese tope. Es el scrape más caro del catálogo vehicular y el precio lo refleja en vez de esconderlo en el margen.

A cambio, el caché con datos dura 180 días, el TTL más largo de toda la API. La razón es que este historial es inmutable hacia atrás: una reclamación de 2019 va a seguir siendo de 2019 el mes que viene. Consultar la misma placa dos veces en el mismo semestre sale del caché y no cobra nada.

Cuando la fuente falla —el portal caído, el cupo diario agotado, el código de acceso que no llegó—, la respuesta vuelve con status unknown, data en null y los 2 créditos reservados se devuelven. Ese fallo se cachea solo 30 minutos, no 180 días: es un amortiguador para no re-golpear un portal que ya está sufriendo, no una forma de esconder por medio año una fuente que se recuperó en diez minutos.

¿Dónde encaja esta llamada en un flujo de compraventa de usados?

Va primero, y la razón es el dato de entrada. Este es de los pocos endpoints del catálogo vehicular que NO pide el documento del propietario: le basta la placa. En una compraventa eso cambia el orden de todo, porque la placa la tienes desde el aviso o desde la llamada, y la cédula del dueño aparece mucho después, cuando ya invertiste una visita.

¿Cómo saber por API si un carro fue declarado pérdida total?

Con una llamada POST a /api/perdida-total enviando solo la placa. La respuesta trae perdidaTotal en true o false, el total de reclamaciones y el detalle de cada una con su fecha, su amparo y su severidad. El true aparece únicamente cuando hay al menos una reclamación de mayor cuantía, es decir, cuando una aseguradora indemnizó el vehículo completo.

¿La consulta de pérdida total necesita la cédula del propietario?

No. Es de los pocos endpoints del catálogo vehicular que se resuelve con la placa sola, y en compraventa esa diferencia es todo: puedes revisar un carro que te están ofreciendo antes de pedir un solo documento. Los endpoints que sí exigen documento del propietario son los que leen el registro automotor, como la ficha del RUNT o el semáforo de traspaso.

Ejemplo de solicitud

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

curl -X POST 'https://placapi.com/api/perdida-total' \
  -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": "siniestros",
  "status": "danger",
  "data": {
    "placa": "ABC123",
    "perdidaTotal": true,
    "totalSiniestros": 2,
    "siniestros": [
      {
        "fecha": "2022-09-13",
        "amparo": "Pérdida Mayor Cuantía",
        "severidad": "mayor"
      },
      {
        "fecha": "2015-01-20",
        "amparo": "Pérdida Menor Cuantía",
        "severidad": "menor"
      }
    ],
    "fuente": "Reclamaciones reportadas por aseguradoras",
    "cobertura": "Solo vehículos que estuvieron asegurados; reclamaciones reportadas por las aseguradoras desde 2008."
  },
  "mode": "live",
  "fetchedAt": "2026-08-20T14:32:10.000Z"
}

Explicación campo por campo

Limitaciones y posibles errores

• Cobertura parcial por diseño de la fuente: solo vehículos que estuvieron asegurados y solo desde 2008. Un perdidaTotal en false significa «no figura», nunca «nunca chocó».
• No viene el valor indemnizado ni el nombre de la aseguradora. La fuente no los publica y no se infieren.
• La severidad la derivamos del texto del amparo. Un amparo nuevo o poco común sale como «desconocida» y no levanta perdidaTotal: preferimos no afirmar una pérdida total que no consta, y por eso el amparo original viaja en la respuesta.
• El portal topa alrededor de diez consultas al día por correo y por IP. Un barrido masivo de placas no es el caso de uso de este endpoint; para volumen alto conviene escalonarlo y apoyarse en el caché de 180 días.
• Es la consulta más lenta del catálogo (30-60 s). Si la llamas dentro de una petición HTTP de tu propia aplicación, hazlo en segundo plano: no la pongas en el camino de un formulario que un usuario está esperando.
• Cuando la fuente falla, la respuesta llega con status unknown y data en null, los 2 créditos se devuelven y ese fallo se cachea 30 minutos.

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

Otras preguntas frecuentes

Seguir explorando

• ¿Cómo saber si un carro fue pérdida total? (sin código)→
• API de prendas y embargos por placa→
• API FASECOLDA: avalúo comercial por placa→
• API de consulta vehicular por placa→
• Revisar un usado antes de comprar→
• Documentación e integración→