Aan de slag

De publieke API ondersteunt momenteel Rental. Je systeem kan voertuigen en Rental-dossiers synchroniseren, inspecties voorbereiden en gevalideerde resultaten ophalen. De API-referentie is het exacte contract voor iedere aanvraag en reactie.

1. Maak een sleutel

Een organisatiebeheerder opent API & integraties in TrakarIA en maakt een API-sleutel. Toegang hangt af van het Rental-abonnement. Geef elke integratie een eigen sleutel; het volledige geheim wordt maar één keer getoond. Lees hoe authenticatie werkt.

De basis-URL is https://api.trakaria.com. Aanvragen met de sleutel wijzigen echte gegevens van je account.

2. Controleer toegang en limieten

Plaats de sleutel in je terminal zonder hem aan broncode toe te voegen en voer een alleen-lezen aanvraag uit:

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

De reactie vermeldt de actuele Rental-functies en limieten. 401 betekent dat de credential ongeldig of verlopen is; 403 kan betekenen dat de bewerking of het abonnement niet beschikbaar is. Zie synchronisatie en fouten.

3. Synchroniseer een voertuig en Rental-dossier

Gebruik voor een test herkenbare, unieke externe ID’s en geen echte klantgegevens. De volgende aanvragen maken records in je account. Herhaal hetzelfde externe ID om dezelfde resource bij te werken en bewaar de publieke id-waarden.

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":"Demovoertuig","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}'

De tweede aanvraag maakt direct een zichtbare planningsvermelding. De reactie bevat Rental id en planning.entry_id. Alleen vehicle_external_id is verplicht in de body; datums, referenties, locaties, contact en bestuurders zijn optioneel en mogen vooraf, bij de fysieke uitgifte of later worden aangevuld. Zonder vertrektijd gebruikt TrakarIA het creatiemoment; zonder retourtijd blijft de planning open.

Gebruik voor latere inhoudelijke wijzigingen een strikt oplopende source_revision. Weggelaten velden behouden hun waarde en dezelfde planningsvermelding wordt bijgewerkt. Een geslaagde voertuig-upsert wijst het voertuig ook toe aan de organisatie van de API-sleutel, zodat bevoegde groepsleden het zien. Een ongewijzigde herhaling herstelt die koppeling veilig wanneer nodig.

Controleer testrecords achteraf in TrakarIA en ruim ze op via de beschikbare groepsacties. De API kan een Rental vóór vertrek annuleren met POST /v1/rentals/{rental_id}/cancel, inclusief de planningsvermelding. Er is geen algemene DELETE-route; annuleren wist de historie niet.

4. Ga verder met de inspectie

Gebruik de publieke Rental id — niet het externe of plannings-ID — om vertrek voor te bereiden:

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"}'

Deze aanroep maakt dezelfde inspectie of hervat haar: 201 betekent nieuw, 200 betekent al aanwezig. Na timeout, verbindingsverlies, 503 of REQUEST_ALREADY_PROCESSING herhaal je dezelfde methode, route en body met dezelfde Idempotency-Key. Maak geen nieuw Rental- of extern ID. Stuur nooit private Kernel-details zoals cycle-ID’s, ETag, If-Match of expectedRevision.

Een TrakarIA-gebruiker moet zich aanmelden via de ontvangen launch_url en de voertuigstaat valideren. De API-aanroep voert die menselijke validatie niet uit. Haal daarna het departure-rapport op; bereid na de retour een return-inspectie voor en haal het comparison-rapport op. Zie de volledige Rental-workflow, API-referentie en webhooks.