Sincronização e erros

Mantenha as atualizações em ordem

Os upserts de veículos e Rental são limitados à organização e ao seu external_id. Na criação, envie o contexto disponível. Em alterações posteriores, envie source_revision ou source_updated_at. Prefira uma revisão inteira do sistema de origem e aumente-a estritamente. Depois de armazenada uma revisão, um timestamp não a pode substituir. Propriedades omitidas conservam o valor; null explícito limpa apenas campos anuláveis. Propriedades desconhecidas são rejeitadas.

Aplicam-se as regras do ciclo Rental: a atribuição do veículo fica bloqueada ao iniciar a primeira inspeção; após a entrega, alguns campos planeados deixam de poder mudar; após a conclusão, só permanecem correções de relatório suportadas. Uma atualização antiga ou em conflito devolve um erro estruturado. Leia o recurso atual antes de tentar uma nova revisão.

Torne os comandos POST seguros para repetição

Cada POST de escrita exige Idempotency-Key. Gere um valor único por operação pretendida, mantenha-o em repetições de rede e nunca o reutilize com outro corpo. A chave é limitada à organização e guardada durante sete dias. Repetir o mesmo comando concluído devolve a resposta original; uma reutilização em conflito falha.

O PUT por ID externo é determinístico, mas os marcadores de versão continuam necessários nas alterações. Não crie outro ID externo para repetir o mesmo veículo ou reserva.

Trate os erros

Os erros usam application/problem+json, com code estável, status, detail, request_id, retryable e eventuais errors de campos. Registe o request_id para o suporte, nunca segredos nem conteúdo privado.

O URL type aponta para uma página pública. Por exemplo, INVALID_API_KEY explica causa e ação. Cada código tem uma página em todas as línguas suportadas.

Resposta	Ação
401	Verifique se a chave é válida, expirou ou foi revogada.
403	Verifique permissões e acesso comercial da organização.
409	Leia o recurso atual ou o conflito de idempotência antes de alterar o pedido.
422	Corrija os campos indicados; não repita o mesmo corpo inválido.
429	Respeite Retry-After e os cabeçalhos de limite.
503	Repita de acordo com retryable e eventual Retry-After.

GET /v1/capabilities apresenta quotas, limites de ficheiros e retenção efetivos. A referência da API é a fonte autorizada para cada rota.