Cenários Rental: aplicação, API e webhooks

Antes dos cenários: quem cria o quê?

O seu software de aluguer gere reservas, preços, pagamentos e decisões comerciais. O TrakarIA trata da inspeção física: entrega, devolução, provas, comparação e relatórios. O mesmo veículo pode participar em vários alugueres sucessivos.

Acesso	Quem usa?	Para quê?
Chave API do grupo	Backend do software	Sincronizar veículos e dossiers, abrir inspeções e ler resultados. Nunca no navegador.
Conta TrakarIA	Pessoa que inspeciona	Iniciar sessão, fotografar e validar. A chave não substitui esta conta.

Escolher por intenção operacional

Cenário	Quando usar	Comportamento API
Reserva antecipada	A reserva é conhecida antes do levantamento	Sincronize planeamento e contexto opcional antes da entrega
Entrega imediata	O cliente chega antes de existir uma reserva completa	Crie o Rental com IDs estáveis e complete-o numa revisão posterior
Devolução com alteração	Pretende testar o ciclo inteiro	Preserve a referência de entrega, valide devolução e obtenha comparação
Cancelamento	A reserva é cancelada antes da inspeção	Cancele o Rental e liberte o planeamento sem apagar auditoria

Sincronização é uma ação explícita: envie PUT /v1/vehicles/by-external/{external_id} e PUT /v1/rentals/by-external/{external_id}. O Rental surge no planeamento. Apenas o ID da rota e vehicle_external_id são necessários; o resto pode chegar antes, na entrega ou depois com revisão mais recente. Sem hora de saída usa-se a criação; sem devolução a entrada fica aberta. Reutilize IDs externos. Sem estas chamadas, nenhuma reserva é sincronizada automaticamente.

Prepare a inspeção com POST /v1/rentals/{rental_id}/inspections, primeiro departure, depois return. O launch_url apenas abre o fluxo e não substitui a autenticação humana.

Existem dois tipos oficiais: departure e comparison, ambos em JSON e PDF. O PDF pode ficar pronto depois. Os webhooks são opcionais: configure o destino, verifique a assinatura e obtenha o relatório pela API. Sem destino, use GET /v1/events. Não confunda comandos API de saída com eventos de entrada.

Após validação:

1. a inspeção pública fica completed;
2. o webhook chega ou o evento é recuperado por GET /v1/events;
3. o backend arquiva o JSON imutável;
4. pede o PDF e, em 202, segue Retry-After ou o job.

Cenário 1: software ligado com botão “Abrir inspeção”

1. O backend sincroniza veículo e reserva, guarda Rental id e planning.entry_id e utiliza revisões crescentes.
2. Na entrega, chama a inspeção com {"type":"departure"} e Idempotency-Key, guarda o ID e mostra launch_url.
3. O operador abre, autentica-se, fotografa e valida. A ligação não concede permissões.
4. Após rental.departure.completed ou polling, o backend arquiva departure e obtém o PDF.
5. Na devolução usa o mesmo endpoint com {"type":"return"} e nova chave de idempotência.
6. rental.return.completed anuncia comparison; decisões financeiras ficam no software.

Cenário 2: software ligado sem botão

A chave continua necessária. O backend sincroniza e prepara, podendo ignorar launch_url. O operador encontra e retoma a inspeção já preparada na aplicação TrakarIA, sem criar outro ciclo. Os resultados seguem o cenário 1.

Cenário 3: tudo no TrakarIA, sem API

Não existem chave nem sincronização. O operador escolhe ou cria o veículo, conclui entrega e devolução no mesmo ciclo e consulta os resultados na aplicação. O software externo não recebe webhooks nem relatórios. Um ciclo criado apenas na aplicação não fica automaticamente associado a /v1/rentals mais tarde.

Cenário 4: a reserva ou o relatório muda

• Antes da primeira inspeção: atualize campos suportados por upsert ou PATCH com marcador mais recente. Após 409, leia o dossier.
• Cancelamento antes da entrega: /cancel cancela dossier e planeamento.
• Após o início: o veículo fica bloqueado; depois da entrega, também datas e locais. Uma correção permitida cria uma versão imutável nova.
• Após correção: arquive cada novo report_id e versão; rental.report.corrected pode notificar.

Cenário 5: recetor webhook indisponível

Verifique e elimine duplicados, depois leia o recurso atual. Use GET /v1/events com cursor ou created_after; avance o cursor só após processamento. A retenção é de 30 dias.

Cenário 6: ligação expirada

Leia a inspeção. Se continuar aberta, chame /launch com nova Idempotency-Key e abra a nova ligação. Retoma a mesma inspeção; o operador continua a autenticar-se.

O que guardar

Dado	Razão
Grupo e IDs externos de veículo e reserva	Reconciliar exatamente os mesmos registos
IDs públicos Rental e inspeção	Abrir o fluxo sem IDs privados do Kernel
ID da entrada de planeamento	Identificar a ocupação sincronizada
Uma chave de idempotência por comando	Repetir em segurança após perda de resposta
Cursor e IDs processados	Recuperar e deduplicar notificações
ID, tipo, versão e hash do relatório	Arquivar revisões separadamente

Mantenha chave API e segredo webhook no backend. Não use launch_url como identificador duradouro. O guia inicial mostra os primeiros pedidos e a referência Rental define os campos exatos.