Sincronización y errores

Mantener las actualizaciones en orden

Las actualizaciones de vehículos y expedientes de alquiler usan tu external_id dentro de tu organización. Al crear un recurso, envía el contexto disponible. Para cualquier cambio posterior, envía source_revision o source_updated_at. Es preferible usar un número de revisión de tu software y aumentarlo estrictamente. Una vez guardada una revisión, una marca de tiempo no puede saltarse esa regla. Los campos ausentes conservan su valor; null solo borra los campos que lo admiten. Los campos desconocidos se rechazan.

Siguen vigentes las reglas del ciclo de Alquiler: el vehículo queda fijo desde la primera inspección; tras la salida, ciertos campos previstos quedan fijos; tras el cierre, solo son posibles las correcciones admitidas de detalles de informe. Un cambio antiguo o incompatible devuelve un error estructurado. Lee el recurso actual antes de reintentar con otra revisión.

Reintentar comandos POST sin duplicados

Cada escritura POST requiere el encabezado Idempotency-Key. Crea un valor único por operación, consérvalo para los reintentos de red y nunca lo reutilices con otro contenido. Está vinculado a tu organización y se conserva siete días. Repetir un comando completado devuelve su primera respuesta correcta; reutilizar la clave de forma incompatible falla.

El PUT por identificador externo es determinista, pero el orden de las versiones sigue siendo importante para los cambios. No crees un nuevo identificador externo al reintentar con el mismo vehículo o reserva.

Gestionar los errores

Los errores API usan application/problem+json con un code estable, el status HTTP, un detail legible, un request_id, retryable y, cuando corresponda, errors por campo. Guarda el request_id para soporte sin registrar secretos ni bytes de documentos privados en tus logs.

La URL type abre la página del error. Por ejemplo, INVALID_API_KEY explica la causa y cómo actuar. Cada código devuelto por este middleware tiene una página en inglés, francés y español.

Respuesta	Acción
401	Comprueba si la clave es válida, ha caducado o se ha revocado.
403	Comprueba los permisos de la clave y los derechos del plan de la organización.
409	Examina el recurso actual o el conflicto de idempotencia antes de cambiar la petición.
422	Corrige los campos indicados; no repitas el mismo contenido inválido.
429	Respeta Retry-After y los encabezados de limitación.
503	Reintenta según retryable y, si existe, Retry-After.

GET /v1/capabilities indica las cuotas, los límites de archivo y los plazos de conservación aplicables a tu clave. La referencia API define las respuestas posibles de cada ruta.