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

  1. 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.
  2. Vérifiez l'adresse de votre commerce dans votre espace partenaire : c'est le point de retrait des courses.
  3. 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.
  4. Rechargez votre solde (par carte depuis la même rubrique, ou par virement) : chaque course est payée sur ce solde.
  5. 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."
  }'
Champs de la demande
ChampObligatoireRôle
reference_commandeouiVotre numéro de commande : le coursier le présente au retrait. Une seule course en cours par commande.
tailleouiS sac à dos, M cabas, L coffre, XL gros volume.
destinataire.nom, destinataire.telephoneouiVotre client, que le coursier peut appeler.
livraison.adresseouiÀ 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.longitudenonRecommandées si vous les avez (ensemble).
livraison.precisionsnonBâtiment, digicode, repère.
retrait.nom_sur_commande, retrait.plagenonLe nom sur la commande, quand elle peut être retirée.
instructionsnonConsignes pour le coursier.
pretenontrue par défaut : la course est proposée aux coursiers tout de suite. false : elle attend POST /courses/{id}/prete.
creneau.date, creneau.heurenonLivraison 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.

Statuts d'une course
StatutSignification
en_preparationCommande pas encore prête (créée avec prete: false).
recherche_coursierProposée aux coursiers.
coursier_assigneUn coursier a accepté ; son nom et son téléphone sont dans la course.
coursier_en_routeEn route vers votre commerce.
coursier_au_commerceAu commerce, pour le retrait.
en_livraisonCommande retirée, en route vers votre client.
coursier_a_destinationArrivé chez votre client.
livreeRemise contre le code de livraison.
termineeClose 24 h après la livraison ; le coursier est payé.
annuleeAnnulée ; le prix réservé est rendu à votre solde.
litigeTraité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 /solde montre 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, code solde_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 …"]}}}
Codes d'erreur
HTTPCodeQue faire
401cle_invalide, cle_revoqueeVérifiez l'en-tête et la clé ; créez-en une nouvelle si elle a été révoquée.
403acces_api_ferme, compte_inactifContactez Ti Course.
402solde_insuffisantRechargez votre solde.
404introuvableLa course n'existe pas, ou n'est pas à vous.
409reference_deja_utiliseeUne course existe déjà pour cette commande (course_id donné).
409adresse_commerce_manquanteComplétez l'adresse de votre commerce dans l'espace partenaire.
409deja_prete, non_annulable, transition_refuseeLa course n'est plus dans un statut qui le permet (statut donné).
422donnees_invalidesCorrigez les champs listés dans champs.
422adresse_introuvablePrécisez l'adresse ou envoyez livraison.latitude et livraison.longitude.
422creneau_passe, montant_trop_eleve, idempotency_key_invalideCorrigez la demande.
429trop_de_requetesPatientez (en-tête Retry-After).

9. Référence des appels

Appels de l'API, version 1
AppelRôle
GET /pingVérifier la clé (compte, clé, environnement).
GET /soldeSolde disponible et réservé.
POST /devisPrix et distance, sans rien créer.
POST /coursesCréer une course.
GET /coursesLister ses courses.
GET /courses/{id}Une course.
POST /courses/{id}/preteLa commande est prête.
POST /courses/{id}/annulerAnnuler 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.