Démarrer
Concepts clés
Le vocabulaire de Rapidy, et les règles qui ne se devinent pas.
Organisation
Votre compte Rapidy est une organisation — une boutique, une marketplace, un transporteur. Toutes vos données lui sont rattachées, et votre clé d'API la désigne. Une clé ne voit jamais les données d'une autre organisation.
Dans les interfaces destinées aux marchands, on dit toujours « organisation ». Le terme technique « tenant » n'apparaît pas à l'écran, et pas davantage ici.
Devis, envoi, course
Trois objets distincts, souvent confondus :
| Objet | Ce que c'est | Durée de vie |
|---|---|---|
Devis (qte_…) | Un prix ferme pour un trajet donné. | Jusqu'à expiresAt. |
Envoi (shp_…) | Le colis, son itinéraire, son paiement, son suivi. | Du devis accepté à la livraison. |
| Course | La mission confiée à un livreur pour cet envoi. | Créée à markReady, refaite si le livreur se retire. |
Vous manipulez le devis et l'envoi. La course est notre affaire : si un livreur accepte puis se retire, Rapidy re-dispatche sans que vous ayez à intervenir — l'envoi, lui, ne change pas d'identifiant.
city est le quartier
La règle qui coûte le plus cher quand on l'ignore. city
désigne le quartier (« Médina », « Ouakam », « Pikine Est »), jamais la
ville. C'est le quartier qui détermine la zone tarifaire. Envoyer « Dakar » fait sortir
le tarif de repli — le plus élevé — et personne ne s'en aperçoit avant la facture.
address porte le détail : la rue, le numéro, le repère. Joignez coords quand vous les avez : le prix suit alors la distance réelle plutôt que la zone.
Montants et devise
Les montants sont exprimés en XOF, dans l'unité mineure. Le franc CFA n'ayant pas de sous-unité, la valeur mineure EST le montant : 10000 vaut dix mille francs.
Ne divisez jamais par 100 sur cette devise. C'est la source classique d'un facteur cent, dans un sens ou dans l'autre.
Identifiants
Chaque entité porte un préfixe : shp_ pour un envoi, qte_ pour un devis, drv_ pour un livreur, usr_ pour un utilisateur. Le préfixe dit le type ; le reste est opaque. Ne le découpez pas, ne le devinez pas, ne l'affichez pas à un client final.
Votre référence de commande
external_order_id est votre identifiant, celui que votre boutique connaît déjà. Renseignez-le à la création : vous pourrez retrouver l'envoi avec getShipmentByExternalOrder sans stocker nos identifiants chez vous. C'est le chemin de rattrapage quand la correspondance a été perdue d'un côté.
Deux surfaces, deux régimes
| Surface | Authentification | Ce qu'on y trouve |
|---|---|---|
| API | Clé pk_… dans X-Api-Key | Tout ce qui concerne votre organisation. |
| Suivi public | Aucune | La vue destinée au client final, expurgée des données personnelles de tiers. |
Les SDK n'envoient pas votre clé sur la surface publique. C'est délibéré : la poster là ferait figurer votre clé dans des journaux d'accès qui ne sont pas les vôtres. Un test dédié le vérifie dans les huit SDK.
Casse du fil
Le format d'échange est en snake_case : order_amount_xof, external_order_id, shipment_id. Les SDK typés (TypeScript, Dart) exposent du camelCase et traduisent pour vous ; les autres passent les clés telles quelles.