API LOKO pour les centrales de réservation

Démarrage rapide

1. Créez un compte LOKO, puis une clé depuis Mes clés API. La clé n'est affichée qu'une seule fois.

2. Envoyez-la dans l'en-tête Authorization :

curl https://loko-trip.com/api/v1/prestataires?categorie=hebergement&ville=Kribi \
  -H "Authorization: Bearer lk_live_votre_cle"

Clé limitée ou clé complète

Vous choisissez le niveau d'accès à la création de chaque clé. Dans les deux cas la clé est stockée hachée, révocable à tout moment et peut être restreinte à vos adresses IP.

Permissions

Endpoints

URL de base : https://loko-trip.com/api/v1

Créer une réservation

Le prestataire reçoit la demande et la confirme ou la refuse. Suivez le champ statut avec GET /reservations/{id} : en_attente, dispo_confirmee, confirme, refuse, termine, annule.

curl -X POST https://loko-trip.com/api/v1/reservations \
  -H "Authorization: Bearer lk_live_votre_cle" \
  -H "Content-Type: application/json" \
  -d '{
    "prestataire_id": "uuid-du-prestataire",
    "date_debut": "2026-12-20",
    "date_fin": "2026-12-23",
    "nb_personnes": 2,
    "montant": 150000,
    "external_ref": "VOTRE-REF-0001",
    "client": { "nom": "Awa Ndiaye", "email": "awa@exemple.com", "telephone": "+221770000000" },
    "message": "Arrivée tardive vers 22 h"
  }'

Montants en FCFA (XAF), entiers. Renvoyer la même external_ref ne crée jamais de doublon : la réservation existante est retournée avec l'en-tête Idempotent-Replayed: true.

Webhooks

Ajoutez une URL https dans Mes clés API. LOKO envoie un POST JSON à chaque changement de statut d'une réservation créée avec votre compte. Le secret de signature est affiché une seule fois.

POST https://votre-centrale.com/webhooks/loko
Content-Type: application/json
LOKO-Event: reservation.status_changed
LOKO-Delivery: 7d1f…            (identifiant unique de la livraison)
LOKO-Signature: t=1791138600,v1=3c9a…

{
  "id": "evt_9f2c…",
  "type": "reservation.status_changed",
  "created_at": "2026-12-01T10:15:00Z",
  "data": {
    "previous_status": "en_attente",
    "reservation": { "id": "…", "external_ref": "VOTRE-REF-0001", "statut": "dispo_confirmee", "…": "…" }
  }
}

Vérifier la signature

La signature est un HMAC-SHA256 de {timestamp}.{corps brut} avec votre secret. Calculez-la sur le corps reçu tel quel, comparez en temps constant et refusez les requêtes de plus de 5 minutes.

import { createHmac, timingSafeEqual } from 'node:crypto'

export function verifyLoko(rawBody, header, secret) {
  const parts = Object.fromEntries(header.split(',').map(p => p.split('=')))
  if (Math.abs(Date.now() / 1000 - Number(parts.t)) > 300) return false
  const expected = createHmac('sha256', secret).update(parts.t + '.' + rawBody).digest('hex')
  const a = Buffer.from(expected), b = Buffer.from(parts.v1 ?? '')
  return a.length === b.length && timingSafeEqual(a, b)
}

• Répondez avec un statut 2xx en moins de 8 secondes. Toute autre réponse est considérée comme un échec.
• En cas d'échec, LOKO réessaie après 1 min, 5 min, 30 min, 2 h puis 12 h (6 tentatives au total).
• Dédoublonnez avec id de l'événement : une même livraison peut arriver plus d'une fois.
• Les redirections ne sont pas suivies et les adresses internes sont refusées.
• Après 20 échecs consécutifs, le webhook est désactivé. Vous pouvez le réactiver depuis votre espace.
• Le bouton « Envoyer un test » déclenche un événement webhook.test.

Quotas et erreurs

Les clés limitées renvoient X-RateLimit-Limit, X-RateLimit-Remaining et X-RateLimit-Reset. Au-delà du quota : statut 429 et en-tête Retry-After.

{ "error": { "code": "rate_limited", "message": "Quota dépassé (60 requêtes/minute).", "request_id": "req_…" } }

Sécurité

• Appelez l'API depuis votre serveur, jamais depuis un navigateur ou une application mobile.
• Stockez la clé dans une variable d'environnement, jamais dans un dépôt de code.
• Restreignez la clé à vos adresses IP et donnez-lui une date d'expiration.
• Une clé perdue ne peut pas être récupérée : révoquez-la et créez-en une nouvelle.