API

Invitar conductores

En didi, vincular un conductor a tu flotilla es una invitación que el conductor acepta en su propia app — la API la envía y te dice si ya aceptó.

1. Crear el conductor

curl -X POST https://api.credikul.com/v1/drivers \
  -H "Authorization: Bearer ck_live_TU_LLAVE" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "Juan Pérez",
    "whatsapp": "+528112345678",
    "city": "Monterrey",
    "vehicleId": "1f2e…"
  }'
  • El WhatsApp es único en toda la flota Credikul (409 si ya existe) y debe ser el mismo número de la cuenta didi del conductor — es la llave con la que la plataforma lo encuentra.
  • vehicleId es opcional: si lo mandas, la asignación queda abierta desde el alta.

2. Invitar a didi

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

Respuesta 201: { "platform": "didi", "status": "invited", … }. El conductor recibe la solicitud en su app de DiDi y puede tardar horas o días en aceptar.

3. ¿Ya aceptó?

# Estado almacenado (ideal para polling periódico)
curl https://api.credikul.com/v1/drivers/{id}/invitations/didi \
  -H "Authorization: Bearer ck_live_TU_LLAVE"

# Consulta en vivo a la plataforma + persistencia
curl -X POST https://api.credikul.com/v1/drivers/{id}/invitations/didi/refresh \
  -H "Authorization: Bearer ck_live_TU_LLAVE"

{
  "platform": "didi",
  "status": "bound",
  "reviewStatus": "approved",
  "invitedAt": "2026-07-01T15:00:00.000Z",
  "acceptedAt": "2026-07-02T09:14:22.000Z"
}

El estado tiene dos ejes:

  • status — la relación con tu flotilla: none → invited → bound (aceptó) o rejected (declinó / se desvinculó).
  • reviewStatus — la revisión de la cuenta por la plataforma: pending / under_review / approved / rejected / suspended. Un conductor puede estar bound pero suspended — está en tu flotilla pero no puede tomar viajes.

Errores comunes

Código Qué significa Qué hacer
DRIVER_BOUND_ELSEWHERE (409) El conductor ya pertenece a otra flotilla en didi Debe salirse desde su app (Perfil → Flota → Salir) y entonces reintentar la invitación
DRIVER_NOT_ON_PLATFORM (422) El número no corresponde a un conductor registrado en la plataforma Verifica el WhatsApp; el conductor debe crear su cuenta en la app primero
ALREADY_INVITED (409) La plataforma ya tenía una invitación activa Consulta el estado con GET; si quedó atorada, cancélala y reintenta
INVALID_PHONE (422) Teléfono con formato inválido para la plataforma Corrige con PATCH /v1/drivers/{id}

Repetir el POST de una invitación existente responde 200 con el estado actual — reintentar es seguro.

Cancelar / desvincular

curl -X DELETE https://api.credikul.com/v1/drivers/{id}/invitations/didi \
  -H "Authorization: Bearer ck_live_TU_LLAVE"

Una invitación pendiente se cancela; un conductor ya vinculado se desvincula (su cuenta didi no se toca). El estado vuelve a none y puedes re-invitar.

indrive: la asignación de conductores por API no está disponible en v1 — responde 403 PLATFORM_NOT_ENABLED. Se habilitará sin cambios en tu integración (mismo endpoint) cuando la plataforma confirme la semántica de consentimiento.

Asignaciones

Qué conductor maneja qué vehículo. Una asignación activa por vehículo y por conductor — crear una nueva termina (desplaza) la anterior en cualquiera de los dos lados. La asignación local gobierna la vinculación del carro en la plataforma: Credikul la reconcilia automáticamente cuando el vehículo está aprobado y el conductor aceptó.

# Asignar
curl -X POST https://api.credikul.com/v1/assignments \
  -H "Authorization: Bearer ck_live_TU_LLAVE" \
  -H "Content-Type: application/json" \
  -d '{ "vehicleId": "1f2e…", "driverId": "9c4d…" }'

# Terminar
curl -X DELETE https://api.credikul.com/v1/assignments/{id} \
  -H "Authorization: Bearer ck_live_TU_LLAVE"

El campo platformSync de la asignación te dice cómo va la vinculación plataforma-lado: synced (lista), awaiting (aún no hay nada que vincular — p. ej. el vehículo sigue en revisión), pending / failed (Credikul la está reconciliando).