Livraisons

La livraison est la ressource centrale de l'API. Elle représente l'acheminement d'un colis (ou le convoyage d'un véhicule) d'un point d'enlèvement vers un point de livraison. Créez, récupérez, listez et annulez vos livraisons via les endpoints ci-dessous.

Endpoints

Méthode	Endpoint	Description
POST	/api/v1/deliveries	Créer une livraison (montant bloqué sur la carte enregistrée).
GET	/api/v1/deliveries/{id}	Récupérer une livraison.
GET	/api/v1/deliveries	Lister les livraisons.
POST	/api/v1/deliveries/{id}/cancel	Annuler une livraison avant l'enlèvement.

Créer une livraison

POST/api/v1/deliveries

Crée une livraison, bloque son montant sur la carte enregistrée dans l'espace entreprise et lance la recherche d'un coursier. Le prix est toujours calculé par CONVOY (distance routière et véhicule). Les objets pickup et dropoff prennent une adresse postale complète, géocodée automatiquement.

Paramètres du corps

Paramètre	Type	Description
pickuprequis	object	Point d'enlèvement. Voir l'objet `address` ci-dessous.
dropoffrequis	object	Point de livraison, même structure que pickup.
vehiclerequis	enum	Type de véhicule : `bike`, `moto`, `car`, `van` ou `xl`. Ignoré pour un convoyage.
serviceoptionnel	enum	`express` (immédiate, par défaut) ou `vehicle_transfer` (convoyage de véhicule, si ce service est proposé). Les livraisons programmées ne sont pas proposées.
packageoptionnel	object	Description du colis : `label` (100 caractères), `weight_kg`, `fragile` (booléen, supplément tarifaire).
proofoptionnel	enum	Preuve de livraison : `otp` (code à 4 chiffres remis au destinataire, par défaut) ou `photo` (dépôt en boîte aux lettres, photographié par le coursier).
metadataoptionnel	object	Paires clé/valeur libres rattachées à la livraison (ex. votre identifiant de commande) : 20 clés au plus, de 40 caractères (lettres, chiffres, `_ . -`), valeurs de 500 caractères.

Objet address

Paramètre	Type	Description
addressrequis	string	Adresse postale complète, ex. « 24 rue Oberkampf, 75011 Paris » (200 caractères).
contact_nameoptionnel	string	Nom de la personne à contacter sur place.
contact_phoneoptionnel	string	Téléphone du contact, au format E.164.
instructionsoptionnel	string	Consignes (étage, code, interphone…), 500 caractères.

Exemple de requête

POST /api/v1/deliveries

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",
      "contact_name": "Studio Rivoli",
      "contact_phone": "+33611223344",
      "instructions": "2e étage, code 1789B"
    },
    "dropoff": {
      "address": "10 rue de Rivoli, 75004 Paris",
      "contact_name": "Camille Martin",
      "contact_phone": "+33655667788"
    },
    "vehicle": "moto",
    "service": "express",
    "package": { "label": "Documents", "weight_kg": 1.2, "fragile": false },
    "proof": "otp",
    "metadata": { "order_id": "CMD-90817" }
  }'

Réponse

Réponse · 201 Created

{
  "id": "ord_3f9a1c27b84d6e05a2c1",
  "object": "delivery",
  "status": "SEARCHING_DRIVER",
  "reference": "C-4KP9QX",
  "service": "express",
  "vehicle": "moto",
  "pickup": {
    "address": "24 rue Oberkampf, 75011 Paris",
    "contact_name": "Studio Rivoli",
    "contact_phone": "+33611223344",
    "instructions": "2e étage, code 1789B",
    "lat": 48.8649, "lng": 2.3703
  },
  "dropoff": { "address": "10 rue de Rivoli, 75004 Paris", "contact_name": "Camille Martin", … },
  "package": { "label": "Documents", "weight_kg": 1.2, "fragile": false },
  "price":   { "amount": 9.35, "currency": "EUR" },
  "distance_km": 3.6,
  "eta_min": 11,
  "proof": "otp",
  "otp": "4821",
  "driver": null,
  "payment": { "status": "authorized", "payment_url": null, "failure_code": null },
  "tracking_url": "https://convoyapp.fr/suivi/ord_3f9a…?t=…",
  "metadata": { "order_id": "CMD-90817" },
  "created_at": "2026-11-03T09:24:11.000Z",
  "updated_at": "2026-11-03T09:24:12.000Z",
  "delivered_at": null,
  "canceled_at": null
}

Paiement

Le montant est bloqué sur votre carte enregistrée à la création (payment.status vaut authorized) puis débité à la livraison (paid) ; il est libéré si la livraison est annulée ou qu'aucun coursier ne la prend (released).

Carte refusée ou authentification exigée

La livraison est tout de même créée, en PENDING_PAYMENT, avec payment.failure_code (card_declined, authentication_required…) et payment.payment_url : une page de paiement à ouvrir. Sans paiement sous 30 minutes, la livraison passe en EXPIRED. Sans carte enregistrée, la création est refusée (422 payment_method_required).

Récupérer une livraison

GET/api/v1/deliveries/{id}

Renvoie l'état courant d'une livraison : son statut, le coursier assigné, l'ETA et le code de remise (OTP). Une livraison d'un autre compte renvoie 404.

Exemple de réponse

Réponse · 200 OK

{
  "id": "ord_3f9a1c27b84d6e05a2c1",
  "object": "delivery",
  "status": "EN_ROUTE_DROPOFF",
  "reference": "C-4KP9QX",
  "service": "express",
  "vehicle": "moto",
  "eta_min": 7,
  "otp": "4821",
  "driver": {
    "name": "Karim M.",
    "rating": 4.9,
    "vehicle": "moto",
    "plate": "AB-512-CD"
  },
  "payment": { "status": "authorized", "payment_url": null, "failure_code": null },
  "tracking_url": "https://convoyapp.fr/suivi/ord_3f9a…?t=…",
  "updated_at": "2026-11-03T09:58:02.000Z",
  …
}

Code de remise et suivi

Le champ otp n'est renseigné que pour les livraisons dont la preuve est otp. Communiquez ce code au destinataire : le coursier le saisit pour valider la remise. Le lien tracking_url montre la position du coursier en direct, sans le code ni le prix : vous pouvez le transmettre au destinataire.

Lister les livraisons

GET/api/v1/deliveries

Renvoie une liste paginée de vos livraisons, des plus récentes aux plus anciennes.

Paramètres de requête

Paramètre	Type	Description
statusoptionnel	enum	Filtre sur un statut (ex. `DELIVERED`, `SEARCHING_DRIVER`).
limitoptionnel	integer	Nombre d'éléments à renvoyer (1 à 100, par défaut 20).
starting_afteroptionnel	string	Curseur de pagination : identifiant de livraison après lequel commencer.

Exemple

GET /api/v1/deliveries?status=DELIVERED&limit=2

curl "https://convoyapp.fr/api/v1/deliveries?status=DELIVERED&limit=2" \
  -H "Authorization: Bearer cvk_live_•••"

Réponse · 200 OK

{
  "object": "list",
  "has_more": true,
  "data": [
    { "id": "ord_3f9a1c27b84d6e05a2c1", "object": "delivery", "status": "DELIVERED", "reference": "C-4KP9QX", … },
    { "id": "ord_9b2e47d10c5a3f8e61d4", "object": "delivery", "status": "DELIVERED", "reference": "C-7MN2WR", … }
  ]
}

Annuler une livraison

POST/api/v1/deliveries/{id}/cancel

Annule une livraison tant que le coursier n'a pas récupéré le colis (statuts PENDING_PAYMENT, SEARCHING_DRIVER, EN_ROUTE_PICKUP, AT_PICKUP). Le montant bloqué est libéré : rien n'est débité. Au-delà, l'API répond 409 too_late.

Convoyage de véhicule

Lorsque ce service est proposé, un coursier titulaire du permis déplace un véhicule (et non un colis) entre deux points. Indiquez service: "vehicle_transfer" et l'objet vehicle_info ; le prix suit le barème du convoyage. Sinon, l'API répond 422 service_unavailable.

Champ	Type	Description
`vehicle_info.brand`	string · requis	Marque du véhicule convoyé.
`vehicle_info.plate`	string · requis	Immatriculation.
`vehicle_info.model`, `fuel`	string	Modèle et carburant, facultatifs.

POST /api/v1/deliveries

curl -X POST https://convoyapp.fr/api/v1/deliveries \
  -H "Authorization: Bearer cvk_live_•••" \
  -H "Content-Type: application/json" \
  -d '{
    "pickup":  { "address": "2 avenue de Paris, 78000 Versailles" },
    "dropoff": { "address": "12 avenue de la Gare, 92100 Boulogne-Billancourt" },
    "service": "vehicle_transfer",
    "vehicle_info": { "brand": "Peugeot", "model": "208", "plate": "AB-123-CD" }
  }'

Statuts d'une livraison

Le champ status suit ce cycle de vie. Chaque transition déclenche un webhook delivery.status_updated. La liste complète figure dans la référence.

Cycle de vie nominal

PENDING_PAYMENT  →  SEARCHING_DRIVER  →  EN_ROUTE_PICKUP  →  AT_PICKUP
        →  PICKED_UP  →  EN_ROUTE_DROPOFF  →  AT_DROPOFF  →  DELIVERED

Statuts terminaux

Une livraison se termine sur DELIVERED, CANCELED (annulée) ou EXPIRED (paiement non effectué ou aucun coursier disponible : rien n'est débité). Aucune transition n'intervient ensuite. INCIDENT signale une livraison suspendue, reprise par l'équipe CONVOY.

Pour aller plus loin

Webhooks→

Suivre chaque transition de statut en temps réel.

Statuts & véhicules→

Tableaux de référence complets.