API REST · versión 1

Integra el catálogo vehicular de México.

Consulta años, marcas, modelos y versiones exactas, o resuelve descripciones libres provenientes de formularios, inventarios y conversaciones.

URL basehttps://api.autocatalogo.mx

Todos los endpoints de datos usan GET.La API es de solo lectura y responde JSON en UTF-8.

Inicio rápido

Crea una cuenta, genera una credencial de prueba en el portal y haz tu primera petición. Las credenciales de prueba comienzan con ac_test_: no consumen la cuota pagada, pero cada respuesta de datos usa una consulta de cortesía.

Petición

curl https://api.autocatalogo.mx/v1/anios \
  -H "Authorization: Bearer ac_test_TU_CREDENCIAL"

Respuesta 200

{
  "datos": [
    { "anio": 2026, "marcas": 72, "modelos": 418, "versiones": 1264 }
  ],
  "meta": {
    "total": 12,
    "catalogo_version": "2026.08"
  }
}

Autenticación

Envía la credencial en cada petición mediante el encabezado Authorization. No la coloques en la URL, en código del navegador ni en repositorios.

Authorization: Bearer ac_live_TU_CREDENCIAL

Prueba

`ac_test_…`

Úsala durante el desarrollo. Ejecuta el mismo contrato y descuenta de la bolsa de cortesía del periodo.

Producción

`ac_live_…`

Úsala únicamente desde tu servidor. Las operaciones facturables se registran en tu periodo.

Catálogo estructurado

El flujo recomendado es Año → Marca → Modelo → Versión. Conserva los identificadores recibidos; son los que conectan un paso con el siguiente.

1/v1/anios
2/v1/marcas?anio=2026
3/v1/marcas/mar_…/modelos?anio=2026
4/v1/modelos/mod_…/versiones?anio=2026

GET/v1/anios

Lista los años disponibles y sus totales de marcas, modelos y versiones.

—Sin costo

GET/v1/marcas?anio={anio}

Lista las marcas; el año es opcional y acota el catálogo.

anio opcionalSin costo

GET/v1/marcas/{id}/modelos?anio={anio}

Lista los modelos de una marca y, opcionalmente, de un año.

id requerido · anio opcionalSin costo

GET/v1/modelos/{id}/anios

Lista los años disponibles cuando la integración elige primero el modelo.

id requeridoSin costo

GET/v1/modelos/{id}/versiones?anio={anio}

Devuelve las versiones exactas y sus atributos para un modelo y año.

id y anio requeridos · limite y cursor opcionales1 consulta

GET/v1/versiones/{id}

Devuelve la ficha completa de una versión por su identificador estable.

id requerido1 consulta

Resolver y buscar

Usa Resolver cuando recibas texto sin estructura. La respuesta incluye candidatos y una decisión explícita: auto_aceptable o requiere_confirmacion. No conviertas la confianza en un porcentaje para mostrar al usuario.

Resolver

curl https://api.autocatalogo.mx/v1/resolver \
  -G --data-urlencode "texto=vw jetta trendline 2018 std" \
  -H "Authorization: Bearer ac_test_TU_CREDENCIAL"

GET/v1/resolver?texto={descripcion}

Convierte una descripción libre en candidatos del catálogo y señala si requiere confirmación.

texto requerido · limite opcional (1–10)1 consulta

GET/v1/buscar?q={consulta}

Busca versiones por texto y permite acotar por año y marca.

q requerido · anio, marca, limite y cursor opcionales1 consulta

GET/v1/uso

Consulta el consumo, la cuota restante y la proyección del periodo.

—Sin costo

Paginación por cursor

Las respuestas paginadas entregan meta.cursor_siguiente. Reenvíalo sin modificar junto con los mismos filtros. El cursor está ligado a la credencial y a la consulta; puede expirar.

Haz la petición con limite.

Lee meta.cursor_siguiente.

Si no es null, envíalo como cursor.

Respuestas y errores

Las respuestas correctas contienen datos y meta. Los errores tienen un codigo estable para programar contra él; algunos incluyen una URL de resolución.

Respuesta de error

{
  "error": {
    "codigo": "parametros_invalidos",
    "mensaje": "Parámetros inválidos.",
    "detalle": {
      "parametro": "anio",
      "esperado": "entero entre 1990 y 2100"
    }
  }
}

400Parámetros o cursor inválidos

401Credencial ausente, inválida o expirada

402Suscripción, cuota o pago requieren atención

403Permiso o restricción de la credencial

404Recurso no encontrado

429Límite por minuto o cuota diaria excedidos

500Error interno

Límites y medición

Cada respuesta autenticada informa el límite disponible, el consumo y la edición del catálogo mediante encabezados HTTP.

RateLimit-LimitCapacidad por minuto de la credencial.

RateLimit-RemainingSolicitudes restantes en el nivel más próximo a agotarse.

RateLimit-ResetSegundos estimados para recuperar capacidad.

Retry-AfterCuándo reintentar después de un error 429.

X-Catalogo-VersionEdición del catálogo usada para responder.

Los errores no se cobran. Una respuesta con estado 4xx o 5xx consume cero consultas.

Los reintentos están protegidos. Una consulta idéntica repetida dentro de 60 segundos cuenta una sola vez.

La navegación no consume cuota. Obtener años, marcas y modelos sí queda registrado para proteger el servicio.

Hay una cuota diaria por credencial. Starter 250, Pro 900 y Scale 2,200 consultas de datos al día. Se repone completa a medianoche, hora de Ciudad de México, y la navegación no la consume. Está calibrada muy por encima de un día de trabajo normal: su función es que una credencial filtrada o un ciclo mal escrito no puedan facturar sin freno. Al agotarse, la API responde 429 con el código cuota_diaria_agotada.

Tu consumo adicional tiene techo y tú lo mueves. Al superar las consultas incluidas, la API sigue respondiendo y cobra por consulta hasta el techo que definas en el portal. Ahí se detiene con un 402 en vez de seguir acumulando. Consulta ambos límites en vivo en GET /v1/uso.

¿Listo para integrar?

Crea una credencial de prueba.

Valida el contrato con tu flujo real antes de pasar a producción.

Crear cuenta