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 (250000 pour 2 500 CDF). PATCH /v1/products/{id}, POST /v1/payment-links et PATCH /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 : coverUrl n’existe plus dans les réponses de GET /v1/payment-links, GET /v1/payment-links/{id}, POST /v1/payment-links, PATCH /v1/payment-links/{id}, POST /v1/payment-links/{id}/disable et POST /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 coverUrl ne répondent plus.

2026-10 — sessions de paiement sans code promo

Un changement non rétrocompatible.

  • Sessions de paiement : POST /v1/checkouts n’accepte plus couponCode. Un code promo ne s’applique jamais à une licence. Une requête qui l’envoie encore reçoit 400 validation_failed. amount est 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/checkouts accepte country, 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 (null sans pays), dans POST /v1/checkouts, GET /v1/checkouts/{id} et GET /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} et GET /v1/checkouts, avec les portées checkouts:read et checkouts: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), null pour une commande passée dans la boutique, dans GET /v1/orders, GET /v1/orders/{id} et les événements order.paid, order.failed, order.refunded et payment_link.paid.
  • Clés de licence : checkout, jusqu’ici toujours null, dit la session qui a vendu la clé, dans GET /v1/license-keys et les événements license_key.*.
  • Produits : license.appOnly dit qu’une licence ne se vend que depuis ton application. Elle n’a alors pas de page dans la boutique : url vaut null.

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 dans GET /v1/products (filtre type=LICENSE), GET /v1/products/{id}, les lignes des commandes (items[].type) et les événements product.published et product.archived.
  • Une nouvelle ressource, les clés de licence, avec les portées license_keys:read et license_keys:write :
    • en lecture, POST /v1/license-keys/validate vérifie la clé que ton utilisateur a saisie, et GET /v1/license-keys, GET /v1/license-keys/{id} et GET /v1/license-keys/{id}/activations listent et lisent les clés de la boutique ;
    • en écriture, POST /v1/license-keys/activate et POST /v1/license-keys/deactivate gèrent les appareils d’une clé, et POST /v1/license-keys/{id}/revoke la révoque.
  • Webhooks : six nouveaux événements, license_key.issued, license_key.activated, license_key.deactivated, license_key.revoked, license_key.expiring et license_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 dans GET /v1/products (filtre type=COURSE), GET /v1/products/{id}, les lignes des commandes (items[].type) et les événements product.published et product.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épond 422 product_incomplete avec details.missing: ["lesson"], là où il répondait jusqu’ici product_type_unavailable. Les valeurs de details.missing sont 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 : amount est 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, 0 sans code promo) et couponCode (le code saisi, null sans code promo), dans GET /v1/orders, GET /v1/orders/{id} et les événements order.paid, order.failed, order.refunded et payment_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. data est la commande, comme GET /v1/orders/{id}, avec status: "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 reste PAID.

2026-10 — noms des images d’un produit

Un changement incompatible, sans changement de version.

  • Produits : coverUrl devient imageUrl (l’image des cartes de la boutique) et pageImageUrl devient coverImageUrl (l’image en 16:9 en haut de la page d’un produit à télécharger). Cela vaut pour GET /v1/products, GET /v1/products/{id}, PATCH /v1/products/{id} et les événements product.published et product.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 (FIXED ou OPEN) et maxPriceAmount dans GET /v1/products, GET /v1/products/{id} et les événements product.published et product.archived. Un produit à prix libre (OPEN, produits à télécharger uniquement) laisse l’acheteur choisir son prix, de priceAmount jusqu’à maxPriceAmount, ou dix fois priceAmount quand il est null.
  • 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 (GET et POST /v1/customers, GET et PATCH /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, plus ping pour 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.

Sur cette page