API CONVOY
L'API REST CONVOY vous permet de créer et de suivre des livraisons express par programmation — depuis votre boutique, votre back-office ou votre marketplace. Une livraison se crée en un seul appel et son cycle de vie complet est exposé via des webhooks signés.
Présentation
L'API est organisée autour des ressources REST, accepte des corps de requête encodés en JSON, renvoie des réponses JSON et utilise les codes de statut HTTP, l'authentification et les verbes standard. Toutes les requêtes doivent être effectuées en HTTPS.
| URL de base | https://convoyapp.fr/api/v1 |
| Version | v1 — versionnée dans le chemin d'URL. |
| Format | JSON (Content-Type: application/json) en requête comme en réponse. |
| Authentification | Clé API secrète via l'en-tête Authorization: Bearer. |
| Paiement | Carte enregistrée dans l'espace entreprise : montant bloqué à la création, débité à la livraison. |
Environnements
Chaque environnement CONVOY émet ses propres clés, reconnaissables à leur préfixe. Une clé n'est valable que sur l'environnement qui l'a émise : une clé de test est refusée par la production, et inversement.
| Environnement | Préfixe de clé | Effet |
|---|---|---|
| Test | cvk_test_… | Environnement de recette : paiements Stripe de test (cartes de test), aucun débit réel. |
| Live | cvk_live_… | Livraisons réelles, coursiers réels, débit de la carte enregistrée. |
Démarrage rapide
Enregistrez d'abord une carte et créez une clé dans l'espace entreprise. Indiquez ensuite une adresse d'enlèvement, une adresse de livraison et un type de véhicule : CONVOY calcule le prix, bloque le montant sur votre carte, lance la recherche d'un coursier et renvoie immédiatement la livraison.
curl -X POST https://convoyapp.fr/api/v1/deliveries \
-H "Authorization: Bearer cvk_live_•••" \
-H "Content-Type: application/json" \
-d '{
"pickup": { "address": "24 rue Oberkampf, 75011 Paris" },
"dropoff": { "address": "10 rue de Rivoli, 75004 Paris" },
"vehicle": "moto",
"service": "express"
}'Réponse — la livraison est créée et la recherche de coursier démarre :
{
"id": "ord_3f9a1c27b84d6e05a2c1",
"object": "delivery",
"status": "SEARCHING_DRIVER",
"reference": "C-4KP9QX",
"service": "express",
"vehicle": "moto",
"pickup": { "address": "24 rue Oberkampf, 75011 Paris", … },
"dropoff": { "address": "10 rue de Rivoli, 75004 Paris", … },
"price": { "amount": 9.35, "currency": "EUR" },
"distance_km": 3.6,
"eta_min": 11,
"proof": "otp",
"otp": "4821",
"payment": { "status": "authorized", "payment_url": null, "failure_code": null },
"tracking_url": "https://convoyapp.fr/suivi/ord_3f9a…?t=…",
"created_at": "2026-11-03T09:24:11.000Z"
}PENDING_PAYMENT et payment.payment_url donne une page de paiement à ouvrir ; sans paiement sous 30 minutes, elle expire.