Fluxo de inspeção de veículos de aluguer

O seu software de aluguer gere reservas e condições comerciais. O TrakarIA recebe o contexto necessário para inspecionar o veículo e conserva o dossier de inspeção autorizado, as provas e as revisões validadas dos relatórios.

Experimente os cenários API: abra o testador interativo de integração. Estas páginas continuam a ser a descrição autorizada do contrato público.

Comece pela visão geral, escolha um modelo de integração e siga os cenários detalhados.

Responsabilidades

Interveniente	Responsabilidade	Exemplo
O seu software	Referência da reserva, datas e decisões comerciais	Cria RES-1042; decide sobre a cobrança de danos
TrakarIA	Inspeção, provas, validação humana e histórico de relatórios	Regista o estado na entrega e compara-o na devolução
A sua equipa	Ações sob a própria identidade TrakarIA	Inicia sessão, fotografa, revê e valida

Uma chave de grupo identifica software, não a pessoa que inspeciona, e não lhe concede acesso. Essa pessoa inicia sessão e necessita das permissões adequadas. O percurso Rental também pode ser concluído diretamente na aplicação, sem API.

Percurso humano

1. Existe um veículo no grupo, criado na aplicação ou sincronizado.
2. Um dossier Rental contém o contexto operacional de uma reserva; o TrakarIA não substitui reservas, pagamentos ou disponibilidade.
3. Uma pessoa autorizada regista o estado na entrega e valida departure.
4. Na devolução, regista o estado atual e valida a comparação. Não existe um relatório oficial separado do tipo return.
5. Com a API pública, o TrakarIA pode enviar webhooks assinados. O backend obtém então o relatório departure ou comparison.

Receber resultados por webhook

Adicione um destino HTTP(S) em Organização → Integrações → Chaves API → Gerir webhooks. Subscreva rental.departure.completed, rental.return.completed e, se necessário, rental.report.pdf_ready. Verifique a assinatura com o segredo do destino e recupere o relatório pela API: o webhook é uma notificação, não o relatório completo. Consulte webhooks e recuperação.

Fluxo principal

1. Veículo: PUT /v1/vehicles/by-external/{external_id} cria ou atualiza o veículo associado ao seu ID estável.
2. Dossier e planeamento: PUT /v1/rentals/by-external/{external_id} associa a reserva e coloca-a imediatamente no planeamento. Apenas vehicle_external_id é obrigatório; os outros dados são opcionais. Guarde Rental id e planning.entry_id e use uma revisão posterior para alterações.
3. Entrega: POST /v1/rentals/{rental_id}/inspections com {"type":"departure"} cria ou retoma a inspeção. Envie Idempotency-Key. A criação devolve 201 e already_started: false; uma chamada posterior devolve a mesma inspeção com 200 e already_started: true. Abra launch_url; o colaborador autentica-se.
4. Resultado da entrega: após validação, rental.departure.completed sinaliza o relatório inicial. Obtenha JSON e PDF quando estiver pronto.
5. Devolução: chame o mesmo endpoint com {"type":"return"}. rental.return.completed anuncia o relatório de comparação, cujo tipo é comparison, não return.

Se perder um evento, use GET /v1/events e releia o recurso atual.

Outros percursos suportados

• GET /v1/inspections/{inspection_id} lê o estado; /launch renova uma ligação expirada.
• Os anexos Rental são documentos privados, distintos das fotografias oficiais. Aparecem automaticamente como contexto só de leitura no fluxo humano.
• As rotas de evidence disponibilizam metadados limpos e originais individuais ou em ZIP. O contrato nunca expõe máscaras, contornos, imagens anotadas ou URLs de armazenamento. Consulte Relatórios e provas.
• A extração da carta propõe dados para revisão e não altera silenciosamente um condutor confirmado.

A referência da API define campos, limites e respostas exatos. Consulte sincronização e erros para atualizações fora de ordem.