Conventions

Adresse et format

Toutes les routes sont sous https://lekalao.example.com/api/v1.
Envoyez et recevez du JSON : Content-Type: application/json et Accept: application/json.
Une ressource seule est enveloppée dans data : {"data": {…}}.
Les dates sont en ISO 8601 avec fuseau : 2026-09-17T09:12:44+00:00. Sans fuseau, une date envoyée est lue dans le fuseau de l’installation (UTC par défaut).
Les montants sont des entiers dans la plus petite unité de la devise : 1250 = 12,50 €. Pour le franc CFA, qui n’a pas de subdivision, 15000 = 15 000 FCFA.

Identifiants

Chaque ressource est désignée par son id, qui est un uuid et jamais un numéro de ligne. Les adresses se construisent avec : /api/v1/lists/{id}/subscribers. Les tags peuvent aussi être désignés par leur nom là où c’est naturel : tags d’un abonné, règles de segment.

Pagination

Les listes sont paginées :

Paramètre	Défaut	Maximum
`page`	1
`per_page`	25 (50 pour les tags)	100

{
  "data": [ … ],
  "links": {
    "first": "https://lekalao.example.com/api/v1/lists/9d5c…/subscribers?page=1",
    "last": "https://lekalao.example.com/api/v1/lists/9d5c…/subscribers?page=52",
    "prev": null,
    "next": "https://lekalao.example.com/api/v1/lists/9d5c…/subscribers?page=2"
  },
  "meta": { "current_page": 1, "from": 1, "last_page": 52, "per_page": 25, "to": 25, "total": 1284 }
}

Suivez links.next jusqu’à ce qu’il vaille null.

Limite de débit

Chaque jeton peut faire 120 appels par minute (réglable par l’installation). Chaque réponse dit où vous en êtes :

X-RateLimit-Limit: 120
X-RateLimit-Remaining: 87
X-RateLimit-Reset: 1789637580

Au-delà, la réponse est 429 avec Retry-After en secondes :

{ "message": "Too many requests. Try again in 23 seconds." }

Attendez Retry-After secondes avant de reprendre. Pour inscrire beaucoup de monde, utilisez le lot : un appel pour 1 000 adresses.

Idempotence

Un appel qui expire vous laisse dans le doute : la commande est-elle passée ? Ajoutez un en-tête Idempotency-Key à vos POST et PUT et renvoyez le même appel sans risque :

curl -X POST https://lekalao.example.com/api/v1/transactional-mails/send \
  -H "Authorization: Bearer $LEKALAO_TOKEN" \
  -H "Content-Type: application/json" \
  -H "Idempotency-Key: commande-2026-00481-confirmation" \
  -d '{"template": "confirmation-commande", "to": ["ada@example.com"], "variables": {"order": "2026-00481"}}'

Situation	Réponse
Première fois	Traité normalement. La réponse porte `Idempotency-Key`.
Même clé, même route, même corps, dans les 24 h	La première réponse, rejouée à l’identique, avec `Idempotent-Replay: true`. Rien n’est refait.
Même clé pendant que le premier appel tourne encore	`409`. Réessayez un peu plus tard.
Même clé, autre route ou autre corps	`422` : une clé sert à une seule requête.
Même clé après 24 h	`422` : la clé a expiré, envoyez-en une nouvelle.
Premier appel en erreur `5xx`	Rien n’est retenu : le renvoi est traité comme neuf.

Choisissez une clé qui décrit l’opération (numéro de commande + action) ou un UUID généré avant le premier essai. 255 caractères au plus. Les clés sont propres à chaque équipe.

CORS

Les routes api/* et subscribe/* acceptent les appels venant de n’importe quelle origine, sans cookies. Les en-têtes de débit et d’idempotence sont lisibles par le navigateur.

CORS ouvert ne veut pas dire qu’il faut appeler l’API depuis un navigateur : le jeton y serait visible de tous. Seul le formulaire d’inscription est fait pour ça.

L'API

Recettes

Intégrations

Adresse et format

Identifiants

Limite de débit

Idempotence

CORS

​Adresse et format

​Identifiants

​Pagination

​Limite de débit

​Idempotence

​CORS

Adresse et format

Identifiants

Pagination

Limite de débit

Idempotence

CORS