{"openapi":"3.0.3","info":{"title":"Credikul Partner API","version":"1.0.0","description":"API pública de Credikul para flotilleros: automatiza el alta de vehículos, la invitación de conductores, documentos y la consulta de viajes/ganancias en las plataformas donde opera tu flotilla. Autenticación: `Authorization: Bearer ck_live_…`.","contact":{"email":"soporte@credikul.com"}},"servers":[{"url":"https://api.credikul.com","description":"Producción"}],"security":[{"apiKey":[]}],"tags":[{"name":"Cuenta"},{"name":"Vehículos"},{"name":"Documentos"},{"name":"Conductores"},{"name":"Invitaciones"},{"name":"Asignaciones"},{"name":"Lotes"},{"name":"Viajes"}],"components":{"securitySchemes":{"apiKey":{"type":"http","scheme":"bearer","description":"Llave API de Credikul (`ck_live_…` / `ck_test_…`). Créala en el portal: Desarrolladores → Crear llave API."}},"schemas":{"ErrorEnvelope":{"type":"object","properties":{"error":{"type":"object","properties":{"code":{"type":"string","enum":["UNAUTHORIZED","FORBIDDEN","INSUFFICIENT_SCOPE","TENANT_PENDING","NOT_FOUND","VALIDATION","CONFLICT","RATE_LIMITED","PLATFORM_NOT_ENABLED","ALREADY_INVITED","ALREADY_REGISTERED","DRIVER_BOUND_ELSEWHERE","DRIVER_NOT_ON_PLATFORM","INVALID_PHONE","CITY_REQUIRED","FILE_TOO_LARGE","INVALID_FILE_TYPE","PLATFORM_UNAVAILABLE","PLATFORM_REJECTED","INTERNAL"]},"message":{"type":"string"},"details":{"nullable":true},"requestId":{"type":"string"}},"required":["code","message","requestId"]}},"required":["error"]},"Me":{"type":"object","properties":{"tenantId":{"type":"string","format":"uuid"},"tenantName":{"type":"string"},"keyId":{"type":"string","format":"uuid"},"keyPrefix":{"type":"string"},"scopes":{"type":"array","items":{"type":"string","enum":["vehicles:read","vehicles:write","drivers:read","drivers:write","documents:write","rides:read"]}},"environment":{"type":"string","enum":["live","test"]}},"required":["tenantId","tenantName","keyId","keyPrefix","scopes","environment"]},"CatalogItem":{"type":"object","properties":{"id":{"type":"integer"},"name":{"type":"string"}},"required":["id","name"]},"Vehicle":{"type":"object","properties":{"id":{"type":"string","format":"uuid"},"plate":{"type":"string"},"brand":{"type":"string"},"model":{"type":"string"},"year":{"type":"integer"},"color":{"type":"string"},"city":{"type":"string","nullable":true},"vin":{"type":"string","nullable":true},"status":{"type":"string","enum":["activo","mantenimiento","inactivo","pending_didi"]},"platforms":{"type":"array","items":{"type":"string","enum":["didi","indrive"]}},"assignedDriverId":{"type":"string","nullable":true,"format":"uuid"},"registrations":{"type":"array","items":{"type":"object","properties":{"platform":{"type":"string","enum":["didi","indrive"]},"status":{"type":"string","enum":["none","pending","approved","rejected","registered","removed"]},"documentsRequired":{"type":"boolean"},"docStatus":{"type":"string","nullable":true,"enum":["not_submitted","submitted"]},"docReviewStatus":{"type":"string","nullable":true,"enum":["pending","approved","rejected"]},"registeredAt":{"type":"string","nullable":true,"format":"date-time"},"approvedAt":{"type":"string","nullable":true,"format":"date-time"}},"required":["platform","status","documentsRequired","docStatus","docReviewStatus","registeredAt","approvedAt"]}},"createdAt":{"type":"string","format":"date-time"},"updatedAt":{"type":"string","format":"date-time"}},"required":["id","plate","brand","model","year","color","city","vin","status","platforms","assignedDriverId","registrations","createdAt","updatedAt"]},"Registration":{"type":"object","properties":{"platform":{"type":"string","enum":["didi","indrive"]},"status":{"type":"string","enum":["none","pending","approved","rejected","registered","removed"]},"documentsRequired":{"type":"boolean"},"docStatus":{"type":"string","nullable":true,"enum":["not_submitted","submitted"]},"docReviewStatus":{"type":"string","nullable":true,"enum":["pending","approved","rejected"]},"registeredAt":{"type":"string","nullable":true,"format":"date-time"},"approvedAt":{"type":"string","nullable":true,"format":"date-time"}},"required":["platform","status","documentsRequired","docStatus","docReviewStatus","registeredAt","approvedAt"]},"Document":{"type":"object","properties":{"id":{"type":"string","format":"uuid"},"vehicleId":{"type":"string","format":"uuid"},"type":{"type":"string","enum":["circulation_card_front"]},"status":{"type":"string","enum":["submitted","failed"]},"contentType":{"type":"string"},"sizeBytes":{"type":"integer","nullable":true},"submittedAt":{"type":"string","format":"date-time"}},"required":["id","vehicleId","type","status","contentType","sizeBytes","submittedAt"]},"Driver":{"type":"object","properties":{"id":{"type":"string","format":"uuid"},"name":{"type":"string"},"whatsapp":{"type":"string"},"email":{"type":"string","nullable":true},"city":{"type":"string"},"license":{"type":"string","nullable":true},"platforms":{"type":"array","items":{"type":"string","enum":["didi","indrive"]}},"assignedVehicleId":{"type":"string","nullable":true,"format":"uuid"},"invitations":{"type":"array","items":{"type":"object","properties":{"platform":{"type":"string","enum":["didi","indrive"]},"status":{"type":"string","enum":["none","invited","bound","rejected"]},"reviewStatus":{"type":"string","nullable":true,"enum":["pending","under_review","approved","rejected","suspended"]},"invitedAt":{"type":"string","nullable":true,"format":"date-time"},"acceptedAt":{"type":"string","nullable":true,"format":"date-time"}},"required":["platform","status","reviewStatus","invitedAt","acceptedAt"]}},"createdAt":{"type":"string","format":"date-time"},"updatedAt":{"type":"string","format":"date-time"}},"required":["id","name","whatsapp","email","city","license","platforms","assignedVehicleId","invitations","createdAt","updatedAt"]},"Invitation":{"type":"object","properties":{"platform":{"type":"string","enum":["didi","indrive"]},"status":{"type":"string","enum":["none","invited","bound","rejected"]},"reviewStatus":{"type":"string","nullable":true,"enum":["pending","under_review","approved","rejected","suspended"]},"invitedAt":{"type":"string","nullable":true,"format":"date-time"},"acceptedAt":{"type":"string","nullable":true,"format":"date-time"}},"required":["platform","status","reviewStatus","invitedAt","acceptedAt"]},"Assignment":{"type":"object","properties":{"id":{"type":"string","format":"uuid"},"vehicleId":{"type":"string","format":"uuid"},"driverId":{"type":"string","format":"uuid"},"status":{"type":"string","enum":["active","ended"]},"platformSync":{"type":"string","enum":["synced","awaiting","pending","failed"]},"startedAt":{"type":"string","format":"date-time"},"endedAt":{"type":"string","nullable":true,"format":"date-time"},"createdAt":{"type":"string","format":"date-time"}},"required":["id","vehicleId","driverId","status","platformSync","startedAt","endedAt","createdAt"]},"Job":{"type":"object","properties":{"id":{"type":"string","format":"uuid"},"platform":{"type":"string","nullable":true,"enum":["didi","indrive"]},"status":{"type":"string","enum":["pending","running","completed","failed"]},"total":{"type":"integer"},"processed":{"type":"integer"},"succeeded":{"type":"integer"},"failed":{"type":"integer"},"results":{"type":"array","items":{"type":"object","properties":{"vehicleId":{"type":"string","format":"uuid"},"driverId":{"type":"string","format":"uuid"},"plate":{"type":"string"},"ok":{"type":"boolean"},"message":{"type":"string","nullable":true}},"required":["ok","message"]}},"startedAt":{"type":"string","nullable":true,"format":"date-time"},"completedAt":{"type":"string","nullable":true,"format":"date-time"},"createdAt":{"type":"string","format":"date-time"}},"required":["id","platform","status","total","processed","succeeded","failed","results","startedAt","completedAt","createdAt"]},"BatchAccepted":{"type":"object","properties":{"jobId":{"type":"string","nullable":true,"format":"uuid"},"total":{"type":"integer"},"skipped":{"type":"array","items":{"type":"string","format":"uuid"}}},"required":["jobId","total","skipped"]},"Ride":{"type":"object","properties":{"id":{"type":"string","format":"uuid"},"platform":{"type":"string","enum":["didi","indrive"]},"driverId":{"type":"string","nullable":true,"format":"uuid"},"vehicleId":{"type":"string","nullable":true,"format":"uuid"},"serviceDate":{"type":"string","pattern":"^\\d{4}-\\d{2}-\\d{2}$"},"startedAt":{"type":"string","nullable":true,"format":"date-time"},"completedAt":{"type":"string","nullable":true,"format":"date-time"},"status":{"type":"string","enum":["completed","cancelled_driver","cancelled_rider","cancelled_support","in_progress","other"]},"distanceKm":{"type":"string","nullable":true},"grossMxn":{"type":"string","nullable":true},"netMxn":{"type":"string","nullable":true},"tipMxn":{"type":"string","nullable":true}},"required":["id","platform","driverId","vehicleId","serviceDate","startedAt","completedAt","status","distanceKm","grossMxn","netMxn","tipMxn"]},"DailyEarnings":{"type":"object","properties":{"id":{"type":"string","format":"uuid"},"platform":{"type":"string","enum":["didi","indrive"]},"date":{"type":"string","pattern":"^\\d{4}-\\d{2}-\\d{2}$"},"driverId":{"type":"string","nullable":true,"format":"uuid"},"trips":{"type":"integer","nullable":true},"grossMxn":{"type":"string","nullable":true},"netMxn":{"type":"string","nullable":true},"onlineHours":{"type":"string","nullable":true}},"required":["id","platform","date","driverId","trips","grossMxn","netMxn","onlineHours"]},"EarningsSummary":{"type":"object","properties":{"platform":{"type":"string","enum":["didi","indrive"]},"from":{"type":"string","nullable":true,"pattern":"^\\d{4}-\\d{2}-\\d{2}$"},"to":{"type":"string","nullable":true,"pattern":"^\\d{4}-\\d{2}-\\d{2}$"},"totals":{"type":"object","properties":{"trips":{"type":"integer"},"grossMxn":{"type":"string"},"netMxn":{"type":"string"},"onlineHours":{"type":"string"},"days":{"type":"integer"}},"required":["trips","grossMxn","netMxn","onlineHours","days"]}},"required":["platform","from","to","totals"]}},"parameters":{}},"paths":{"/v1/health":{"get":{"tags":["Cuenta"],"summary":"Liveness (sin autenticación)","security":[],"responses":{"200":{"description":"OK"}}}},"/v1/me":{"get":{"tags":["Cuenta"],"summary":"Introspección de la llave (tenant, scopes, entorno)","responses":{"200":{"description":"Identidad de la llave","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Me"}}}},"401":{"description":"Llave API faltante, inválida o revocada (UNAUTHORIZED)","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"}}}},"403":{"description":"Scope insuficiente, cuenta en revisión o plataforma no habilitada","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"}}}},"429":{"description":"Límite de solicitudes excedido (revisa Retry-After)","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"}}}}}}},"/v1/catalog/didi/cities":{"get":{"tags":["Cuenta"],"summary":"Catálogo de ciudades didi (para el alta de vehículos)","responses":{"200":{"description":"Ciudades","content":{"application/json":{"schema":{"type":"object","properties":{"data":{"type":"array","items":{"$ref":"#/components/schemas/CatalogItem"}}},"required":["data"]}}}},"401":{"description":"Llave API faltante, inválida o revocada (UNAUTHORIZED)","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"}}}},"429":{"description":"Límite de solicitudes excedido (revisa Retry-After)","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"}}}}}}},"/v1/catalog/didi/colors":{"get":{"tags":["Cuenta"],"summary":"Catálogo de colores didi","responses":{"200":{"description":"Colores","content":{"application/json":{"schema":{"type":"object","properties":{"data":{"type":"array","items":{"$ref":"#/components/schemas/CatalogItem"}}},"required":["data"]}}}},"401":{"description":"Llave API faltante, inválida o revocada (UNAUTHORIZED)","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"}}}},"429":{"description":"Límite de solicitudes excedido (revisa Retry-After)","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"}}}}}}},"/v1/vehicles":{"get":{"tags":["Vehículos"],"summary":"Listar vehículos","description":"Scope: `vehicles:read`. Paginación por cursor (`startingAfter`).","parameters":[{"schema":{"type":"integer","minimum":1,"maximum":100,"default":25},"required":false,"name":"limit","in":"query"},{"schema":{"type":"string","format":"uuid"},"required":false,"name":"startingAfter","in":"query"},{"schema":{"type":"string"},"required":false,"name":"plate","in":"query"},{"schema":{"type":"string","enum":["activo","mantenimiento","inactivo","pending_didi"]},"required":false,"name":"status","in":"query"}],"responses":{"200":{"description":"Página de vehículos","content":{"application/json":{"schema":{"type":"object","properties":{"data":{"type":"array","items":{"$ref":"#/components/schemas/Vehicle"}},"hasMore":{"type":"boolean"}},"required":["data","hasMore"]}}}},"400":{"description":"Entrada inválida (VALIDATION)","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"}}}},"401":{"description":"Llave API faltante, inválida o revocada (UNAUTHORIZED)","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"}}}},"403":{"description":"Scope insuficiente, cuenta en revisión o plataforma no habilitada","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"}}}},"429":{"description":"Límite de solicitudes excedido (revisa Retry-After)","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"}}}}}},"post":{"tags":["Vehículos"],"summary":"Crear vehículo","description":"Scope: `vehicles:write`. La placa y el VIN son únicos en TODA la flota Credikul (409 si ya existen).","requestBody":{"content":{"application/json":{"schema":{"type":"object","properties":{"plate":{"type":"string","minLength":6,"maxLength":10},"brand":{"type":"string","minLength":1,"maxLength":80},"model":{"type":"string","minLength":1,"maxLength":80},"year":{"type":"integer","minimum":2000,"maximum":2100},"color":{"type":"string","minLength":1,"maxLength":40},"city":{"type":"string","minLength":2,"maxLength":80},"vin":{"type":"string","minLength":17,"maxLength":17,"pattern":"^[A-HJ-NPR-Z0-9]{17}$"},"platforms":{"type":"array","items":{"type":"string","enum":["didi","indrive"]},"minItems":1,"default":["didi"]}},"required":["plate","brand","model","year","color"]}}}},"responses":{"201":{"description":"Vehículo creado","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Vehicle"}}}},"400":{"description":"Entrada inválida (VALIDATION)","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"}}}},"401":{"description":"Llave API faltante, inválida o revocada (UNAUTHORIZED)","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"}}}},"403":{"description":"Scope insuficiente, cuenta en revisión o plataforma no habilitada","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"}}}},"409":{"description":"Conflicto (duplicado, estado incompatible)","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"}}}},"429":{"description":"Límite de solicitudes excedido (revisa Retry-After)","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"}}}}}}},"/v1/vehicles/{id}":{"get":{"tags":["Vehículos"],"summary":"Obtener vehículo","parameters":[{"schema":{"type":"string","format":"uuid"},"required":true,"name":"id","in":"path"}],"responses":{"200":{"description":"Vehículo","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Vehicle"}}}},"401":{"description":"Llave API faltante, inválida o revocada (UNAUTHORIZED)","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"}}}},"403":{"description":"Scope insuficiente, cuenta en revisión o plataforma no habilitada","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"}}}},"404":{"description":"Recurso no encontrado","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"}}}},"429":{"description":"Límite de solicitudes excedido (revisa Retry-After)","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"}}}}}},"patch":{"tags":["Vehículos"],"summary":"Actualizar vehículo (city/color/vin/status/notes)","parameters":[{"schema":{"type":"string","format":"uuid"},"required":true,"name":"id","in":"path"}],"requestBody":{"content":{"application/json":{"schema":{"type":"object","properties":{"city":{"type":"string","minLength":2,"maxLength":80},"color":{"type":"string","minLength":1,"maxLength":40},"vin":{"type":"string","nullable":true,"minLength":17,"maxLength":17,"pattern":"^[A-HJ-NPR-Z0-9]{17}$"},"status":{"type":"string","enum":["activo","mantenimiento","inactivo"]},"notes":{"type":"string","maxLength":2000}}}}}},"responses":{"200":{"description":"Vehículo actualizado","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Vehicle"}}}},"400":{"description":"Entrada inválida (VALIDATION)","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"}}}},"401":{"description":"Llave API faltante, inválida o revocada (UNAUTHORIZED)","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"}}}},"403":{"description":"Scope insuficiente, cuenta en revisión o plataforma no habilitada","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"}}}},"404":{"description":"Recurso no encontrado","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"}}}},"409":{"description":"Conflicto (duplicado, estado incompatible)","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"}}}},"429":{"description":"Límite de solicitudes excedido (revisa Retry-After)","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"}}}}}}},"/v1/vehicles/{id}/registrations":{"post":{"tags":["Vehículos"],"summary":"Registrar el vehículo en una plataforma (alta)","description":"Scope: `vehicles:write`. didi: registro asíncrono (queda `pending` y requiere la tarjeta de circulación). indrive: instantáneo (requiere VIN). Idempotente: si ya está registrado responde 200 con el mismo objeto.","parameters":[{"schema":{"type":"string","format":"uuid"},"required":true,"name":"id","in":"path"}],"requestBody":{"content":{"application/json":{"schema":{"type":"object","properties":{"platform":{"type":"string","enum":["didi","indrive"]}},"required":["platform"]}}}},"responses":{"200":{"description":"Ya estaba registrado","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Registration"}}}},"201":{"description":"Registro iniciado","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Registration"}}}},"400":{"description":"Entrada inválida (VALIDATION)","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"}}}},"401":{"description":"Llave API faltante, inválida o revocada (UNAUTHORIZED)","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"}}}},"403":{"description":"Scope insuficiente, cuenta en revisión o plataforma no habilitada","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"}}}},"404":{"description":"Recurso no encontrado","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"}}}},"422":{"description":"La operación no procede (estado del recurso / plataforma)","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"}}}},"429":{"description":"Límite de solicitudes excedido (revisa Retry-After)","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"}}}}}},"get":{"tags":["Vehículos"],"summary":"Estado de registro en todas las plataformas","parameters":[{"schema":{"type":"string","format":"uuid"},"required":true,"name":"id","in":"path"}],"responses":{"200":{"description":"Registros","content":{"application/json":{"schema":{"type":"object","properties":{"data":{"type":"array","items":{"$ref":"#/components/schemas/Registration"}}},"required":["data"]}}}},"401":{"description":"Llave API faltante, inválida o revocada (UNAUTHORIZED)","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"}}}},"403":{"description":"Scope insuficiente, cuenta en revisión o plataforma no habilitada","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"}}}},"404":{"description":"Recurso no encontrado","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"}}}},"429":{"description":"Límite de solicitudes excedido (revisa Retry-After)","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"}}}}}}},"/v1/vehicles/{id}/registrations/{platform}":{"get":{"tags":["Vehículos"],"summary":"Estado de registro en una plataforma (objetivo de polling)","parameters":[{"schema":{"type":"string","format":"uuid"},"required":true,"name":"id","in":"path"},{"schema":{"type":"string","enum":["didi","indrive"]},"required":true,"name":"platform","in":"path"}],"responses":{"200":{"description":"Registro","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Registration"}}}},"401":{"description":"Llave API faltante, inválida o revocada (UNAUTHORIZED)","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"}}}},"403":{"description":"Scope insuficiente, cuenta en revisión o plataforma no habilitada","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"}}}},"404":{"description":"Recurso no encontrado","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"}}}},"429":{"description":"Límite de solicitudes excedido (revisa Retry-After)","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"}}}}}}},"/v1/vehicles/{id}/registrations/{platform}/refresh":{"post":{"tags":["Vehículos"],"summary":"Refrescar el veredicto de revisión en vivo (solo didi)","parameters":[{"schema":{"type":"string","format":"uuid"},"required":true,"name":"id","in":"path"},{"schema":{"type":"string","enum":["didi","indrive"]},"required":true,"name":"platform","in":"path"}],"responses":{"200":{"description":"Estado actualizado","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Registration"}}}},"400":{"description":"Entrada inválida (VALIDATION)","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"}}}},"401":{"description":"Llave API faltante, inválida o revocada (UNAUTHORIZED)","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"}}}},"403":{"description":"Scope insuficiente, cuenta en revisión o plataforma no habilitada","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"}}}},"404":{"description":"Recurso no encontrado","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"}}}},"409":{"description":"Conflicto (duplicado, estado incompatible)","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"}}}},"429":{"description":"Límite de solicitudes excedido (revisa Retry-After)","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"}}}}}}},"/v1/vehicles/{id}/documents":{"post":{"tags":["Documentos"],"summary":"Subir la tarjeta de circulación (frente)","description":"Scope: `documents:write`. Multipart: campo `file` (JPEG/PNG, máx 4 MB) + `type=circulation_card_front`. Requiere registro didi previo (409 si falta).","parameters":[{"schema":{"type":"string","format":"uuid"},"required":true,"name":"id","in":"path"}],"responses":{"201":{"description":"Documento enviado a revisión","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Document"}}}},"400":{"description":"Entrada inválida (VALIDATION)","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"}}}},"401":{"description":"Llave API faltante, inválida o revocada (UNAUTHORIZED)","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"}}}},"403":{"description":"Scope insuficiente, cuenta en revisión o plataforma no habilitada","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"}}}},"404":{"description":"Recurso no encontrado","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"}}}},"409":{"description":"Conflicto (duplicado, estado incompatible)","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"}}}},"413":{"description":"Archivo demasiado grande (FILE_TOO_LARGE)","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"}}}},"422":{"description":"La operación no procede (estado del recurso / plataforma)","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"}}}},"429":{"description":"Límite de solicitudes excedido (revisa Retry-After)","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"}}}}}},"get":{"tags":["Documentos"],"summary":"Historial de documentos del vehículo","parameters":[{"schema":{"type":"string","format":"uuid"},"required":true,"name":"id","in":"path"}],"responses":{"200":{"description":"Documentos","content":{"application/json":{"schema":{"type":"object","properties":{"data":{"type":"array","items":{"$ref":"#/components/schemas/Document"}}},"required":["data"]}}}},"401":{"description":"Llave API faltante, inválida o revocada (UNAUTHORIZED)","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"}}}},"403":{"description":"Scope insuficiente, cuenta en revisión o plataforma no habilitada","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"}}}},"404":{"description":"Recurso no encontrado","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"}}}},"429":{"description":"Límite de solicitudes excedido (revisa Retry-After)","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"}}}}}}},"/v1/drivers":{"get":{"tags":["Conductores"],"summary":"Listar conductores","parameters":[{"schema":{"type":"integer","minimum":1,"maximum":100,"default":25},"required":false,"name":"limit","in":"query"},{"schema":{"type":"string","format":"uuid"},"required":false,"name":"startingAfter","in":"query"},{"schema":{"type":"string","pattern":"^(?:\\d{10}|\\+(?:1\\d{10}|52\\d{10}|521\\d{10}))$"},"required":false,"name":"whatsapp","in":"query"}],"responses":{"200":{"description":"Página de conductores","content":{"application/json":{"schema":{"type":"object","properties":{"data":{"type":"array","items":{"$ref":"#/components/schemas/Driver"}},"hasMore":{"type":"boolean"}},"required":["data","hasMore"]}}}},"400":{"description":"Entrada inválida (VALIDATION)","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"}}}},"401":{"description":"Llave API faltante, inválida o revocada (UNAUTHORIZED)","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"}}}},"403":{"description":"Scope insuficiente, cuenta en revisión o plataforma no habilitada","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"}}}},"429":{"description":"Límite de solicitudes excedido (revisa Retry-After)","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"}}}}}},"post":{"tags":["Conductores"],"summary":"Crear conductor","description":"Scope: `drivers:write`. El WhatsApp es único en toda la flota Credikul (409). `vehicleId` opcional abre la asignación.","requestBody":{"content":{"application/json":{"schema":{"type":"object","properties":{"name":{"type":"string","minLength":2,"maxLength":200},"whatsapp":{"type":"string","pattern":"^(?:\\d{10}|\\+(?:1\\d{10}|52\\d{10}|521\\d{10}))$"},"city":{"type":"string","minLength":2,"maxLength":80},"email":{"type":"string","format":"email"},"license":{"type":"string","maxLength":40},"vehicleId":{"type":"string","format":"uuid"}},"required":["name","whatsapp","city"]}}}},"responses":{"201":{"description":"Conductor creado","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Driver"}}}},"400":{"description":"Entrada inválida (VALIDATION)","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"}}}},"401":{"description":"Llave API faltante, inválida o revocada (UNAUTHORIZED)","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"}}}},"403":{"description":"Scope insuficiente, cuenta en revisión o plataforma no habilitada","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"}}}},"404":{"description":"Recurso no encontrado","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"}}}},"409":{"description":"Conflicto (duplicado, estado incompatible)","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"}}}},"429":{"description":"Límite de solicitudes excedido (revisa Retry-After)","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"}}}}}}},"/v1/drivers/{id}":{"get":{"tags":["Conductores"],"summary":"Obtener conductor","parameters":[{"schema":{"type":"string","format":"uuid"},"required":true,"name":"id","in":"path"}],"responses":{"200":{"description":"Conductor","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Driver"}}}},"401":{"description":"Llave API faltante, inválida o revocada (UNAUTHORIZED)","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"}}}},"403":{"description":"Scope insuficiente, cuenta en revisión o plataforma no habilitada","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"}}}},"404":{"description":"Recurso no encontrado","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"}}}},"429":{"description":"Límite de solicitudes excedido (revisa Retry-After)","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"}}}}}},"patch":{"tags":["Conductores"],"summary":"Actualizar conductor","description":"El WhatsApp se congela cuando el conductor ya aceptó la invitación (409).","parameters":[{"schema":{"type":"string","format":"uuid"},"required":true,"name":"id","in":"path"}],"requestBody":{"content":{"application/json":{"schema":{"type":"object","properties":{"name":{"type":"string","minLength":2,"maxLength":200},"whatsapp":{"type":"string","pattern":"^(?:\\d{10}|\\+(?:1\\d{10}|52\\d{10}|521\\d{10}))$"},"email":{"type":"string","nullable":true,"format":"email"},"city":{"type":"string","minLength":2,"maxLength":80},"license":{"type":"string","nullable":true,"maxLength":40}}}}}},"responses":{"200":{"description":"Conductor actualizado","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Driver"}}}},"400":{"description":"Entrada inválida (VALIDATION)","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"}}}},"401":{"description":"Llave API faltante, inválida o revocada (UNAUTHORIZED)","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"}}}},"403":{"description":"Scope insuficiente, cuenta en revisión o plataforma no habilitada","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"}}}},"404":{"description":"Recurso no encontrado","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"}}}},"409":{"description":"Conflicto (duplicado, estado incompatible)","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"}}}},"429":{"description":"Límite de solicitudes excedido (revisa Retry-After)","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"}}}}}}},"/v1/drivers/{id}/invitations":{"post":{"tags":["Invitaciones"],"summary":"Invitar al conductor a una plataforma","description":"Scope: `drivers:write`. didi: envía la invitación que el conductor acepta en su app (consulta el estado con GET/refresh). indrive: no disponible en v1 (403 PLATFORM_NOT_ENABLED). Idempotente: si ya hay invitación responde 200.","parameters":[{"schema":{"type":"string","format":"uuid"},"required":true,"name":"id","in":"path"}],"requestBody":{"content":{"application/json":{"schema":{"type":"object","properties":{"platform":{"type":"string","enum":["didi","indrive"]}},"required":["platform"]}}}},"responses":{"200":{"description":"Ya existía una invitación","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Invitation"}}}},"201":{"description":"Invitación enviada","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Invitation"}}}},"400":{"description":"Entrada inválida (VALIDATION)","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"}}}},"401":{"description":"Llave API faltante, inválida o revocada (UNAUTHORIZED)","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"}}}},"403":{"description":"Scope insuficiente, cuenta en revisión o plataforma no habilitada","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"}}}},"404":{"description":"Recurso no encontrado","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"}}}},"409":{"description":"Conflicto (duplicado, estado incompatible)","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"}}}},"422":{"description":"La operación no procede (estado del recurso / plataforma)","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"}}}},"429":{"description":"Límite de solicitudes excedido (revisa Retry-After)","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"}}}}}},"get":{"tags":["Invitaciones"],"summary":"Estado de invitaciones del conductor","parameters":[{"schema":{"type":"string","format":"uuid"},"required":true,"name":"id","in":"path"}],"responses":{"200":{"description":"Invitaciones","content":{"application/json":{"schema":{"type":"object","properties":{"data":{"type":"array","items":{"$ref":"#/components/schemas/Invitation"}}},"required":["data"]}}}},"401":{"description":"Llave API faltante, inválida o revocada (UNAUTHORIZED)","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"}}}},"403":{"description":"Scope insuficiente, cuenta en revisión o plataforma no habilitada","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"}}}},"404":{"description":"Recurso no encontrado","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"}}}},"429":{"description":"Límite de solicitudes excedido (revisa Retry-After)","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"}}}}}}},"/v1/drivers/{id}/invitations/{platform}":{"get":{"tags":["Invitaciones"],"summary":"¿Ya aceptó? — estado almacenado de la invitación","parameters":[{"schema":{"type":"string","format":"uuid"},"required":true,"name":"id","in":"path"},{"schema":{"type":"string","enum":["didi","indrive"]},"required":true,"name":"platform","in":"path"}],"responses":{"200":{"description":"Invitación","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Invitation"}}}},"401":{"description":"Llave API faltante, inválida o revocada (UNAUTHORIZED)","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"}}}},"403":{"description":"Scope insuficiente, cuenta en revisión o plataforma no habilitada","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"}}}},"404":{"description":"Recurso no encontrado","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"}}}},"429":{"description":"Límite de solicitudes excedido (revisa Retry-After)","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"}}}}}}},"/v1/drivers/{id}/invitations/didi/refresh":{"post":{"tags":["Invitaciones"],"summary":"Consultar la plataforma en vivo y persistir el estado","parameters":[{"schema":{"type":"string","format":"uuid"},"required":true,"name":"id","in":"path"}],"responses":{"200":{"description":"Estado actualizado","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Invitation"}}}},"401":{"description":"Llave API faltante, inválida o revocada (UNAUTHORIZED)","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"}}}},"403":{"description":"Scope insuficiente, cuenta en revisión o plataforma no habilitada","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"}}}},"404":{"description":"Recurso no encontrado","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"}}}},"409":{"description":"Conflicto (duplicado, estado incompatible)","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"}}}},"429":{"description":"Límite de solicitudes excedido (revisa Retry-After)","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"}}}}}}},"/v1/drivers/{id}/invitations/didi":{"delete":{"tags":["Invitaciones"],"summary":"Cancelar la invitación / desvincular al conductor","parameters":[{"schema":{"type":"string","format":"uuid"},"required":true,"name":"id","in":"path"}],"responses":{"200":{"description":"Invitación cancelada (status none)","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Invitation"}}}},"401":{"description":"Llave API faltante, inválida o revocada (UNAUTHORIZED)","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"}}}},"403":{"description":"Scope insuficiente, cuenta en revisión o plataforma no habilitada","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"}}}},"404":{"description":"Recurso no encontrado","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"}}}},"429":{"description":"Límite de solicitudes excedido (revisa Retry-After)","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"}}}}}}},"/v1/assignments":{"get":{"tags":["Asignaciones"],"summary":"Listar asignaciones conductor↔vehículo","parameters":[{"schema":{"type":"integer","minimum":1,"maximum":100,"default":25},"required":false,"name":"limit","in":"query"},{"schema":{"type":"string","format":"uuid"},"required":false,"name":"startingAfter","in":"query"},{"schema":{"type":"string","format":"uuid"},"required":false,"name":"vehicleId","in":"query"},{"schema":{"type":"string","format":"uuid"},"required":false,"name":"driverId","in":"query"},{"schema":{"type":"string","enum":["active","ended"]},"required":false,"name":"status","in":"query"}],"responses":{"200":{"description":"Página de asignaciones","content":{"application/json":{"schema":{"type":"object","properties":{"data":{"type":"array","items":{"$ref":"#/components/schemas/Assignment"}},"hasMore":{"type":"boolean"}},"required":["data","hasMore"]}}}},"400":{"description":"Entrada inválida (VALIDATION)","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"}}}},"401":{"description":"Llave API faltante, inválida o revocada (UNAUTHORIZED)","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"}}}},"403":{"description":"Scope insuficiente, cuenta en revisión o plataforma no habilitada","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"}}}},"429":{"description":"Límite de solicitudes excedido (revisa Retry-After)","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"}}}}}},"post":{"tags":["Asignaciones"],"summary":"Asignar un conductor a un vehículo","description":"Scope: `drivers:write`. Un vehículo y un conductor solo pueden tener UNA asignación activa: crear una nueva desplaza (termina) la anterior en cualquiera de los dos lados. La asignación local gobierna la vinculación en la plataforma.","requestBody":{"content":{"application/json":{"schema":{"type":"object","properties":{"vehicleId":{"type":"string","format":"uuid"},"driverId":{"type":"string","format":"uuid"}},"required":["vehicleId","driverId"]}}}},"responses":{"201":{"description":"Asignación activa","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Assignment"}}}},"400":{"description":"Entrada inválida (VALIDATION)","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"}}}},"401":{"description":"Llave API faltante, inválida o revocada (UNAUTHORIZED)","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"}}}},"403":{"description":"Scope insuficiente, cuenta en revisión o plataforma no habilitada","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"}}}},"404":{"description":"Recurso no encontrado","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"}}}},"429":{"description":"Límite de solicitudes excedido (revisa Retry-After)","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"}}}}}}},"/v1/assignments/{id}":{"get":{"tags":["Asignaciones"],"summary":"Obtener asignación","parameters":[{"schema":{"type":"string","format":"uuid"},"required":true,"name":"id","in":"path"}],"responses":{"200":{"description":"Asignación","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Assignment"}}}},"401":{"description":"Llave API faltante, inválida o revocada (UNAUTHORIZED)","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"}}}},"403":{"description":"Scope insuficiente, cuenta en revisión o plataforma no habilitada","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"}}}},"404":{"description":"Recurso no encontrado","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"}}}},"429":{"description":"Límite de solicitudes excedido (revisa Retry-After)","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"}}}}}},"delete":{"tags":["Asignaciones"],"summary":"Terminar la asignación","parameters":[{"schema":{"type":"string","format":"uuid"},"required":true,"name":"id","in":"path"}],"responses":{"200":{"description":"Asignación terminada","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Assignment"}}}},"401":{"description":"Llave API faltante, inválida o revocada (UNAUTHORIZED)","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"}}}},"403":{"description":"Scope insuficiente, cuenta en revisión o plataforma no habilitada","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"}}}},"404":{"description":"Recurso no encontrado","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"}}}},"429":{"description":"Límite de solicitudes excedido (revisa Retry-After)","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"}}}}}}},"/v1/drivers/invitations/batch":{"post":{"tags":["Lotes"],"summary":"Invitar varios conductores (didi) — async","description":"Scope: `drivers:write`. Responde 202 con `jobId`; consulta el avance en GET /v1/jobs/{id}. `skipped` = conductores no elegibles (ya invitados, inexistentes).","requestBody":{"content":{"application/json":{"schema":{"type":"object","properties":{"platform":{"type":"string","enum":["didi","indrive"]},"driverIds":{"type":"array","items":{"type":"string","format":"uuid"},"minItems":1,"maxItems":500}},"required":["platform","driverIds"]}}}},"responses":{"202":{"description":"Job aceptado","content":{"application/json":{"schema":{"$ref":"#/components/schemas/BatchAccepted"}}}},"400":{"description":"Entrada inválida (VALIDATION)","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"}}}},"401":{"description":"Llave API faltante, inválida o revocada (UNAUTHORIZED)","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"}}}},"403":{"description":"Scope insuficiente, cuenta en revisión o plataforma no habilitada","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"}}}},"429":{"description":"Límite de solicitudes excedido (revisa Retry-After)","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"}}}}}}},"/v1/vehicles/registrations/batch":{"post":{"tags":["Lotes"],"summary":"Registrar varios vehículos en una plataforma — async","description":"Scope: `vehicles:write`. Responde 202 con `jobId`; consulta el avance en GET /v1/jobs/{id}.","requestBody":{"content":{"application/json":{"schema":{"type":"object","properties":{"platform":{"type":"string","enum":["didi","indrive"]},"vehicleIds":{"type":"array","items":{"type":"string","format":"uuid"},"minItems":1,"maxItems":500}},"required":["platform","vehicleIds"]}}}},"responses":{"202":{"description":"Job aceptado","content":{"application/json":{"schema":{"$ref":"#/components/schemas/BatchAccepted"}}}},"400":{"description":"Entrada inválida (VALIDATION)","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"}}}},"401":{"description":"Llave API faltante, inválida o revocada (UNAUTHORIZED)","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"}}}},"403":{"description":"Scope insuficiente, cuenta en revisión o plataforma no habilitada","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"}}}},"429":{"description":"Límite de solicitudes excedido (revisa Retry-After)","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"}}}}}}},"/v1/jobs/{id}":{"get":{"tags":["Lotes"],"summary":"Avance de un job por lotes","parameters":[{"schema":{"type":"string","format":"uuid"},"required":true,"name":"id","in":"path"}],"responses":{"200":{"description":"Estado del job","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Job"}}}},"401":{"description":"Llave API faltante, inválida o revocada (UNAUTHORIZED)","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"}}}},"403":{"description":"Scope insuficiente, cuenta en revisión o plataforma no habilitada","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"}}}},"404":{"description":"Recurso no encontrado","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"}}}},"429":{"description":"Límite de solicitudes excedido (revisa Retry-After)","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"}}}}}}},"/v1/rides":{"get":{"tags":["Viajes"],"summary":"Listar viajes (por plataforma)","description":"Scope: `rides:read`. `platform` es requerido. Dinero como string decimal MXN; fechas en día calendario CDMX (−06:00 fijo). Las métricas de indrive se asientan hasta 16 días — re-consulta ventanas recientes.","parameters":[{"schema":{"type":"integer","minimum":1,"maximum":100,"default":25},"required":false,"name":"limit","in":"query"},{"schema":{"type":"string","format":"uuid"},"required":false,"name":"startingAfter","in":"query"},{"schema":{"type":"string","enum":["didi","indrive"]},"required":true,"name":"platform","in":"query"},{"schema":{"type":"string","pattern":"^\\d{4}-\\d{2}-\\d{2}$"},"required":false,"name":"from","in":"query"},{"schema":{"type":"string","pattern":"^\\d{4}-\\d{2}-\\d{2}$"},"required":false,"name":"to","in":"query"},{"schema":{"type":"string","format":"uuid"},"required":false,"name":"driverId","in":"query"},{"schema":{"type":"string","format":"uuid"},"required":false,"name":"vehicleId","in":"query"},{"schema":{"type":"string","enum":["completed","cancelled_driver","cancelled_rider","cancelled_support","in_progress","other"]},"required":false,"name":"status","in":"query"}],"responses":{"200":{"description":"Página de viajes","content":{"application/json":{"schema":{"type":"object","properties":{"data":{"type":"array","items":{"$ref":"#/components/schemas/Ride"}},"hasMore":{"type":"boolean"}},"required":["data","hasMore"]}}}},"400":{"description":"Entrada inválida (VALIDATION)","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"}}}},"401":{"description":"Llave API faltante, inválida o revocada (UNAUTHORIZED)","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"}}}},"403":{"description":"Scope insuficiente, cuenta en revisión o plataforma no habilitada","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"}}}},"429":{"description":"Límite de solicitudes excedido (revisa Retry-After)","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"}}}}}}},"/v1/earnings/daily":{"get":{"tags":["Viajes"],"summary":"Ganancias diarias por conductor","parameters":[{"schema":{"type":"integer","minimum":1,"maximum":100,"default":25},"required":false,"name":"limit","in":"query"},{"schema":{"type":"string","format":"uuid"},"required":false,"name":"startingAfter","in":"query"},{"schema":{"type":"string","enum":["didi","indrive"]},"required":true,"name":"platform","in":"query"},{"schema":{"type":"string","pattern":"^\\d{4}-\\d{2}-\\d{2}$"},"required":false,"name":"from","in":"query"},{"schema":{"type":"string","pattern":"^\\d{4}-\\d{2}-\\d{2}$"},"required":false,"name":"to","in":"query"},{"schema":{"type":"string","format":"uuid"},"required":false,"name":"driverId","in":"query"}],"responses":{"200":{"description":"Página de días","content":{"application/json":{"schema":{"type":"object","properties":{"data":{"type":"array","items":{"$ref":"#/components/schemas/DailyEarnings"}},"hasMore":{"type":"boolean"}},"required":["data","hasMore"]}}}},"400":{"description":"Entrada inválida (VALIDATION)","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"}}}},"401":{"description":"Llave API faltante, inválida o revocada (UNAUTHORIZED)","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"}}}},"403":{"description":"Scope insuficiente, cuenta en revisión o plataforma no habilitada","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"}}}},"429":{"description":"Límite de solicitudes excedido (revisa Retry-After)","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"}}}}}}},"/v1/earnings/summary":{"get":{"tags":["Viajes"],"summary":"Totales del periodo","parameters":[{"schema":{"type":"string","enum":["didi","indrive"]},"required":true,"name":"platform","in":"query"},{"schema":{"type":"string","pattern":"^\\d{4}-\\d{2}-\\d{2}$"},"required":false,"name":"from","in":"query"},{"schema":{"type":"string","pattern":"^\\d{4}-\\d{2}-\\d{2}$"},"required":false,"name":"to","in":"query"},{"schema":{"type":"string","format":"uuid"},"required":false,"name":"driverId","in":"query"}],"responses":{"200":{"description":"Totales","content":{"application/json":{"schema":{"$ref":"#/components/schemas/EarningsSummary"}}}},"400":{"description":"Entrada inválida (VALIDATION)","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"}}}},"401":{"description":"Llave API faltante, inválida o revocada (UNAUTHORIZED)","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"}}}},"403":{"description":"Scope insuficiente, cuenta en revisión o plataforma no habilitada","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"}}}},"429":{"description":"Límite de solicitudes excedido (revisa Retry-After)","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"}}}}}}}}}