Changelog
Les évolutions de l’API publique et des webhooks de Kivoo.
2026-11 — montants en francs congolais
Un ajout rétrocompatible : aucune version ne change.
- Produits et liens de paiement : un montant en francs congolais (
CDF) est en francs entiers, soit un multiple de 100 en unités mineures (250000pour 2 500 CDF).PATCH /v1/products/{id},POST /v1/payment-linksetPATCH /v1/payment-links/{id}refusent un montant avec des centimes :400 amount_not_whole. Les autres devises ne changent pas.
2026-10 — liens de paiement sans image
Un changement incompatible, sans changement de version.
- Liens de paiement :
coverUrln’existe plus dans les réponses deGET /v1/payment-links,GET /v1/payment-links/{id},POST /v1/payment-links,PATCH /v1/payment-links/{id},POST /v1/payment-links/{id}/disableetPOST /v1/payment-links/{id}/enable. Un lien n’a plus d’image : sa page et son aperçu de partage montrent le logo de la boutique. - Les adresses d’image déjà renvoyées dans
coverUrlne répondent plus.
2026-10 — sessions de paiement sans code promo
Un changement non rétrocompatible.
- Sessions de paiement :
POST /v1/checkoutsn’accepte pluscouponCode. Un code promo ne s’applique jamais à une licence. Une requête qui l’envoie encore reçoit400 validation_failed.amountest le prix de la licence. - Commandes : une commande de licence passée avec un code promo est refusée (
400 coupon_not_applicable).
2026-10 — pays d’une session de paiement
Un ajout rétrocompatible : aucune version ne change.
- Sessions de paiement :
POST /v1/checkoutsacceptecountry, le pays de l’utilisateur en code ISO 3166-1 alpha-2 (GA). Tout pays connu de Kivoo est accepté, même sans moyen de paiement ouvert. - La session renvoie ce pays dans
country(nullsans pays), dansPOST /v1/checkouts,GET /v1/checkouts/{id}etGET /v1/checkouts. - La page de la session s’ouvre sur ce pays, et l’utilisateur peut en choisir un autre. Voir Encaisser depuis ton application.
2026-10 — sessions de paiement
Un ajout rétrocompatible : aucune version ne change.
- Une nouvelle ressource, les sessions de paiement :
POST /v1/checkouts,GET /v1/checkouts/{id}etGET /v1/checkouts, avec les portéescheckouts:readetcheckouts:write. Ton application crée une page de paiement pour une licence et un de ses utilisateurs, qui revient chez elle une fois le paiement reçu. Voir Encaisser depuis ton application. - Commandes : un nouveau champ
checkout(id,externalReference,metadata),nullpour une commande passée dans la boutique, dansGET /v1/orders,GET /v1/orders/{id}et les événementsorder.paid,order.failed,order.refundedetpayment_link.paid. - Clés de licence :
checkout, jusqu’ici toujoursnull, dit la session qui a vendu la clé, dansGET /v1/license-keyset les événementslicense_key.*. - Produits :
license.appOnlydit qu’une licence ne se vend que depuis ton application. Elle n’a alors pas de page dans la boutique :urlvautnull.
2026-10 — licences
Un ajout rétrocompatible : aucune version ne change.
- Produits : le type
LICENSE, une licence qui délivre une clé de licence par commande, apparaît dansGET /v1/products(filtretype=LICENSE),GET /v1/products/{id}, les lignes des commandes (items[].type) et les événementsproduct.publishedetproduct.archived. - Une nouvelle ressource, les clés de licence, avec les portées
license_keys:readetlicense_keys:write:- en lecture,
POST /v1/license-keys/validatevérifie la clé que ton utilisateur a saisie, etGET /v1/license-keys,GET /v1/license-keys/{id}etGET /v1/license-keys/{id}/activationslistent et lisent les clés de la boutique ; - en écriture,
POST /v1/license-keys/activateetPOST /v1/license-keys/deactivategèrent les appareils d’une clé, etPOST /v1/license-keys/{id}/revokela révoque.
- en lecture,
- Webhooks : six nouveaux événements,
license_key.issued,license_key.activated,license_key.deactivated,license_key.revoked,license_key.expiringetlicense_key.expired. Les webhooks créés avant n’y sont pas abonnés : coche-les dans leur fiche pour les recevoir.
Voir Vérifier une clé de licence.
2026-10 — formations
Un ajout rétrocompatible : aucune version ne change.
- Produits : le type
COURSE, une formation faite de leçons vidéo que l’acheteur suit sur Kivoo, apparaît dansGET /v1/products(filtretype=COURSE),GET /v1/products/{id}, les lignes des commandes (items[].type) et les événementsproduct.publishedetproduct.archived. - Publier une formation avec
PATCH /v1/products/{id}demande au moins une leçon affichée avec une vidéo prête. Sinon, Kivoo répond422 product_incompleteavecdetails.missing: ["lesson"], là où il répondait jusqu’iciproduct_type_unavailable. Les valeurs dedetails.missingsont listées dans Conventions. - Le prix libre (
pricing: "OPEN") et l’image de couverture (coverImageUrl), jusqu’ici réservés aux produits à télécharger, valent aussi pour les formations.
2026-10 — codes promo
Un ajout rétrocompatible dans sa forme, mais le sens d’un champ change : à relire si ton intégration rapproche le montant d’une commande de ses lignes.
- Commandes :
amountest désormais ce que l’acheteur a payé, net de la remise d’un code promo. Il peut donc être inférieur à la somme des lignes. Deux nouveaux champs :discountAmount(la remise,0sans code promo) etcouponCode(le code saisi,nullsans code promo), dansGET /v1/orders,GET /v1/orders/{id}et les événementsorder.paid,order.failed,order.refundedetpayment_link.paid. - La remise ne porte que sur les lignes à prix fixe :
amount= somme des lignes −discountAmount.
2026-10 — remboursements
Un ajout rétrocompatible : aucune version ne change.
- Webhooks : un nouvel événement,
order.refunded, envoyé quand une commande payée est remboursée à l’acheteur.dataest la commande, commeGET /v1/orders/{id}, avecstatus: "REFUNDED". Les webhooks créés avant n’y sont pas abonnés : coche-le dans leur fiche pour le recevoir. - Commandes : le statut
REFUNDED, déjà présent dans l’énumération, peut désormais être atteint. Une commande en attente de remboursement restePAID.
2026-10 — noms des images d’un produit
Un changement incompatible, sans changement de version.
- Produits :
coverUrldevientimageUrl(l’image des cartes de la boutique) etpageImageUrldevientcoverImageUrl(l’image en 16:9 en haut de la page d’un produit à télécharger). Cela vaut pourGET /v1/products,GET /v1/products/{id},PATCH /v1/products/{id}et les événementsproduct.publishedetproduct.archived. Les anciens champs n’existent plus. - Les adresses d’image déjà renvoyées restent valables : elles redirigent vers les nouvelles.
2026-09-29 — prix libre
Un ajout rétrocompatible : aucune version ne change.
- Produits :
pricing(FIXEDouOPEN) etmaxPriceAmountdansGET /v1/products,GET /v1/products/{id}et les événementsproduct.publishedetproduct.archived. Un produit à prix libre (OPEN, produits à télécharger uniquement) laisse l’acheteur choisir son prix, depriceAmountjusqu’àmaxPriceAmount, ou dix foispriceAmountquand il estnull. PATCH /v1/products/{id}écrit ces deux champs, avec les mêmes règles que le dashboard :open_pricing_unsupported,open_price_below_floor(details.floor),open_price_max_invalid,compare_at_not_allowed.
2026-09 — v1
La première version de l’API publique de Kivoo.
Clés API
- Des clés par boutique, préfixées
kv_live_, montrées une seule fois, avec une expiration facultative et dix clés actives au plus par boutique. - Des portées par ressource : Boutique et Commandes en lecture, Produits, Acheteurs et Liens de paiement en lecture et écriture.
- Une limite de débit de 120 requêtes par minute et par clé.
API publique (https://api.kivoo.africa/v1)
- Boutique :
GET /v1/store. - Produits : lister, lire, modifier et publier (
GET /v1/products,GET /v1/products/{id},PATCH /v1/products/{id}). - Commandes : lister et lire (
GET /v1/orders,GET /v1/orders/{id}). - Acheteurs : lister, lire, créer, modifier (
GETetPOST /v1/customers,GETetPATCH /v1/customers/{id}). - Liens de paiement : lister, lire, créer, modifier, suspendre et réactiver (
/v1/payment-links).
Webhooks
- Jusqu’à cinq webhooks HTTPS par boutique et six événements webhook :
order.paid,order.failed,customer.created,product.published,product.archived,payment_link.paid, pluspingpour les tests. - Une signature
Kivoo-Signature(HMAC-SHA256) et un identifiant d’événement stable pour l’idempotence. - Huit tentatives sur un peu plus de vingt-deux heures, un journal des livraisons de trente jours, le renvoi manuel et la désactivation automatique après trois jours d’échecs.