Conventions
Ce qui vaut pour toute l’API : format, identifiants, dates, montants, pagination, tri, recherche, erreurs et limite de débit.
Format
- Adresse de base :
https://api.kivoo.africa/v1. - Requêtes et réponses en JSON, encodé en UTF-8 : envoie
Content-Type: application/jsonavec un corps. - Les appels se font depuis un serveur : l’API ne renvoie aucun en-tête CORS, un navigateur ne peut pas l’appeler.
Identifiants
Chaque ressource a un id UUID, par exemple 3a6c2f1e-8b4d-4c1a-9e2f-5d7b8a9c0e1f. Conserve-le tel quel : c’est lui qu’on passe dans les adresses (/v1/products/{id}) et qu’on retrouve dans les événements webhook.
Dates
Toutes les dates sont au format ISO 8601, en UTC : 2026-09-12T10:05:00.000Z. Une date absente vaut null (une commande pas encore payée n’a pas de paidAt). Pour les filtres de période, from est inclus et to exclu.
Montants
Les montants sont des entiers, en unités mineures de la devise indiquée par le champ currency (code ISO 4217), qui est celle de la boutique. Le franc CFA (XAF) n’a pas de décimales : 5000 vaut 5 000 FCFA. Ne divise jamais un montant par 100 sans regarder la devise.
Pagination
Les listes sont paginées avec deux paramètres de requête :
| Paramètre | Valeurs | Par défaut |
|---|---|---|
page | 1 ou plus | 1 |
pageSize | de 1 à 100 | 25 |
La réponse donne la page (data) et de quoi parcourir les suivantes :
{
"page": 2,
"pageSize": 25,
"total": 42,
"data": [{ "id": "3a6c2f1e-8b4d-4c1a-9e2f-5d7b8a9c0e1f", "title": "Guide du freelance" }]
}Tant que page × pageSize < total, il reste des pages. Une page au-delà de la dernière renvoie data: [].
Tri et recherche
- Les listes sont triées de la plus récente à la plus ancienne (
createdAtdécroissant). - Le paramètre
qfait une recherche sans tenir compte de la casse : sur le titre des produits, sur le nom, l’e-mail et le téléphone des acheteurs. - Chaque liste a ses propres filtres (
status,type,from,to…), décrits dans la référence.
Une boutique, et elle seule
Une clé ne voit que sa boutique. Une ressource d’une autre boutique n’existe pas pour elle : Kivoo répond 404 (par exemple product_not_found), jamais 403.
Erreurs
Une requête refusée reçoit un statut HTTP 4xx ou 5xx et ce corps :
{
"statusCode": 404,
"code": "product_not_found",
"message": "Product not found",
"requestId": "5b0f6a2c-6a0e-4f65-9d2b-2f3d1c0b9a77",
"timestamp": "2026-09-26T10:00:00.000Z"
}| Champ | Contenu |
|---|---|
statusCode | Le statut HTTP, répété. |
code | Un code stable, lisible par une machine : c’est sur lui qu’il faut brancher ton code. |
message | Une explication en anglais, qui peut changer. |
details | Présent pour certaines erreurs seulement : la portée manquante (required), la liste des champs refusés pour validation_failed, ce qui manque pour publier (missing). |
requestId | L’identifiant de la requête : donne-le au support si tu écris à Kivoo. |
timestamp | L’heure de l’erreur. |
Les codes que l’API renvoie :
| Statut | code |
|---|---|
| 400 | validation_failed (paramètre ou corps invalide), et quelques codes précis : compare_at_invalid, phone_invalid, customer_identifier_required, payment_link_expiry_invalid |
| 401 | api_key_missing, api_key_invalid, api_key_revoked, api_key_expired (voir Authentification) |
| 403 | insufficient_scope, store_unavailable |
| 404 | product_not_found, order_not_found, customer_not_found, payment_link_not_found |
| 409 | customer_conflict : un autre acheteur de la boutique a déjà cet e-mail ou ce téléphone |
| 422 | product_incomplete (details.missing dit ce qui manque pour publier), product_type_unavailable, feature_disabled, payment_link_invalid_pricing, payment_link_expiry_past |
| 429 | rate_limited |
| 5xx | Une erreur de Kivoo : réessaie plus tard, avec un délai croissant. |
La page de chaque opération, dans la référence, liste les codes qu’elle peut renvoyer.
Limite de débit
Chaque clé a droit à 120 requêtes par minute, toutes routes confondues. Deux clés de la même boutique ont chacune leur compteur. Chaque réponse porte :
| En-tête | Contenu |
|---|---|
X-RateLimit-Limit | Le nombre de requêtes permises par minute (120). |
X-RateLimit-Remaining | Les requêtes qui restent dans la minute en cours. |
X-RateLimit-Reset | Les secondes avant que le compteur reparte à zéro. |
Au-delà, Kivoo répond 429 avec le code rate_limited et l’en-tête Retry-After, en secondes : attends ce délai avant de réessayer.
Une adresse IP qui présente plus de 20 clés inconnues par minute reçoit aussi 429 rate_limited, sans que ses clés soient vérifiées : vérifie la clé que ton programme envoie plutôt que de réessayer.