API Ti Course pour les partenaires
Votre client choisit la livraison en commandant en click & collect sur votre site : votre système crée lui-même la course sur Ti Course. Un coursier retire la commande à votre commerce et la livre à votre client. Plus de double saisie, ni pour vous, ni pour votre client.
L'essentiel
- REST et JSON, version 1
- Clé d'API à créer dans votre espace partenaire
- Webhooks signés à chaque étape de la course
- Spécification OpenAPI à télécharger
1. Démarrer
- Demandez l'accès à Ti Course (ticourse@ticourseconnect.fr). L'accès s'ouvre compte par compte ; un accès d'essai (bac à sable : données d'essai, aucun paiement réel) peut être ouvert d'abord.
- Vérifiez l'adresse de votre commerce dans votre espace partenaire : c'est le point de retrait des courses.
- Créez une clé dans votre espace partenaire, rubrique « API et intégration ». Elle n'est montrée qu'une fois : rangez-la comme un mot de passe, côté serveur, jamais dans une page web ou une appli.
- Rechargez votre solde (par carte depuis la même rubrique, ou par virement) : chaque course est payée sur ce solde.
- Testez votre clé avec
GET /ping, puis créez une première course.
L'adresse de l'API est affichée dans votre espace partenaire, rubrique « API et intégration » (en production : https://api.ticourseconnect.fr/api/v1). Les clés de production commencent par tc_live_, celles du bac à sable par tc_test_.
2. Authentification
Chaque appel porte la clé dans l'en-tête Authorization :
curl https://api.ticourseconnect.fr/api/v1/ping \
-H "Authorization: Bearer tc_live_…"
Une clé ne sert qu'à l'API : elle n'ouvre pas votre espace partenaire. Vous pouvez en avoir plusieurs (une par système), et révoquer celle qui a pu fuiter depuis votre espace partenaire. Au plus 120 appels par minute et par clé ; au-delà, l'API répond 429 (code trop_de_requetes, en-tête Retry-After).
3. Créer une course
Facultatif, le devis donne le prix et la distance sans rien créer :
curl https://api.ticourseconnect.fr/api/v1/devis \
-H "Authorization: Bearer tc_live_…" -H "Content-Type: application/json" \
-d '{"taille": "M", "livraison": {"adresse": "5 rue Jean Chatel, 97400 Saint-Denis"}}'
Puis la course :
curl https://api.ticourseconnect.fr/api/v1/courses \
-H "Authorization: Bearer tc_live_…" -H "Content-Type: application/json" \
-H "Idempotency-Key: CMD-1042-1" \
-d '{
"reference_commande": "CMD-1042",
"taille": "M",
"destinataire": {"nom": "Marie Hoarau", "telephone": "+262 692 12 34 56"},
"livraison": {"adresse": "5 rue Jean Chatel, 97400 Saint-Denis", "precisions": "Bât. B, code 1234"},
"retrait": {"nom_sur_commande": "Hoarau", "plage": "dès 14 h"},
"instructions": "Sac isotherme."
}'
| Champ | Obligatoire | Rôle |
|---|---|---|
reference_commande | oui | Votre numéro de commande : le coursier le présente au retrait. Une seule course en cours par commande. |
taille | oui | S sac à dos, M cabas, L coffre, XL gros volume. |
destinataire.nom, destinataire.telephone | oui | Votre client, que le coursier peut appeler. |
livraison.adresse | oui | À La Réunion. Sans coordonnées, l'adresse est située par la Base Adresse Nationale ; si elle ne l'est pas sûrement, l'API répond adresse_introuvable. |
livraison.latitude, livraison.longitude | non | Recommandées si vous les avez (ensemble). |
livraison.precisions | non | Bâtiment, digicode, repère. |
retrait.nom_sur_commande, retrait.plage | non | Le nom sur la commande, quand elle peut être retirée. |
instructions | non | Consignes pour le coursier. |
prete | non | true par défaut : la course est proposée aux coursiers tout de suite. false : elle attend POST /courses/{id}/prete. |
creneau.date, creneau.heure | non | Livraison programmée (heure de La Réunion), à venir. |
La réponse (201) rend la course, avec son id, son prix et son code_livraison à 4 chiffres : transmettez ce code à votre client, le coursier le lui demande à la remise.
Doublons : envoyez un en-tête Idempotency-Key (8 à 64 caractères : lettres, chiffres, -, _). Si votre système renvoie la même demande avec la même clé (coupure réseau, nouvelle tentative), l'API rend la course déjà créée (200, en-tête Idempotent-Replayed: true) sans rien débiter de nouveau.
4. Suivre une course
GET /courses/{id} rend une course ; GET /courses la liste de vos courses (filtres statut, reference_commande, depuis, pages de 20 par défaut, 100 au plus). Mieux : recevez chaque étape par webhook.
| Statut | Signification |
|---|---|
en_preparation | Commande pas encore prête (créée avec prete: false). |
recherche_coursier | Proposée aux coursiers. |
coursier_assigne | Un coursier a accepté ; son nom et son téléphone sont dans la course. |
coursier_en_route | En route vers votre commerce. |
coursier_au_commerce | Au commerce, pour le retrait. |
en_livraison | Commande retirée, en route vers votre client. |
coursier_a_destination | Arrivé chez votre client. |
livree | Remise contre le code de livraison. |
terminee | Close 24 h après la livraison ; le coursier est payé. |
annulee | Annulée ; le prix réservé est rendu à votre solde. |
litige | Traitée par le support Ti Course. |
5. Préparer, annuler
POST /courses/{id}/prete : la commande créée avec prete: false est prête, la course part aux coursiers.
POST /courses/{id}/annuler (motif facultatif) : possible tant que le coursier n'a pas retiré la commande (en_preparation, recherche_coursier, coursier_assigne) ; le prix réservé est rendu à votre solde. Ensuite, l'API répond non_annulable : contactez le support.
Ces courses apparaissent aussi dans les demandes de votre espace partenaire, où vous pouvez les suivre et les marquer « Prête » ou « Remise au coursier ».
6. Webhooks
Réglez l'adresse de votre webhook dans votre espace partenaire (rubrique « API et intégration ») : https, port 443, nom d'hôte public (adresse IPv4 publique). Le secret de signature (whsec_…) n'est montré qu'à sa création. Le bouton « Envoyer un test » vous envoie un événement test.
Ti Course envoie un POST JSON à la création de la course (course.creee), puis à chaque changement de statut (course.<statut> : course.coursier_assigne, course.livree, course.annulee…).
POST /votre-webhook
Ti-Course-Evenement: course.livree
Ti-Course-Signature: t=1763371200,v1=5f2b…
Content-Type: application/json
{"id": "evt_9fK2mQ7xLpA4sT1vB8nC3dE0", "type": "course.livree", "cree_le": "2026-11-17T14:00:00+04:00",
"donnees": {"course": { … la course, comme GET /courses/{id} … }}}
Vérifier la signature
signature = HMAC-SHA256, avec votre secret, de <horodatage>.<corps brut>. Calculez-la sur le corps brut (avant tout décodage JSON), comparez en temps constant et refusez un horodatage de plus de 5 minutes. Ces trois exemples ont été éprouvés contre la signature réelle de Ti Course.
PHP
function signatureValide(string $corps, string $entete, string $secret, int $tolerance = 300): bool
{
if (! preg_match('/^t=(\d+),v1=([a-f0-9]{64})$/', $entete, $m)) {
return false;
}
if (abs(time() - (int) $m[1]) > $tolerance) {
return false; // trop ancien : rejeu possible
}
$attendue = hash_hmac('sha256', $m[1] . '.' . $corps, $secret);
return hash_equals($attendue, $m[2]);
}
$corps = file_get_contents('php://input');
if (! signatureValide($corps, $_SERVER['HTTP_TI_COURSE_SIGNATURE'] ?? '', getenv('TI_COURSE_WEBHOOK_SECRET'))) {
http_response_code(400);
exit;
}
$evenement = json_decode($corps, true);
Node.js
const crypto = require('crypto');
function signatureValide(corps, entete, secret, tolerance = 300) {
const m = /^t=(\d+),v1=([a-f0-9]{64})$/.exec(entete || '');
if (!m) return false;
if (Math.abs(Date.now() / 1000 - Number(m[1])) > tolerance) return false; // trop ancien
const attendue = crypto.createHmac('sha256', secret).update(`${m[1]}.${corps}`).digest('hex');
return crypto.timingSafeEqual(Buffer.from(attendue), Buffer.from(m[2]));
}
// Express : le corps brut, pas le JSON décodé.
app.post('/ti-course', express.raw({ type: 'application/json' }), (req, res) => {
const corps = req.body.toString('utf8');
if (!signatureValide(corps, req.get('Ti-Course-Signature'), process.env.TI_COURSE_WEBHOOK_SECRET)) {
return res.sendStatus(400);
}
const evenement = JSON.parse(corps);
res.sendStatus(200);
});
Python
import hashlib
import hmac
import re
import time
def signature_valide(corps: bytes, entete: str, secret: str, tolerance: int = 300) -> bool:
m = re.fullmatch(r"t=(\d+),v1=([a-f0-9]{64})", entete or "")
if not m:
return False
if abs(time.time() - int(m.group(1))) > tolerance:
return False # trop ancien : rejeu possible
attendue = hmac.new(secret.encode(), m.group(1).encode() + b"." + corps, hashlib.sha256).hexdigest()
return hmac.compare_digest(attendue, m.group(2))
Répondre, et les nouvelles tentatives
Répondez par un code 2xx en moins de 10 secondes, puis traitez l'événement. Sinon, Ti Course recommence après 1 min, 5 min, 30 min, 2 h et 6 h (6 tentatives en tout), et le journal de votre espace partenaire montre chaque essai. Un même événement peut arriver deux fois : ignorez un id déjà traité. Les redirections ne sont pas suivies.
7. Paiement et solde
- Chaque course est payée sur votre solde prépayé : son prix est réservé à la création (
GET /soldemontre le disponible et le réservé). - Annulée, le prix réservé revient à votre solde ; terminée, il paie le coursier.
- Solde insuffisant : la course n'est pas créée (
402, codesolde_insuffisant, avec le prix et le solde). - Recharge par carte depuis votre espace partenaire (paiement par Stripe), ou par virement : contactez Ti Course.
- Le prix suit la grille de Ti Course (taille et distance) ; une course ne dépasse pas 200 €.
8. Erreurs
Toujours la même forme, à lire par son code :
{"erreur": {"code": "donnees_invalides", "message": "…",
"champs": {"destinataire.telephone": ["Numéro de téléphone invalide …"]}}}
| HTTP | Code | Que faire |
|---|---|---|
| 401 | cle_invalide, cle_revoquee | Vérifiez l'en-tête et la clé ; créez-en une nouvelle si elle a été révoquée. |
| 403 | acces_api_ferme, compte_inactif | Contactez Ti Course. |
| 402 | solde_insuffisant | Rechargez votre solde. |
| 404 | introuvable | La course n'existe pas, ou n'est pas à vous. |
| 409 | reference_deja_utilisee | Une course existe déjà pour cette commande (course_id donné). |
| 409 | adresse_commerce_manquante | Complétez l'adresse de votre commerce dans l'espace partenaire. |
| 409 | deja_prete, non_annulable, transition_refusee | La course n'est plus dans un statut qui le permet (statut donné). |
| 422 | donnees_invalides | Corrigez les champs listés dans champs. |
| 422 | adresse_introuvable | Précisez l'adresse ou envoyez livraison.latitude et livraison.longitude. |
| 422 | creneau_passe, montant_trop_eleve, idempotency_key_invalide | Corrigez la demande. |
| 429 | trop_de_requetes | Patientez (en-tête Retry-After). |
9. Référence des appels
| Appel | Rôle |
|---|---|
GET /ping | Vérifier la clé (compte, clé, environnement). |
GET /solde | Solde disponible et réservé. |
POST /devis | Prix et distance, sans rien créer. |
POST /courses | Créer une course. |
GET /courses | Lister ses courses. |
GET /courses/{id} | Une course. |
POST /courses/{id}/prete | La commande est prête. |
POST /courses/{id}/annuler | Annuler avant le retrait. |
Le détail de chaque appel, de chaque champ et de chaque réponse est dans la spécification OpenAPI 3.1, lisible par la plupart des outils (Postman, Insomnia, générateurs de clients).
Version 1 de l'API, 17 novembre 2026.