Intégrer

Le parcours complet

Tous les états d'un envoi, qui les provoque, et ce que votre système doit faire à chaque étape.

La chaîne, du devis à l'argent

  vous                 Rapidy                     terrain
  ────                 ──────                     ───────
  createQuote    →     prix ferme
  createShipment →     envoi créé          (paiement prépayé ouvert si le profil l'exige)
  markReady      →     course dispatchée   →      un livreur reçoit l'offre
                                           ←      il accepte
                       enlèvement          ←      il récupère le colis chez vous
                       en transit          →      suivi public alimenté
                       livraison           ←      il remet le colis (et encaisse si COD)
                       remise du cash      ←      il dépose l'espèce
                       réconciliation      →      vous êtes crédité

Vous n'intervenez que sur les trois premières flèches. Le reste vous parvient par webhook.

Étape par étape

1. Le devis

createQuote rend un prix ferme jusqu'à expiresAt. Passé ce délai, il faut redemander : accepter un devis périmé est refusé.

Le prix dépend du couple de quartiers, du poids et — si vous fournissez coords — de la distance réelle.

2. L'envoi

createShipment transforme un devis accepté en envoi. C'est ici que se décide qui paie quoi : voir Paiement.

Si le profil de paiement exige un prépaiement, Rapidy ouvre le paiement à cet instant et vous rend le lien à présenter au client.

3. Prêt à enlever

C'est ce geste — et lui seul — qui fait entrer la course dans la file d'affectation. Sans markReady, un envoi créé attend indéfiniment : aucun livreur ne se voit proposer la mission, et rien ne le signale dans votre back-office.

Appelez-le quand le colis est physiquement prêt — emballé, étiqueté, à portée de main. Un livreur qui se déplace pour rien coûte à tout le monde.

4. L'affectation

Rapidy propose la mission aux livreurs selon la stratégie de votre organisation : priorité à vos propres livreurs avec débordement vers la flotte Rapidy, ou affectation manuelle par un opérateur. Le livreur accepte ou refuse ; s'il se retire après avoir accepté, la course est re-dispatchée automatiquement et l'identifiant de l'envoi ne change pas.

5. L'enlèvement et le transit

Le livreur atteste l'enlèvement, puis la course passe en transit. Le suivi public est alimenté à chaque jalon.

6. La livraison

Le livreur remet le colis et — selon le profil — encaisse. La preuve de livraison est attestée par le destinataire.

7. L'argent

C'est l'étape qu'on oublie de modéliser, et celle qui fait mal quand elle est fausse.

La livraison ne vous crédite pas. Tant que l'espèce n'a pas été physiquement remise, elle est dans la sacoche du livreur : la réconciliation n'a pas lieu, et votre règlement n'est pas ouvert. C'est voulu — l'inverse ferait porter à la plateforme un risque qu'elle n'a pas accepté.

Une fois la remise constatée, la réconciliation s'exécute automatiquement et votre règlement est ouvert. Voir Paiement.

Les états d'un envoi

État	Ce qui vient de se passer	Ce que vous pouvez faire
Créé	L'envoi existe, rien n'est lancé.	`markReady`, `cancelShipment`
En recherche	Un livreur est cherché.	`cancelShipment`
Affecté	Un livreur a accepté.	`cancelShipment` (encore possible)
Enlevé	Le colis a quitté vos mains.	plus d'annulation — `openDispute`
En transit	En route vers le destinataire.	`openDispute`
Livré	Remis, avec preuve.	`openDispute`
Annulé	Arrêté avant enlèvement.	—

L'annulation cesse d'être possible dès que le colis est enlevé : au-delà, l'API répond 409 et le recours s'appelle un litige.

Ne pas interroger en boucle

Interroger getShipment toutes les cinq secondes fonctionne et coûte à tout le monde, vous compris — le quota d'appels s'y épuise. Abonnez-vous aux webhooks : vous serez prévenu à chaque changement, sans attendre.