API de Conduce
Precio Real e Inspección 360: el valor de mercado de carros y motos en Venezuela, con cada comparable que lo respalda, y el resultado de las inspecciones de tus vehículos.
Introducción
La API de Conduce te da dos cosas. Precio Real: el valor de mercado de un carro o una moto en Venezuela, en dólares, con el rango en que se mueve y cada uno de los comparables que lo respaldan. E Inspección 360: el resultado completo de las inspecciones que Conduce hace a tus vehículos, con su informe en PDF.
Es una API REST: recibe y devuelve JSON, usa los códigos HTTP de siempre y se autentica con una llave secreta. Toda petición va por HTTPS.
El precio sale de una base de más de 15.000 comparables: carros vendidos y publicados en Conduce, y publicaciones de carros en portales de clasificados y redes sociales de Venezuela. Cada precio usa los de su modelo, y cada comparable se lleva al año y al kilometraje de tu vehículo antes de calcular.
https://api.conduceapp.com/v1cnd_live_.Autenticación
Cada petición lleva tu llave secreta en el encabezado Authorization, como Bearer. Las llaves empiezan con cnd_live_ y te las entrega Conduce.
Tu llave gasta tu cupo: guárdala en tu servidor, en una variable de entorno. Nunca la pongas en una app, en una página web ni en un repositorio.
Si falta o no es válida, la respuesta es 401. Si crees que se filtró, pídenos una nueva y que revoquemos la anterior: crear una llave nueva no apaga la anterior; Conduce la revoca cuando se lo pides.
Errores
Los códigos 2xx son éxito; los 4xx, un problema con la petición, y el mensaje dice cuál; los 5xx, una falla de Conduce, que es poco común.
| Código | Qué significa |
|---|---|
| 200 | Todo salió bien. |
| 400 | La petición está mal formada: el JSON no se pudo leer. |
| 401 | Falta la llave o no es válida. |
| 403 | Tu acceso está suspendido. |
| 404 | Lo que pides no existe, no es tuyo o el informe todavía no ha llegado. |
| 413 | El cuerpo de la petición pasa de 1 MB. |
| 422 | Un dato no es válido: param dice cuál y message, por qué. |
| 429 | Pasaste el límite por minuto o el cupo del mes. |
| 500, 503 | Falla de Conduce. Reintenta en un momento. |
Los códigos de error
code | HTTP | Cuándo |
|---|---|---|
invalid_ | 400 | El cuerpo no es un JSON válido. |
body_ | 413 | El cuerpo de la petición pasa de 1 MB. |
parameter_ | 422 | Falta un dato obligatorio. |
parameter_ | 422 | Un dato no cumple su regla. |
brand_ | 422 | La marca no está en el catálogo: message trae las más parecidas. |
resource_ | 404 | El id no existe o no es tuyo, o la ruta no existe. |
report_ | 404 | El informe en PDF de esa inspección todavía no ha llegado. |
api_ | 401 | No mandaste la llave. |
api_ | 401 | La llave no es válida o fue revocada. |
client_ | 403 | Tu acceso está suspendido. |
rate_ | 429 | Pasaste el límite de peticiones por minuto. |
monthly_ | 429 | Llegaste al cupo de valuaciones del mes. |
api_ | 500, 503 | Falla de Conduce. |
El objeto de error
typetextoLa familia del error: invalid_request_error, authentication_error, permission_error, rate_limit_error o api_error.
codetextoEl error exacto, para tu código: parameter_missing, parameter_invalid, brand_not_found, monthly_quota_exceeded…
paramtexto o nullEl parámetro con el problema, o null si no es de un parámetro.
messagetextoQué pasó, en español, para que lo leas tú.
doc_urltextoLa parte de esta documentación que lo explica.
Límites de uso
Cada llave tiene un límite de peticiones por minuto: 60, si no acordamos otro. Si te pasas, la respuesta es 429 rate_limited: espera los segundos que dice Retry-After y reintenta.
Las valuaciones no tienen tope mensual, salvo que tu plan diga otra cosa. Si lo tiene, solo cuentan las de POST /v1/valuations que dan precio, el mes va del día 1 al último en hora de Venezuela y, al llegar al tope, crear una valuación responde 429 monthly_quota_exceeded mientras el resto sigue funcionando. Ese 429 no trae Retry-After: el cupo vuelve el día 1.
No gastan cupo consultar el catálogo, tu uso o una valuación que ya pediste, ni una valuación sin datos suficientes. Las inspecciones tampoco: ni pedirlas ni la valuación que traen.
Cada respuesta te dice cómo vas, menos los 401 y 403: esos no traen los RateLimit-*.
Encabezados de la respuesta
RateLimit-LimitenteroPeticiones por minuto de tu llave.
RateLimit-RemainingenteroLas que te quedan en este minuto.
RateLimit-ResetenteroSegundos para que el minuto se renueve.
X-Conduce-Quota-RemainingenteroValuaciones que te quedan este mes. Solo viene si tu plan tiene tope; entonces sale en cada respuesta autenticada, menos en un 429 rate_limited.
Retry-AfterenteroSolo con 429 rate_limited: los segundos que debes esperar antes de reintentar. monthly_quota_exceeded no lo trae: el cupo vuelve el día 1 del mes, en hora de Venezuela.
X-Request-IdtextoEl id de la petición. Si nos escribes por un problema, mándanoslo.
Versiones
La versión va en la URL. Hoy es v1.
Dentro de v1 solo agregamos: campos nuevos en las respuestas, parámetros opcionales y valores nuevos en las listas. Tu integración debe ignorar los campos que no conoce.
Un cambio que rompa algo sale en una versión nueva, y te avisamos antes. La anterior sigue funcionando mientras migras.
Valuaciones, Inspecciones 360, catálogo, eventos y uso.
El objeto Valuación
Una valuación es el precio de mercado de un vehículo en un momento dado, con todo lo que lo respalda. Se guarda: la puedes volver a pedir con su id y no cambia aunque el mercado se mueva.
Atributos
idtextoIdentificador único. Empieza con val_.
objecttextoSiempre valuation.
statustextocomplete: hay precio. insufficient_data: todavía no hay vehículos parecidos para dar un precio; esa consulta no gasta cupo.
vehicleobjetoEl vehículo valuado, con la marca como quedó en el catálogo.
Ver los 7 camposOcultar los 7 campos
typetextocar o motorcycle.
yearenteroAño del modelo.
brandtextoLa marca, con su nombre del catálogo.
modeltextoEl modelo.
versiontexto o nullLa versión, si la mandaste.
mileage_kmenteroKilómetros recorridos.
conditiontextoEl estado.
priceobjeto o nullEl precio de mercado en dólares, en enteros. null si status es insufficient_data.
Ver los 4 camposOcultar los 4 campos
estimatedenteroEl precio estimado: la mediana de los comparables ya ajustados, movida por el estado del vehículo.
lowenteroEl piso del rango.
highenteroEl techo del rango.
currencytextoSiempre USD.
confidenceobjetoQué tan sólido es el precio.
Ver los 3 camposOcultar los 3 campos
leveltexto o nullhigh: la misma versión y 8 comparables o más en el cálculo. low: 1 o 2 comparables. medium: el resto. null si no hay precio.
matchtexto o nullversion: se comparó con la misma versión. model: con todo el modelo. null si no hay precio.
comparables_usedenteroCuántos comparables entraron al cálculo: los de la lista con outlier en false, aunque la lista se corte en 100.
comparableslistaCada vehículo que respalda el precio, hasta 100: primero los que entraron al cálculo, del más parecido a tu vehículo en año y kilometraje al menos parecido, y después los que quedaron fuera por salirse de lo normal.
Ver los 9 camposOcultar los 9 campos
sourcetextoconduce: un carro de Conduce. market: una publicación de carros en portales de clasificados y redes sociales de Venezuela.
statustextoEn Conduce: sold (vendido en Conduce), active (publicado) o inactive (ya no está publicado). En el mercado: listed.
yearenteroAño del modelo.
modeltextoEl modelo del comparable. Si no había suficientes del modelo que pediste (Corolla Cross) y se comparó con el más cercano (Corolla), aquí lo ves.
versiontexto o nullLa versión, si se conoce.
mileage_kmentero o nullKilómetros recorridos. null si la publicación no trae los km o no son creíbles; ese comparable no se ajusta por km.
priceenteroEl precio del comparable con el que trabaja el cálculo, en dólares. En Conduce, el precio del carro; en el mercado, el precio pedido ya llevado a precio de venta.
adjusted_priceenteroprice llevado al año y al kilometraje de tu vehículo. Es el que entra al cálculo.
outlierbooleanotrue si el precio se salía de lo normal para ese vehículo y no entró al cálculo.
messagetexto o nullUna nota sobre el precio cuando la hay, como «Estimación basada en 2 comparables. Tómala como referencia.». Si no, null.
referencetexto o nullTu referencia, si la mandaste.
created_atfechaCuándo se calculó, en ISO 8601 y UTC.
Crear una valuación
/v1/valuationsCalcula el precio de mercado de un vehículo con sus datos. Usa los nombres del catálogo para marca, modelo y versión: la marca tiene que estar en el catálogo, y el modelo y la versión se comparan por parecido. confidence.match te dice si se comparó con la misma versión o con todo el modelo, y cada comparable trae su modelo.
Parámetros
vehicle_typetextoCarro o moto. Si no lo mandas, es car.
carCarromotorcycleMotoyearenteroobligatorioAño del modelo, de 1950 al año que viene.
brandtextoobligatorioLa marca: su id del catálogo (toyota) o su nombre (Toyota), sin importar mayúsculas ni tildes. Hasta 100 caracteres. Si no está en el catálogo, la respuesta es 422 brand_not_found con las marcas más parecidas.
modeltextoobligatorioEl modelo, como sale en el catálogo de esa marca. Hasta 255 caracteres.
versiontextoLa versión (SE, XEI, LT…). Con versión el precio es más preciso; sin ella se compara con todo el modelo. Hasta 255 caracteres.
mileage_kmenteroobligatorioKilómetros recorridos, de 0 a 2.000.000. Si el odómetro marca millas, multiplícalas por 1,609.
conditiontextoobligatorioEl estado del vehículo.
excellentExcelentevery_goodMuy buenogoodBuenofairRegularneeds_repairsNecesita reparaciónreferencetextoTu referencia para amarrar la valuación a tu sistema, como el número de tu conductor o de su expediente. Hasta 100 caracteres.
Devuelve
El objeto Valuación. Si no hay suficientes vehículos parecidos, status es insufficient_data y price viene en null: esa consulta no gasta cupo.
Obtener una valuación
/v1/valuations/{id}Devuelve una valuación, la que pediste o la de una de tus Inspecciones 360, igual a como salió ese día, con sus comparables. No gasta cupo.
Parámetros
idtextoobligatorioEl id de la valuación (val_…), en la ruta.
Devuelve
El objeto Valuación.
Listar valuaciones
/v1/valuationsTus valuaciones, de la más nueva a la más vieja, por páginas. Sirve para encontrar las de un conductor con su referencia. No gasta cupo. Incluye las valuaciones que vienen con tus Inspecciones 360 (es el mismo id de inspection.valuation). Esas no gastan cupo. Tu uso del mes está en GET /v1/usage.
Parámetros
referencetextoSolo las valuaciones con esa referencia.
limitenteroCuántas por página, de 1 a 100. Si no lo mandas, 10.
starting_aftertextoEl id de la última que recibiste, para pedir la página siguiente.
Devuelve
Una lista de objetos Valuación.
El objeto Inspección
Una Inspección 360 es la revisión de 68 puntos que hace Conduce a un vehículo: 14 de precalificación (documentos, extras e inspección estática) y 54 técnicos (interior, frontal, motor, bajo chasis, laterales, trasera y exterior).
Trae los puntajes, cada punto con su resultado, los daños con su foto, el diagnóstico OBD2 y la valuación del vehículo ese día. Solo ves las inspecciones de tus vehículos.
Atributos
idtextoIdentificador único. Empieza con insp_.
objecttextoSiempre inspection.
statustextocompleted: la inspección terminó.
referencetexto o nullLa referencia de tu conductor que se anotó al inspeccionar: la misma de tus valuaciones.
vehicleobjetoEl vehículo inspeccionado.
Ver los 6 camposOcultar los 6 campos
vintextoEl serial (VIN) de 17 caracteres.
yearentero o nullAño del modelo. null si la inspección no lo trae.
brandtexto o nullLa marca. null si la inspección no la trae.
modeltexto o nullEl modelo. null si la inspección no lo trae.
versiontexto o nullLa versión.
mileage_kmentero o nullLos kilómetros que marcaba el odómetro. null si la inspección no los trae.
scoreobjetoLos puntajes de la inspección.
Ver los 3 camposOcultar los 3 campos
technicalenteroPuntaje técnico, de 0 a 100: lo que suman los puntos técnicos que cumplen.
prequalificationenteroPuntaje de precalificación, de 0 a 30.
prequalifiedbooleanotrue si la precalificación llegó a 25 o más.
ratingtexto o nullSegún el puntaje técnico: excellent (91 a 100), good_condition (80 a 90), needs_attention (1 a 79) o in_progress (puntaje técnico 0). null si la inspección no trae calificación.
itemslistaLos 68 puntos del protocolo, cada uno con su resultado.
Ver los 8 camposOcultar los 8 campos
keytextoEl punto: compresion_motor, tapiceria, frenos…
labeltextoSu nombre, en español.
blocktextoprequalification (14 puntos) o technical (54).
grouptextodocumentos, extras o estatica en la precalificación; interior, frontal, motor, bajo_chasis, laterales, trasera o exterior en los técnicos.
resulttexto o nullEn los técnicos: pass (cumple), improve (por mejorar) o fail (no cumple). En la precalificación: yes o no. null si ese punto no se contestó (inspección hecha antes de asignártela).
ownersentero o nullSolo en first_owner: cuántos dueños ha tenido el vehículo. Su result es yes si fue uno solo. null si ese punto no se contestó (inspección hecha antes de asignártela).
weightenteroLo que pesa en el puntaje.
notetexto o nullLo que anotó el inspector, si anotó algo.
damageslistaCada daño marcado en el croquis del vehículo, con su foto.
Ver los 4 camposOcultar los 4 campos
idtextoIdentificador del daño dentro de la inspección: dmg_1, dmg_2…
viewtexto o nullfront, rear, left, right o top: la vista del croquis. null si no se marcó.
descriptiontextoEl tipo de daño, su severidad si se marcó y la nota del inspector si anotó algo, como «Rayón de severidad leve: puerta trasera».
photo_urltexto o nullLa foto del daño. El enlace es público, como en la app: se abre sin tu llave y no vence. null si el daño no tiene foto.
obd2objeto o nullEl diagnóstico electrónico OBD2 que se le hizo al vehículo con la inspección. null si no se escaneó.
Ver los 2 camposOcultar los 2 campos
scanned_atfechaCuándo se escaneó.
codeslistaLos códigos de falla. Vacía si no hay fallas.
interviewobjetoLo que contó el dueño del vehículo en la entrevista. Solo trae lo que se contestó.
Ver los 6 camposOcultar los 6 campos
usagetexto o nullhighway (carretera), urban (ciudad) o cargo (carga). null si la respuesta no es una de esas.
collisionbooleanotrue si el vehículo tuvo una colisión.
collision_partstexto o nullLas partes que se afectaron en la colisión. null si el campo quedó vacío.
stolen_or_recoveredbooleanotrue si fue robado o recuperado.
sale_reasontexto o nullPor qué lo vende. null si el campo quedó vacío.
owner_estimated_pricenúmero o nullEl precio que el dueño cree que vale, en dólares. null si no se anotó.
test_driveobjetoLa prueba de manejo: cada punto en true si salió bien y en false si falló. Solo trae lo que se probó.
Ver los 6 camposOcultar los 6 campos
accelerationbooleanoAceleración.
no_abnormal_noisesbooleanoSin ruidos anormales.
no_vibrationsbooleanoSin vibraciones.
abs_respondsbooleanoEl ABS responde.
brakingbooleanoFrenado correcto.
overall_feelbooleanoSensación general.
observationsobjetoLas observaciones del inspector. Solo trae las que tienen texto.
Ver los 3 camposOcultar los 3 campos
relevant_infotextoInformación relevante.
technicaltextoObservación técnica.
drivingtextoObservación de manejo.
photoslistaLas fotos de la inspección, incluidas las del VIN y del odómetro. Las firmas no salen: solo van en el PDF.
Ver los 3 camposOcultar los 3 campos
kindtextosection: una foto de la inspección. damage: la foto de un daño.
sectiontexto o nullA qué parte de la inspección pertenece, como photo_vin (el VIN), photo_odometer (el odómetro) o photo_general. null en las fotos de daños.
urltextoLa foto. El enlace es público, como en la app: se abre sin tu llave y no vence.
valuationobjeto o nullLa valuación del vehículo del día de la inspección o, si Conduce te la asignó después, del día en que te la asignó: el objeto Valuación completo, con sus comparables. Viene incluida y no gasta cupo. null si no se pudo valuar.
Ver los 10 camposOcultar los 10 campos
idtextoIdentificador único. Empieza con val_.
objecttextoSiempre valuation.
statustextocomplete: hay precio. insufficient_data: todavía no hay vehículos parecidos para dar un precio; esa consulta no gasta cupo.
vehicleobjetoEl vehículo valuado, con la marca como quedó en el catálogo.
priceobjeto o nullEl precio de mercado en dólares, en enteros. null si status es insufficient_data.
confidenceobjetoQué tan sólido es el precio.
comparableslistaCada vehículo que respalda el precio, hasta 100: primero los que entraron al cálculo, del más parecido a tu vehículo en año y kilometraje al menos parecido, y después los que quedaron fuera por salirse de lo normal.
messagetexto o nullUna nota sobre el precio cuando la hay, como «Estimación basada en 2 comparables. Tómala como referencia.». Si no, null.
referencetexto o nullTu referencia, si la mandaste.
created_atfechaCuándo se calculó, en ISO 8601 y UTC.
report_urltexto o nullEl informe en PDF con el certificado: ver Descargar el informe. null mientras el informe no ha llegado.
locationtexto o nullLa ciudad donde se hizo. Por ahora siempre viene en null: el campo queda listo para cuando la tengamos.
inspected_atfechaCuándo terminó la inspección, en ISO 8601 y UTC.
Listar inspecciones
/v1/inspectionsLas inspecciones de tus vehículos, de la más nueva a la más vieja, por páginas. Filtra por la referencia del conductor, por el serial o desde una fecha. No gasta cupo.
Parámetros
referencetextoSolo las inspecciones de ese conductor.
vintextoSolo las de ese serial (VIN).
inspected_afterfechaSolo las terminadas después de esa fecha, en ISO 8601.
limitenteroCuántas por página, de 1 a 100. Si no lo mandas, 10.
starting_aftertextoEl id de la última que recibiste, para pedir la página siguiente.
Devuelve
Una lista de objetos Inspección.
Obtener una inspección
/v1/inspections/{id}La inspección completa: los 68 puntos con su resultado, los daños con sus fotos, el OBD2 y la valuación de ese día. No gasta cupo.
Parámetros
idtextoobligatorioEl id de la inspección (insp_…), en la ruta.
Devuelve
El objeto Inspección.
Descargar el informe
/v1/inspections/{id}/reportEl informe en PDF de la Inspección 360, con el certificado: el mismo que entrega Conduce. Responde application/pdf. Si el informe todavía no llegó, la respuesta es 404 report_not_ready. No gasta cupo.
Parámetros
idtextoobligatorioEl id de la inspección (insp_…), en la ruta.
Devuelve
El informe con el certificado.
Listar marcas
/v1/brandsLas marcas que la valuadora conoce, con el id que puedes mandar en brand. Cambian poco: guárdalas un día en tu sistema. No gasta cupo.
Parámetros
vehicle_typetextocar o motorcycle. Si no lo mandas, car.
carCarromotorcycleMotoDevuelve
Una lista de marcas.
Listar modelos
/v1/modelsLos modelos de una marca, del que más publicaciones tiene al que menos. Con year, solo los que tienen publicaciones de ese año, con un año de margen. No gasta cupo.
Parámetros
brandtextoobligatorioLa marca: su id o su nombre.
yearenteroSolo los modelos con publicaciones de ese año, con un año de margen: con 2020, de 2019 a 2021.
vehicle_typetextocar o motorcycle. Si no lo mandas, car.
carCarromotorcycleMotoDevuelve
Una lista de modelos.
Listar versiones
/v1/versionsLas versiones de un modelo, hasta 15, con cuántas publicaciones tiene cada una: con más publicaciones, el precio es más preciso. No gasta cupo.
Parámetros
brandtextoobligatorioLa marca: su id o su nombre.
modeltextoobligatorioEl modelo.
yearenteroSolo las versiones con publicaciones de ese año, con un año de margen: con 2020, de 2019 a 2021.
vehicle_typetextocar o motorcycle. Si no lo mandas, car.
carCarromotorcycleMotoDevuelve
Una lista de versiones.
Webhooks
Cuando pasa algo con una inspección de tus vehículos, te avisamos: mandamos un POST con el evento a la URL de tu servidor. Así no tienes que preguntar a cada rato.
La URL y tu secreto de webhooks, que empieza con whsec_, los configuramos contigo al darte acceso. La URL tiene que ser https y de un servidor público.
Los eventos
| Evento | Cuándo sale |
|---|---|
inspection. | La inspección quedó lista. Sale cuando llega su informe en PDF o, si el informe tarda, unos minutos después de terminada, con report_url en null. También sale cuando Conduce te asigna una inspección que ya existía. |
inspection. | Llegó el informe en PDF después de inspection.completed, o se reemplazó. |
inspection. | Conduce corrigió la referencia de la inspección; la de su valuación cambia con ella. |
inspection. | La inspección ya no es tuya: desde ese momento la API responde 404. Su data trae solo id, object y reference. |
Cómo verificar la firma
Cada aviso va firmado en el encabezado Conduce-Signature: t es la hora del envío y v1, la firma HMAC-SHA256 de t, un punto y el cuerpo, hecha con tu secreto. Calcúlala con el cuerpo tal como llegó, antes de convertirlo a JSON, y compárala antes de confiar en el aviso. Rechaza también un aviso cuyo t difiera más de 5 minutos de tu reloj: cada reintento sale con su t nuevo.
Para probar tu código: con el secreto whsec_prueba, t igual a 1793110805 y el cuerpo {"id":"evt_8Hn3pW5rK2qT"}, la firma tiene que dar 4bd17dfea4f9b7c1e34d78b32d378a345baca18b6e1eafa9790988a30ae7efee. El aviso de ejemplo de esta sección también va firmado con whsec_prueba, sobre el cuerpo tal como se ve.
Cómo responder
Responde con un 2xx en menos de 10 segundos. Si tu servidor no responde o da un error, reintentamos varias veces, cada vez esperando más. No seguimos redirecciones: un 301 o 302 cuenta como falla. Usa el id del evento para no procesar dos veces el mismo aviso. Si tu servidor estuvo caído, ponte al día con GET /v1/inspections?inspected_after=….
El objeto evento
idtextoIdentificador del aviso. Empieza con evt_: úsalo para no procesar dos veces el mismo.
objecttextoSiempre event.
typetextoQué pasó: inspection.completed, inspection.report_ready, inspection.updated o inspection.removed.
created_atfechaCuándo pasó, en ISO 8601 y UTC.
dataobjetoUn resumen de la inspección: pide el objeto completo con su id. En inspection.removed trae solo id, object y reference.
Ver los 6 camposOcultar los 6 campos
idtextoEl id de la inspección.
objecttextoSiempre inspection.
referencetexto o nullLa referencia de tu conductor.
ratingtexto o nullLa calificación: la misma de rating en el objeto Inspección, que puede venir en null.
inspected_atfechaCuándo terminó la inspección.
report_urltexto o nullEl informe en PDF, o null si todavía no llegó.
Consultar tu uso
/v1/usageCuántas valuaciones llevas este mes, cuántas te quedan si tu plan tiene tope y tu límite por minuto. No lleva parámetros y no gasta cupo.
Devuelve
Tu uso del mes.
Herramientas
Para integrar más rápido, con o sin un asistente de IA.
cada página tiene su botón para copiarla en Markdown y pegarla en ChatGPT, Claude o el asistente de tu editor, o para abrirla directo en ellos.
el índice de toda la documentación para asistentes de IA, y todo el texto en un solo archivo.
openapi.json describe cada endpoint, parámetro y respuesta. Con ella generas un cliente en tu lenguaje o tus propias pruebas.
impórtala en Postman o Insomnia, pon tu llave en la variable CONDUCE_API_KEY y prueba cada endpoint sin escribir código.
Cambios
Valuaciones con sus comparables, Inspecciones 360 con su informe, catálogo de marcas, modelos y versiones, avisos por webhook y consulta de uso.