Konvoi Partner API

Wat de Partner API doet

Stuur eender welk vlootdocument en krijg gestructureerde data terug, houd voertuigen en toewijzingen gelijk met je eigen systemen, en lees inspecties, incidenten en voertuigposities uit.

Documentverwerking

Upload boetes, inschrijvingsbewijzen, facturen, tankbonnen of verzekeringsattesten en krijg gestructureerde data terug.

Vlootsynchronisatie

Maak voertuigen en toewijzingen aan en werk ze bij vanuit je eigen vlootsysteem, met je eigen externe ID’s.

Gebruikers en chauffeurs

Maak chauffeursgegevens aan en beheer ze, met koppeling aan externe ID’s.

Workflowautomatisering

Voer documenten aan vanuit n8n of je eigen workflows, en reageer op webhooks.

Authenticatie

1. 01Toegang krijgen. Vraag ons om de Partner API in te schakelen voor je werkruimte.
2. 02Een token aanmaken. Open in Konvoi de instellingen van de Partner API en maak een token aan met de scopes die je nodig hebt.
3. 03Meesturen. Zet het token in de Authorization-header van elke request.

Scopes

curl -H "Authorization: Bearer YOUR_TOKEN" \
  https://konvoi.ai/api/partner/v1/health

Voorbeelden

Een document uploaden en verwerken

De verwerking is asynchroon: upload een document en vraag daarna het resultaat op. Het werkt voor elk documenttype; Konvoi classificeert het en leest de velden uit.

curl -X POST https://konvoi.ai/api/partner/v1/documents \
  -H "Authorization: Bearer YOUR_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{"document": "<base64-encoded-pdf>", "filename": "scan.pdf"}'

# → {"success": true, "id": "clx1abc2300001234", "status": "processing", "filename": "scan.pdf"}

Vraag op tot de status processed is:

curl https://konvoi.ai/api/partner/v1/documents/clx1abc2300001234 \
  -H "Authorization: Bearer YOUR_TOKEN"

{
  "id": "clx1abc2300001234",
  "status": "processed",
  "documentClass": "FINE",
  "classificationConfidence": 0.95,
  "data": {
    "referenceNumber": "PV-2024-12345",
    "amount": 58.00,
    "currency": "EUR",
    "type": "SPEEDING",
    "licensePlate": "1-ABC-123",
    "violationAddress": "Kortrijksesteenweg 123",
    "issuerName": "Politiezone Gent"
  }
}

Multipart-upload

Stuur grote bestanden als multipart/form-data en vermijd de overhead van base64.

curl -X POST https://konvoi.ai/api/partner/v1/documents \
  -H "Authorization: Bearer YOUR_TOKEN" \
  -F "[email protected]"

Een PDF met meerdere documenten

Als een PDF meerdere documenten bevat, stelt de API segmenten voor en wacht. Pas ze aan als dat nodig is en bevestig dan de splitsing.

# Polling returns the proposed segments
GET  /v1/documents/:id          → {"status": "awaiting_split", "segments": [...]}

# Optionally adjust them
PATCH /v1/documents/:id/segments

# Confirm: each segment becomes its own document
POST /v1/documents/:id/split    → {"success": true, "status": "splitting"}

Voertuigen

Maak voertuigen aan met je eigen externe ID, en zoek op nummerplaat.

curl -X POST https://konvoi.ai/api/partner/v1/vehicles \
  -H "Authorization: Bearer YOUR_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{"vin": "WVWZZZ3CZWE123456", "make": "Volkswagen", "model": "Golf",
       "year": 2023, "type": "CAR", "externalId": "fleet_vehicle_001"}'

curl "https://konvoi.ai/api/partner/v1/vehicles?search=1-ABC-123" \
  -H "Authorization: Bearer YOUR_TOKEN"

Webhooks

Registreer tot vijf endpoints per werkruimte. Elke levering is een POST ondertekend met HMAC-SHA256; controleer de handtekening voor je de body vertrouwt. Stuur een testping en bekijk elke levering in het logboek.