API REST · v1

Intégrer Cap Convoi 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.

Demander une clé API

Voir la référence →

Cap Convoi · Live opsOnline

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. Early-access partenaires marketplaces / TMS ouvert sur demande pour valider les intégrations en amont.

4 endpoints

CRUD missions de base

Webhooks HMAC

Push signé SHA-256

Auth Endpoints Webhooks Sandbox Clé API

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 et révocables.

· Idempotency-Key (UUID) sur toutes les POST
· Rate limit : 60 req/min/clé (Scale), 600 sur demande
· Erreurs : { success: false, error: string }

curl — création d'une mission

curl -X POST https://api.capconvoi.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"
        }
      }'

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://capconvoi.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 Convoi envoie un POST signé HMAC-SHA256 (header X-CapConvoi-Signature) à chaque événement : mission.assigned, mission.in_transit, mission.delivered, mission.invoiced, mission.cancelled. Retry exponentiel avec jitter (5 tentatives sur 24 h).

Payload exemple — mission.delivered

POST https://votre-domaine/webhooks/capconvoi
X-CapConvoi-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://capconvoi.fr/edl/...pdf"
  }
}

Sandbox

Environnement api-sandbox.capconvoi.fr avec données fictives + génération synthétique d’événements webhook (CI friendly).

Roadmap 2026

SDK TypeScript officiel, OpenAPI 3.1 publique, collection Postman — remis avec la clé API.

Early-access partenaires

Contact compliance pour valider votre intégration avant le live.

compliance@capconvoi.fr

Forfait Scale