API publique partenaires — REST + Webhooks | Cap Convoie
Cap Convoie
API REST · v1

Intégrer Cap Convoie dans votre SI fleet ou TMS

API REST publique pour créer, lire et annuler des missions depuis votre back-office. Webhooks signés pour recevoir les transitions de statut. Accès inclus dans le forfait Scale ou ouvert sur demande compliance pour les autres cas.

Statut v1 : documentation préfigurative. L’API publique est en construction (disponibilité visée Q4 2026). Un endpoint GET /api/v1/missions répond actuellement en 503 api_not_yet_live avec lien vers ce contact compliance. Early-access partenaires marketplaces / TMS ouvert sur demande pour valider les intégrations en amont.

Authentification

Bearer token par compte client

Toutes les requêtes nécessitent un header Authorization: Bearer ck_live_... (ou ck_test_... en sandbox). Tokens scopés par permission (missions:read, missions:write, webhooks:manage) et révocables à tout moment depuis le portail compliance.

curl — création d'une mission

curl -X POST https://api.capconvoie.fr/v1/missions \
  -H "Authorization: Bearer ck_live_xxxxxxxxxxxxxx" \
  -H "Content-Type: application/json" \
  -H "Idempotency-Key: $(uuidgen)" \
  -d '{
        "vehicleType": "VL",
        "fromCity": "Paris",
        "toCity": "Lyon",
        "addressFrom": "10 av des Champs-Élysées, 75008 Paris",
        "addressTo": "5 rue Garibaldi, 69003 Lyon",
        "desiredDate": "2026-06-12",
        "urgency": false,
        "contact": {
          "name": "Sophie Dupont",
          "email": "sophie@loueur.fr",
          "phone": "+33612345678",
          "companyName": "Loueur National SAS",
          "siret": "12345678901234"
        }
      }'
  • · Idempotency-Key (UUID) sur toutes les POST → évite les double-créations en cas de retry.
  • · Rate limit : 60 req/min/clé (Scale), 600 req/min/clé sur demande pour les marketplaces.
  • · Réponses : JSON UTF-8 strict. Erreurs au format { success: false, error: string, code?: string }.

Référence

Endpoints v1

  • POST/missionsscope missions:write

    Crée une nouvelle mission de convoyage. Retourne une référence opposable et une URL de suivi.

    Body

    {
  "vehicleType": "VL",
  "fromCity": "Paris",
  "toCity": "Lyon",
  "addressFrom": "10 av des Champs-Élysées, 75008 Paris",
  "addressTo": "5 rue Garibaldi, 69003 Lyon",
  "desiredDate": "2026-06-12",
  "urgency": false,
  "contact": {
    "name": "Sophie Dupont",
    "email": "sophie@loueur.fr",
    "phone": "+33612345678",
    "companyName": "Loueur National SAS",
    "siret": "12345678901234"
  }
}

    Réponse 200

    {
  "success": true,
  "reference": "CC-20260612-A7B3",
  "trackingUrl": "https://capconvoie.fr/suivi/CC-20260612-A7B3",
  "estimateHt": { "min": 396, "max": 437 },
  "status": "draft"
}
  • GET/missions/{reference}scope missions:read

    Lit l'état d'une mission (statut, événements, convoyeur affecté).

    Réponse 200

    {
  "success": true,
  "mission": {
    "reference": "CC-20260612-A7B3",
    "currentStatus": "in_transit",
    "fromCity": "Paris",
    "toCity": "Lyon",
    "driverInitials": "J.M.",
    "eta": "2026-06-12T13:30:00Z",
    "events": [
      { "status": "draft", "at": "2026-06-10T09:12:00Z" },
      { "status": "assigned", "at": "2026-06-10T09:35:00Z" },
      { "status": "in_transit", "at": "2026-06-12T08:45:00Z" }
    ]
  }
}
  • POST/missions/{reference}/cancelscope missions:write

    Annule une mission non encore démarrée. Voir CGV art. 9 pour les conditions de retenue.

    Body

    {
  "reason": "Client final injoignable",
  "requestRefund": true
}

    Réponse 200

    {
  "success": true,
  "cancelled": true,
  "retentionPct": 30,
  "refundEur": 287.5
}
  • GET/missionsscope missions:read

    Liste paginée des missions du compte (filtres status, dateRange, country).

    Réponse 200

    {
  "success": true,
  "items": [/* ... */],
  "pagination": { "page": 1, "pageSize": 50, "total": 234 }
}

Webhooks signés

Recevez chaque transition de statut en push

Configurez une URL HTTPS dans le portail compliance. Cap Convoie envoie un POST signé HMAC-SHA256 (header X-CapConvoie-Signature) à chaque événement : mission.assigned, mission.in_transit, mission.delivered, mission.invoiced, mission.cancelled. Retry exponentiel avec jitter (5 tentatives sur 24 h) si vous renvoyez un code >= 500.

Payload exemple — mission.delivered

POST https://votre-domaine/webhooks/capconvoie
X-CapConvoie-Signature: t=1748520000,v1=2c6e...
Content-Type: application/json

{
  "id": "evt_01HXYZ...",
  "type": "mission.delivered",
  "createdAt": "2026-06-12T14:02:13Z",
  "mission": {
    "reference": "CC-20260612-A7B3",
    "currentStatus": "delivered",
    "deliveryEdlUrl": "https://capconvoie.fr/edl/...pdf"
  }
}

Sandbox & roadmap

Environnement sandbox api-sandbox.capconvoie.fr avec données fictives + génération synthétique d’événements webhook (utile pour les intégrations CI). En route 2026 : SDK TypeScript officiel, OpenAPI 3.1 publique, postman collection.

Documentation détaillée et changelog versionné : remis avec la clé API lors de l’ouverture d’accès. Contact : compliance@capconvoie.fr.