API partenaire Konvoi

Ce que fait l’API partenaire

Envoyez n’importe quel document de flotte et recevez des données structurées, synchronisez véhicules et affectations avec vos propres systèmes, et lisez inspections, incidents et positions des véhicules.

Traitement de documents

Téléversez amendes, certificats d’immatriculation, factures, tickets de carburant ou attestations d’assurance et recevez des données structurées.

Synchronisation de la flotte

Créez et mettez à jour véhicules et affectations depuis votre propre système de gestion de flotte, avec vos identifiants externes.

Utilisateurs et chauffeurs

Créez et gérez les fiches chauffeurs avec correspondance des identifiants externes.

Automatisation des workflows

Alimentez Konvoi en documents depuis n8n ou vos propres workflows, et réagissez aux webhooks.

Authentification

1. 01Obtenir l’accès. Demandez-nous d’activer l’API partenaire pour votre espace de travail.
2. 02Créer un jeton. Dans Konvoi, ouvrez les paramètres « Partner API » et créez un jeton avec les scopes dont vous avez besoin.
3. 03L’envoyer. Placez le jeton dans l’en-tête Authorization de chaque requête.

Scopes

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

Exemples

Téléverser et traiter un document

Le traitement est asynchrone : téléversez un document, puis interrogez l’API jusqu’à obtenir le résultat. Cela fonctionne pour tout type de document ; Konvoi le classe et en extrait les champs.

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

Interrogez l’API jusqu’à ce que le statut soit processed :

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

Téléversement multipart

Pour les fichiers volumineux, envoyez du multipart/form-data et évitez le surcoût du base64.

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

Un PDF contenant plusieurs documents

Quand un PDF contient plusieurs documents, l’API propose des segments et attend. Ajustez-les si nécessaire, puis confirmez le découpage.

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

Véhicules

Créez des véhicules avec votre propre identifiant externe, et recherchez-les par plaque.

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

Enregistrez jusqu’à cinq endpoints par espace de travail. Chaque livraison est un POST signé en HMAC-SHA256 ; vérifiez la signature avant de vous fier au contenu. Envoyez un ping de test et consultez chaque livraison dans le journal.