Consulta masiva de placas en Colombia: cómo barrer miles de vehículos por API

Qué problema resuelve

Verificar una flota completa, el inventario de un patio de usados o la cartera de una aseguradora contra el RUNT y el SIMIT es hoy un trabajo manual: los portales oficiales piden captcha, aceptan una placa a la vez y no publican una API para desarrolladores. Quien consulta 300 placas a mano invierte una jornada entera y termina con capturas de pantalla, no con datos. El problema real no es hacer la consulta una vez, sino hacerla cinco mil veces sin que el proceso se caiga a la mitad, sin pagar dos veces la misma placa y sabiendo cuánto va a costar antes de empezar.

Para quién sirve

Administradores de flota y empresas de transporte que revisan SOAT, tecnomecánica y multas de todo su parque; aseguradoras e intermediarios que depuran cartera; concesionarios y patios de usados que barren su inventario antes de publicarlo; empresas de leasing y renting; talleres y centros de diagnóstico con base de clientes; y equipos de datos que necesitan cruzar un archivo de placas contra el registro oficial y devolver un CSV.

Datos requeridos

• placa — la placa de cada vehículo del lote. De 5 a 7 caracteres alfanuméricos; los guiones y espacios se ignoran, así que un CSV exportado de otro sistema no hay que limpiarlo antes.
• docType y docNumber — tipo y número de documento del propietario. Casi todas las fuentes oficiales exigen la pareja placa + documento y no responden solo con la placa. Si el archivo trae el documento del dueño anterior, esa fila devuelve 404 con code propietario_no_coincide.
• refresh — opcional, por defecto false. Salta el caché y vuelve a consultar la fuente. En un barrido se deja en false: con refresh en true cada repetición del lote vuelve a cobrar.
• Nada más. No hay que registrar el lote, ni solicitar una cuota especial, ni subir un archivo: el barrido es tu cliente llamando N veces al mismo endpoint con tu API key en la cabecera x-api-key.

Fuentes y cobertura

• RUNT (runt.gov.co)Alimenta consulta, vehículo básico y apto para traspaso, que derivan de la MISMA ficha y comparten una entrada de caché por placa + documento durante 24 horas: barrer un lote con dos de ellos no cuesta el doble, porque la segunda llamada sale de caché y el crédito se reembolsa. El avalúo y el impuesto vehicular reutilizan esa misma ficha para no volver a consultar el RUNT. Consulta full arma su paquete por otra vía y no comparte esa entrada.
• SIMIT (simit.org.co)Alimenta multas por placa y comparendos por cédula. Consolida la deuda de los organismos de tránsito del país en una sola respuesta, con el detalle de cada comparendo. Una respuesta con datos se cachea 24 horas; una en la que la fuente falló, 30 minutos, para no dejar clavado un error medio día.
• FASECOLDAAvalúo comercial del vehículo e historial de reclamaciones ante aseguradoras. El avalúo cuesta 1 crédito; pérdida total cuesta 2, porque su fuente es lenta y topa las consultas diarias. Cobertura del historial: solo vehículos que estuvieron asegurados desde 2008.
• RGM de ConfecámarasRegistro de garantías mobiliarias: prendas inscritas sobre el vehículo, por placa sola y sin documento del propietario. La cobertura real ronda el 3% del parque, así que en un barrido la inmensa mayoría de las placas responde sin prenda.

¿Cómo consultar 5.000 placas sin que te bloqueen?

El barrido no se bloquea por el número total de placas sino por el ritmo. La regla operativa cabe en una línea: manda las placas en un pool de concurrencia fija, respeta el 429 cuando aparezca, reintenta solo lo que vale la pena reintentar y persiste el resultado de cada placa antes de pasar a la siguiente. Un script que dispare las 5.000 llamadas de golpe no va más rápido: llena la cola, cosecha timeouts y te deja sin saber cuáles se alcanzaron a hacer.

Nada de esto exige coordinación previa con nosotros. No hay que avisar antes de un barrido ni pedir que te suban un límite: el tope está publicado, el 429 dice cuándo volver y el cobro es por placa con datos, así que un lote que se cae a la mitad no deja un cargo abierto por lo que no se consultó.

¿Cuánto cuesta un barrido de 1.000, 5.000 y 50.000 placas?

El precio por crédito baja por volumen y el descuento aplica a la compra completa, no de forma marginal por tramo: quien compra 1.000 créditos paga los 1.000 a 249 COP, no los primeros 999 a 349 y el último a 249.

Con un endpoint de 1 crédito por placa (vehículo básico, apto para traspaso, multas SIMIT, avalúo), un barrido de 1.000 placas cuesta 249.000 COP; uno de 5.000 cuesta 745.000 COP; y uno de 50.000, que es el máximo por transacción, cuesta 4.950.000 COP. Por placa eso es 249, 149 y 99 COP respectivamente.

Los endpoints de 2 créditos duplican el consumo, no el precio unitario: barrer 1.000 placas con consulta full son 2.000 créditos, o sea 498.000 COP; 5.000 placas son 10.000 créditos, o sea 1.390.000 COP. Ahí aparece un tope que conviene tener presente antes de planear: la compra máxima por transacción son 50.000 créditos, así que un barrido de 50.000 placas con consulta full (100.000 créditos) se paga en dos compras o se cotiza aparte con factura y NIT.

En el borde de un tramo comprar más cuesta menos, y no es un error de la tabla: 999 créditos valen 348.651 COP y 1.000 valen 249.000; 4.999 valen 1.244.751 y 5.000 valen 745.000. Si tu lote queda a pocas placas de un borde, redondea hacia arriba — los créditos no vencen y el sobrante queda para el barrido siguiente.

Al presupuesto hay que restarle lo que no se cobra, que en un lote grande no es marginal. Los 502, 503 y 500 se reembolsan siempre. Los hits de caché tampoco cobran: si dos endpoints derivan de la misma ficha del RUNT, o si repites el lote dentro de la ventana, la segunda llamada devuelve datos y el crédito se reembolsa con el motivo cache_hit, visible en tu consumo. Y el endpoint de impuesto vehicular no cuesta crédito: es gratis porque no liquida el impuesto, solo resuelve el departamento donde está matriculado el vehículo y el enlace al portal oficial que sí lo liquida.

¿Qué endpoint usar según lo que estés barriendo?

Elegir el endpoint es la decisión que más mueve la factura de un barrido, bastante más que cualquier optimización del cliente. Estos son los cuatro casos que cubren casi todos los lotes reales, con su costo en créditos tal como lo declara el catálogo de la API.

¿Cómo se ve el bucle de barrido en Node?

El patrón completo son cinco decisiones. Van aquí como líneas sueltas de Node con p-limit, que es la librería más corta para poner un techo de concurrencia sin escribir una cola a mano.

1. El pool. const limite = pLimit(12); — doce llamadas en vuelo, dentro del rango recomendado de 8 a 16. Es el único número que hay que tocar si el lote va lento o si aparecen 429.

2. El disparo. const resultados = await Promise.allSettled(placas.map((fila) => limite(() => consultar(fila)))); — allSettled y no all, porque un rechazo con all aborta la lectura de las demás promesas y te deja sin saber cuáles terminaron.

3. La llamada. const r = await fetch(URL, { method: 'POST', headers: { 'x-api-key': KEY, 'content-type': 'application/json' }, body: JSON.stringify(fila) }); — la misma que ves en el ejemplo cURL de abajo, una por placa.

4. El reparto por código de estado. if (r.status === 429) { await esperar(Number(r.headers.get('Retry-After') ?? 5) * 1000); return consultar(fila); } — el 429 se espera lo que diga la cabecera y se repite. if (r.status >= 500) return reintentar(fila); — los 5xx van a la cola de reintentos, con backoff y un tope de tres intentos. if (r.status === 404) return aRevision(fila); — el 404 no se reintenta nunca, se archiva. if (r.status === 402) throw new Error('sin creditos'); — el 402 detiene el lote entero: seguir llamando sin saldo solo genera ruido.

5. La persistencia. Escribe el resultado de cada placa apenas llega, con su placa como clave, y arranca el barrido saltando las que ya estén escritas. Así un lote interrumpido se reanuda sin volver a pagar, y aunque se repitiera, el caché de 24 horas devolvería los datos sin cobrar.

Un detalle que ahorra soporte: guarda también fromCache y el código HTTP junto a cada fila. Cuando alguien pregunte por qué el barrido de 5.000 placas descontó 4.812 créditos y no 5.000, la respuesta va a estar ahí — hits de caché, 404 dentro de la cortesía y 5xx reembolsados — y coincidirá con lo que muestra tu página de consumos.

¿Hay un endpoint de lote que reciba un array de placas?

No. Hoy no existe una ruta que acepte un array de placas ni un archivo: un barrido masivo son N llamadas concurrentes contra el endpoint unitario, y así es exactamente como se factura, a 1 crédito por placa con datos. Lo decimos de frente porque es la primera pregunta de todo el que llega buscando consulta masiva, y prometer un batch que no existe sale más caro que no tenerlo. El patrón que sí funciona está documentado en esta página: un pool de 8 a 16 llamadas concurrentes, respetar el Retry-After de los 429 y reintentar únicamente los 5xx.

¿Cuántas placas por minuto se pueden consultar?

El tope publicado son 1.000 peticiones por minuto y por API key, en ventana deslizante. Ese no es el número que manda: los endpoints que hacen un scrape real contra una fuente oficial sostuvieron del orden de 6 consultas por segundo, unas 22.000 por hora, en la medición de agosto de 2026, así que 5.000 placas se barren en unos 15 minutos con 8 a 16 llamadas en vuelo. Subir la concurrencia por encima de 24 no acelera el lote: solo hace que las peticiones esperen turno y que algunas terminen en 502, que no cobra pero tampoco avanza.

Ejemplo de solicitud

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

curl -X POST 'https://placapi.com/api/multas' \
  -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": "multas",
  "status": "warn",
  "data": {
    "totalDeuda": 522700,
    "totalMultas": 1,
    "multas": [
      {
        "comparendoId": "11001000000012345678",
        "fecha": "2025-03-15",
        "organismo": "SECRETARÍA DISTRITAL DE MOVILIDAD DE BOGOTÁ",
        "infraccion": "No respetar pico y placa",
        "codigo": "C14",
        "estado": "pendiente",
        "valor": 522700
      }
    ],
    "acuerdosPago": 0
  },
  "mode": "live",
  "fetchedAt": "2026-07-24T15:04:05.000Z"
}

Explicación campo por campo

Limitaciones y posibles errores

• No existe un endpoint de lote. No aceptamos un array de placas ni un archivo: el barrido son N llamadas al endpoint unitario, y así se factura. Si tu caso necesita un batch asíncrono con webhook de resultado, escríbenos antes de diseñar alrededor de algo que hoy no está.
• 1.000 consultas por minuto por API key es un tope duro. Por encima llega 429 con Retry-After, y no hay forma de comprar un tope mayor desde la web.
• El techo real lo pone la fuente, no el tope. Los endpoints que hacen scrape sostienen del orden de 6 consultas por segundo; pedir más solo alarga la cola y aumenta los 502 por espera de turno.
• Un archivo con documentos equivocados sale caro: pasadas las 10 consultas sin resultado gratis del mes para ese código, cada 404 cobra igual que una consulta con datos.
• El máximo por transacción son 50.000 créditos (4.950.000 COP). Un lote más grande se paga en varias compras o se cotiza con factura.
• Los créditos se compran por adelantado: no hay postpago ni facturación por consumo a fin de mes. Si el saldo se acaba a mitad del barrido, las llamadas siguientes responden 402 con code no_credits y hay que recargar para continuar.
• El cobro es por consulta con datos, no por placa única. Consultar dos veces la misma placa con refresh en true cobra dos veces, aunque el dato sea idéntico.

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

Otras preguntas frecuentes

Seguir explorando

• API de traspaso: si un carro se puede traspasar→
• API del SIMIT: multas y comparendos por placa→
• API del RUNT: la ficha del vehículo→
• Referencia de códigos de error (429, 402, 502)→
• Precios por volumen y compra de créditos→
• Generar API key y probar en el sandbox→