TopDepart · API publique v1

Documentation développeurs

Surface additive sous /api/v1. Les routes internes /api/* restent inchangées.

Authentification

Authorization: Bearer td_live_…

Clé créée depuis le dashboard admin / compagnie (affichée une seule fois).
Seule le hash SHA-256 est stocké — jamais la clé brute.
Session cookie acceptée avec les mêmes scopes (rôles plateforme / compagnie).
Lecture catalogue : anonyme autorisée, rate limit par IP.

Scopes

companies:read, stations:read, trips:read, routes:read, bookings:read, bookings:write, tickets:verify, webhooks:manage

Endpoints

Méthode	Chemin	Auth	Description
GET	/api/v1/companies	Optionnel companies:read (si clé)	Catalogue compagnies actives
GET	/api/v1/stations	Optionnel stations:read	Catalogue gares (filtres country, city, company)
GET	/api/v1/trips/search?from=&to=&date=	Optionnel trips:read	Recherche trajets (from/to requis)
GET	/api/v1/routes/:id	Optionnel routes:read	Détail ligne + arrêts
POST	/api/v1/bookings	Requis bookings:write	Créer un hold (BookingGroup PENDING)
GET	/api/v1/bookings/:id	Requis bookings:read	Détail groupe ou billet
GET	/api/v1/tickets/:id/verify	Requis tickets:verify	Statut billet (lecture seule)

Exemple — recherche trajets

curl -s "https://VOTRE_HOST/api/v1/trips/search?from=Abidjan&to=Bouaké&date=2026-07-20" \
  -H "Authorization: Bearer td_live_…"

Exemple — hold réservation

curl -s -X POST "https://VOTRE_HOST/api/v1/bookings" \
  -H "Authorization: Bearer td_live_…" \
  -H "Content-Type: application/json" \
  -d '{
    "tripId": "…",
    "passengers": [{ "name": "Awa Kouassi", "phone": "+2250700000000" }]
  }'

Réponse : groupe PENDING + places verrouillées. Paiement via le flux existant /api/payments/initiate. Correspondances multi-legs : /api/booking-groups.

Webhooks sortants

Événements : payment.confirmed, booking.confirmed, ticket.scanned, incident.created.

X-TopDepart-Event: payment.confirmed
X-TopDepart-Timestamp: 1710000000
X-TopDepart-Signature: sha256=<hmac_hex>
X-TopDepart-Delivery: <deliveryId>

# Vérification : HMAC-SHA256(secret, timestamp + "." + rawBody)

Enregistrement UI dashboard · retry automatique via POST /api/cron/process-webhooks (CRON_SECRET).

ChatBot WhatsApp

Assistant TopDépart (réservation, tarifs, suivi, QR, colis, CEDEAO) branché sur la base réelle. Doc détaillée : apps/web/docs/whatsapp-bot.md.

# Simulation locale (sans Meta)
curl -s -X POST "http://localhost:3000/api/whatsapp/demo" \
  -H "Content-Type: application/json" \
  -d '{"from":"2250700000000","text":"menu"}'

# Webhook Meta
GET  /api/whatsapp/webhook?hub.mode=subscribe&hub.verify_token=…&hub.challenge=…
POST /api/whatsapp/webhook   # Meta Cloud ou Twilio form

WHATSAPP_PROVIDER=demo (défaut) : réponses dans le JSON + logs, aucune API Meta.
Live : whatsapp_cloud + WHATSAPP_TOKEN / WHATSAPP_PHONE_NUMBER_ID / WHATSAPP_VERIFY_TOKEN.

Rate limiting

Par clé API (rateLimit req/min) ou par IP (anonyme ~30/min). Réponse 429 + Retry-After.