Começar

A API pública suporta atualmente Rental. O seu sistema pode sincronizar veículos e dossiers Rental, preparar inspeções e obter resultados validados. A referência da API é o contrato exato de cada pedido e resposta.

1. Criar uma chave

Um administrador abre API e integrações na aplicação e cria uma chave. O acesso depende do plano Rental da organização. Atribua uma chave a cada integração; o segredo completo só é apresentado uma vez. Consulte autenticação e acesso.

O URL base é https://api.trakaria.com. Os pedidos efetuados com a chave afetam dados reais da sua conta.

2. Verificar acesso e limites

Defina a chave no terminal sem a guardar no código-fonte e faça um pedido apenas de leitura:

export TRAKARIA_API_KEY='your-api-key'
curl --fail-with-body --silent --show-error \
  -H "Authorization: Bearer ${TRAKARIA_API_KEY}" \
  https://api.trakaria.com/v1/capabilities

A resposta apresenta as funcionalidades e os limites Rental efetivos. 401 indica uma credencial inválida ou expirada; 403 pode indicar que a operação ou o plano não está disponível. Consulte sincronização e erros.

3. Sincronizar um veículo e um dossier Rental

Para um teste, utilize identificadores externos únicos e reconhecíveis e evite dados reais de clientes. Os pedidos seguintes criam registos na conta. Reutilize o mesmo ID externo para atualizar a mesma entidade e conserve os id públicos devolvidos.

curl --fail-with-body --silent --show-error \
  -X PUT 'https://api.trakaria.com/v1/vehicles/by-external/demo-vehicle-001' \
  -H "Authorization: Bearer ${TRAKARIA_API_KEY}" \
  -H 'Content-Type: application/json' \
  -d '{"plate":"AA-123-AA","name":"Veículo de demonstração","photo_url":"https://cdn.example.com/fleet/demo-vehicle-001.jpg","make":"Example","model":"Car","trim":"Business","year":2025,"registration_date":"2025-03-20","vehicle_type":"hatchback","energy":"petrol","gearbox":"automatic","transmission":"fwd","color":"Blue","mileage":12000,"source_revision":1}'

curl --fail-with-body --silent --show-error \
  -X PUT 'https://api.trakaria.com/v1/rentals/by-external/demo-reservation-001' \
  -H "Authorization: Bearer ${TRAKARIA_API_KEY}" \
  -H 'Content-Type: application/json' \
  -d '{"vehicle_external_id":"demo-vehicle-001","source_revision":1}'

O segundo pedido cria imediatamente uma entrada visível no planeamento. A resposta contém o Rental id e planning.entry_id. Apenas vehicle_external_id é obrigatório no corpo; datas, referências, locais, contacto e condutores são opcionais e podem ser enviados antecipadamente, na entrega física ou mais tarde. Sem hora de saída, é usada a hora de criação; sem hora de devolução, a entrada fica em aberto.

Nas alterações seguintes, use uma source_revision estritamente crescente. Campos omitidos mantêm o valor e a mesma entrada de planeamento é atualizada. Um upsert de veículo também o atribui à organização da chave; repetir um pedido sem alterações reconcilia essa atribuição em segurança.

Após o teste, reveja os registos no TrakarIA. A API pode cancelar um Rental antes da entrega através de POST /v1/rentals/{rental_id}/cancel, cancelando também o planeamento. Não existe um DELETE geral, e cancelar não elimina o histórico.

4. Continuar o fluxo de inspeção

Use o Rental id público — não o ID externo nem o de planeamento — para preparar a inspeção de entrega:

export RENTAL_ID='rental_...'
export DEPARTURE_IDEMPOTENCY_KEY="departure-${RENTAL_ID}"

curl --fail-with-body --silent --show-error \
  -X POST "https://api.trakaria.com/v1/rentals/${RENTAL_ID}/inspections" \
  -H "Authorization: Bearer ${TRAKARIA_API_KEY}" \
  -H 'Content-Type: application/json' \
  -H "Idempotency-Key: ${DEPARTURE_IDEMPOTENCY_KEY}" \
  -d '{"type":"departure"}'

O pedido prepara ou retoma a mesma inspeção: 201 significa criada; 200, já existente. Após timeout, perda de ligação, 503 ou REQUEST_ALREADY_PROCESSING, repita o mesmo método, caminho e corpo com a mesma Idempotency-Key. Não crie outro Rental nem outro ID externo. Nunca envie detalhes privados do Kernel como IDs de ciclo, revisões, ETag, If-Match ou expectedRevision.

Um utilizador TrakarIA deve iniciar sessão no launch_url e validar o estado do veículo. O pedido API não substitui essa validação humana. Depois obtenha o relatório de departure; após a devolução, prepare return e obtenha comparison. Consulte o fluxo Rental, a referência API e os webhooks.