API

Alta de vehículos

Dar de alta un vehículo tiene dos pasos: crearlo en Credikul y registrarlo en cada plataforma.

1. Crear el vehículo

curl -X POST https://api.credikul.com/v1/vehicles \
  -H "Authorization: Bearer ck_live_TU_LLAVE" \
  -H "Content-Type: application/json" \
  -d '{
    "plate": "ABC-123-D",
    "brand": "Nissan",
    "model": "Versa",
    "year": 2023,
    "color": "Blanco",
    "city": "Monterrey",
    "vin": "3N1CN7AD0KL812345",
    "platforms": ["didi", "indrive"]
  }'

Tres reglas importantes:

  • La placa y el VIN son únicos en TODA la flota Credikul, no solo en tu flotilla — una misma unidad física no puede existir dos veces en la plataforma. Un duplicado responde 409 CONFLICT con un mensaje que te dice cuál campo chocó.
  • city es el nombre humano de la ciudad de operación (p. ej. "Monterrey"). Es requisito para el registro en didi; consulta los nombres válidos en GET /v1/catalog/didi/cities.
  • El color debe ser un color del catálogo de didi (ver abajo). Un color que no existe en didi responde 400 VALIDATION.

La respuesta incluye registrations — el estado en cada plataforma, que arranca en none.

El color

El color de un vehículo es siempre un color del catálogo de didi — los mismos con los que se registra la unidad en la plataforma. Consulta la lista (fija, no cambia entre llamadas):

curl https://api.credikul.com/v1/catalog/didi/colors \
  -H "Authorization: Bearer ck_live_TU_LLAVE"
# → { "data": [ { "id": 2, "name": "Blanco" }, { "id": 4, "name": "Plateado" }, … ] }

En el alta envía color, colorId o ambos (al menos uno es obligatorio):

  • color — el nombre del catálogo (p. ej. "Plateado"). No distingue mayúsculas ni acentos y acepta sinónimos claros ("Plata" → "Plateado", "Guinda" → "Vino"). Un nombre genérico con dos variantes ("Gris", "Azul", "Verde", "Café") se toma como la variante claro — para evitar sorpresas envía el nombre exacto ("Gris oscuro") o el id.
  • colorId — el id del catálogo (p. ej. 6 para "Gris oscuro").

Si envías ambos deben ser el mismo color (400 VALIDATION si no; un nombre genérico como "Gris" coincide con cualquiera de sus dos variantes). La respuesta siempre trae el nombre canónico en color y su id en colorId — p. ej. enviar "Plata" devuelve "color": "Plateado", "colorId": 4.

2a. Registrar en didi (asíncrono, 3 pasos)

curl -X POST https://api.credikul.com/v1/vehicles/{id}/registrations \
  -H "Authorization: Bearer ck_live_TU_LLAVE" \
  -H "Content-Type: application/json" \
  -d '{ "platform": "didi" }'

El flujo completo en didi:

  1. Registro (esta llamada) — el vehículo queda pending y documentsRequired: true.
  2. Documentos — sube la tarjeta de circulación (guía). Sin ella, la revisión no arranca.
  3. Revisión de DiDi — horas o días. Consulta el estado hasta que sea approved:
# Estado almacenado (barato — ideal para polling)
curl https://api.credikul.com/v1/vehicles/{id}/registrations/didi \
  -H "Authorization: Bearer ck_live_TU_LLAVE"

# Forzar consulta en vivo a la plataforma y persistir el veredicto
curl -X POST https://api.credikul.com/v1/vehicles/{id}/registrations/didi/refresh \
  -H "Authorization: Bearer ck_live_TU_LLAVE"

Estados de la registración didi: none → pending → approved | rejected. Si rejected con docReviewStatus: "rejected", la tarjeta fue el problema — vuelve a subirla sin filtros ni ediciones.

Errores comunes: 422 CITY_REQUIRED (asigna city con PATCH /v1/vehicles/{id} primero).

El vehículo se registra en didi con su color de catálogo; a partir de ahí ese color queda fijo mientras esté registrado (ver Campos editables después).

2b. Registrar en indrive (instantáneo)

curl -X POST https://api.credikul.com/v1/vehicles/{id}/registrations \
  -H "Authorization: Bearer ck_live_TU_LLAVE" \
  -H "Content-Type: application/json" \
  -d '{ "platform": "indrive" }'

indrive registra con placa + VIN en una sola llamada síncrona — sin documentos ni revisión. El estado queda registered de inmediato. Si el vehículo no tiene VIN responde 422; asígnalo con PATCH /v1/vehicles/{id}.

Idempotencia

Repetir el POST …/registrations de un vehículo ya registrado responde 200 con el mismo objeto (no 201) — es seguro reintentar.

Campos editables después

PATCH /v1/vehicles/{id} acepta city, color / colorId (mismas reglas que en el alta), vin, status (activo / mantenimiento / inactivo) y notes. La placa, marca, modelo y año son inmutables por API — contacta a soporte si necesitas corregirlos.

El color no se puede cambiar mientras el vehículo está registrado en didi: didi no permite editar el color de una unidad ya registrada, así que un PATCH con otro color responde 409 VEHICLE_COLOR_LOCKED y no guarda ningún cambio de esa llamada. Enviar el mismo color que ya tiene es válido. Para cambiarlo, elimina el vehículo de didi y vuelve a registrarlo.