Référence des routes

La référence lisible par une machine est openapi.json, un document OpenAPI 3.1 des mêmes routes : chargez-le dans votre client d’API ou votre générateur de code.

Toutes les routes sont sous /api/platform/v1. Les chemins ci-dessous sont donnés sans ce préfixe.

Entreprises

`GET /businesses`

Vos entreprises, de la plus ancienne à la plus récente, 50 par page par défaut et 100 au plus. Passez le next_cursor d’une page en cursor de la suivante. Une entreprise dont la période de lecture de 90 jours après sa fin est close n’est plus listée.

`POST /businesses`

Enregistre un de vos clients sous votre compte. external_id est votre propre identifiant : il est unique parmi vos entreprises, et le renvoyer répond la même entreprise avec un 200 et Idempotent-Replayed: true au lieu d’en créer une autre. Un NIF déjà connu chez nous, pour quelque client que ce soit, est refusé par un 409 NIF_ALREADY_REGISTERED : contactez-nous.

`GET /businesses/{business}`

{business} est notre identifiant (biz_...) ou le vôtre, écrit ext:<external_id>. normalisation_ready dit si au moins un point de vente détient un jeton DGI capable de normaliser aujourd’hui.

`PATCH /businesses/{business}`

Seuls les champs envoyés changent ; une address remplace toute l’adresse. nif et rccm ne se remplissent qu’une fois : répéter la valeur actuelle est accepté, toute autre valeur répond 409 BUSINESS_IDENTIFIER_LOCKED. Fixer un rccm prend sur la même petite limite de débit que créer une entreprise. Refusé une fois l’entreprise terminée.

`POST /businesses/{business}/end`

L’entreprise quitte votre compte. Les nouvelles factures sont refusées par un 409 BUSINESS_ENDED, celles déjà acceptées sont toujours normalisées, un Z final clôt chaque point de vente qui a vendu depuis son dernier Z, et la lecture, les rapports et les exports restent ouverts 90 jours, après quoi l’entreprise répond 404. Le répéter répond la même chose et n’émet rien de plus. Émet business.ended.

`POST /businesses/{business}/resume`

Retour à active. Une entreprise que nous avons nous-mêmes suspendue répond 409 BUSINESS_SUSPENDED et reste retenue jusqu’à ce que nous la levions ; une entreprise terminée répond 409 BUSINESS_ENDED. Émet business.resumed.

`POST /businesses/{business}/suspend`

Votre propre arrêt : l’entreprise passe à paused, les nouvelles factures sont refusées par un 409 BUSINESS_PAUSED, et celles déjà acceptées attendent dans la file sans échouer. Émet business.suspended. Le répéter ne change rien et n’émet rien de plus.

Factures et avoirs

`POST /businesses/{business}/credit-notes`

Un avoir (FA, ou EA pour une exportation) sur une facture que nous détenons, désignée par original_invoice_id, original_code_def ou original_external_reference. Lignes par original_item_id ou position ; omises, toutes les lignes encore créditables, à ce qui reste. reference_type (COR, RAN, RAM ou RRR) et reference_desc sont obligatoires. Si la facture d’origine est encore en file, l’avoir attend derrière elle ; si elle échoue définitivement, l’avoir échoue aussi. Mêmes réponses et même règle d’idempotence qu’une facture.

`GET /businesses/{business}/invoices`

Du plus récent au plus ancien, 50 par page par défaut et 100 au plus. Filtres : status (pending, normalised ou failed), from (inclus) et to (exclu) en instants ISO-8601 sur l’heure de création, et external_reference (exact, zéro ou une ligne). Une page contient au plus 100 lignes par facture : au-delà, la facture porte lines_omitted: true et sa propre lecture les contient toutes. Une liste est une vue ; c’est le flux d’événements qui sert à réconcilier.

`POST /businesses/{business}/invoices`

Accepte la vente et répond aussitôt 202 avec la facture pending : la DGI la normalise ensuite, et vous en apprenez le résultat par webhook, par le flux d’événements ou en lisant la facture. Rien n’attend la DGI. L’un de l’en-tête Idempotency-Key (64 caractères au plus) et du champ external_reference est obligatoire ; renvoyer le même répond 200 avec Idempotent-Replayed: true et ne crée jamais une seconde facture. delivery est refusé par un 400 DELIVERY_NOT_AVAILABLE : vous remettez vous-même la facture à votre client. format est accepté et ignoré. Tout champ omis prend le défaut que sa description indique, et defaults_applied nomme les défauts appliqués.

`GET /businesses/{business}/invoices/{invoice}`

{invoice} est notre identifiant, ou ext:<external_reference> pour une référence qu’un chemin peut contenir. Une référence avec une barre oblique ou un pour cent, comme INV/2026/0001, se lit avec ?external_reference= sur la liste ; le read_by_reference de la réponse donne cette adresse. Une fois normalisée, la réponse contient tout ce qu’il faut pour imprimer le document, avec toutes ses lignes (jusqu’à 1 000).

`POST /invoices/batch`

Corps { items: [ { business, kind, idempotency_key, invoice } ] } avec kind = invoice ou credit_note ; business vaut biz_... ou ext:... ; invoice est le corps de la route unitaire. Les éléments peuvent relever d’entreprises différentes. La réponse est toujours un 200 dès que le corps est lisible, avec un résultat par élément dans l’ordre d’envoi : accepted, replayed ou rejected. Ne renvoyez que les éléments marqués retryable: true, chacun avec sa propre clé. Au plus 100 éléments, 5 Mio et 5 000 lignes de facture par appel.

Exports

`POST /businesses/{business}/exports`

Construit en arrière-plan un zip contenant les factures et avoirs de l’entreprise (tout ce qu’il faut pour les réimprimer), leurs lignes, ses points de vente et ses rapports X, Z et A, en CSV, avec un fichier LISEZ-MOI. Répond 202. Une demande faite peu d’heures après un export terminé reçoit celui-là, de même qu’un export en cours, y compris un export que votre équipe a demandé dans la console Ripa (son id commence par pcxp_ au lieu de prxp_). Une Idempotency-Key est obligatoire. Ouvert pendant 90 jours après la fin de l’entreprise.

`GET /businesses/{business}/exports/{export}`

state vaut queued, running, ready ou failed. Un export prêt se télécharge jusqu’à available_until, 7 jours après sa construction.

`GET /businesses/{business}/exports/{export}/file`

Le zip, diffusé par cette API. 409 EXPORT_NOT_READY avant ready, 410 EXPORT_EXPIRED après available_until (demandez-en un nouveau), 429 EXPORT_DOWNLOADS_BUSY avec Retry-After au-delà de deux téléchargements à la fois par partenaire.

Points de vente

`GET /businesses/{business}/points-of-sale`

Tous les points de vente de l’entreprise, du plus ancien au plus récent. token_status vaut not_configured, active, expiring_soon ou expired.

`POST /businesses/{business}/points-of-sale`

Enregistre un e-MCF (son NID) avec le jeton DGI qui lui a été délivré. Le jeton est vérifié auprès de la DGI avant tout enregistrement, doit appartenir au NIF de l’entreprise et à ce NID, et n’est jamais renvoyé. time_zone est un identifiant de région tel que Africa/Lubumbashi ; absent, Africa/Kinshasa. Cette route appelle la DGI : sa limite de débit est plus petite que celle des autres.

`POST /businesses/{business}/points-of-sale/{pos}/deactivate`

Refusé par un 409 POS_HAS_QUEUED_INVOICES tant que des factures l’attendent (ou, pour le dernier point de vente actif, n’importe où dans l’entreprise). Le répéter sur un point de vente inactif le renvoie sans rien émettre de plus. Émet pos.deactivated.

`POST /businesses/{business}/points-of-sale/{pos}/reactivate`

L’opposé de deactivate : le point de vente reprend les factures, sa file repart et il retrouve son Z automatique. Son jeton est celui qu’il avait : s’il a expiré entre-temps, token_status le dit et sa file reste en pause jusqu’à ce que vous le remplaciez par PUT …/token. Le répéter sur un point de vente actif le renvoie sans rien émettre de plus. Émet pos.reactivated.

`PUT /businesses/{business}/points-of-sale/{pos}/token`

Le nouveau jeton est vérifié auprès de la DGI et son NIF et son NID doivent correspondre ; la file reprend ensuite d’elle-même. Permis tant que des factures attendent dans la file de l’entreprise, pour qu’elles puissent être normalisées : sur une entreprise terminée dans sa période de lecture, sur une entreprise que vous avez mise en pause, et pour un compte suspendu. Jamais sur une entreprise que nous avons suspendue. Appelle la DGI : limite de débit plus petite.

Rapports

`GET /businesses/{business}/reports`

Du plus récent au plus ancien, 50 par page par défaut et 100 au plus. Filtres : type, origin (API, AUTO, FINAL ou CONSOLE), state (queued, running, ready ou failed), point_of_sale, from et to (instants ISO-8601 sur l’heure de création). CONSOLE est un X ou un X périodique que votre équipe a demandé dans la console Ripa, jamais un Z ni un A ; ses report.ready et report.failed vous parviennent comme les autres. Acceptez les valeurs d’énumération que vous ne connaissez pas.

`POST /businesses/{business}/reports`

type vaut X, X_PERIODIC, Z ou A. Z et A désignent un point de vente dans point_of_sale (sinon 400 POINT_OF_SALE_REQUIRED) : un Z clôt la session de ce point de vente. X et X_PERIODIC peuvent en désigner un ou lire toute l’entreprise ; X_PERIODIC seul prend period_start et period_end. Répond 202 avec le rapport queued ; report.ready ou report.failed suit. Une Idempotency-Key est obligatoire. 1 000 X et X périodiques au plus attendent par partenaire, les X que votre équipe demande dans la console Ripa comptés avec les vôtres (429 REPORT_QUEUE_FULL). Reste ouvert à un partenaire suspendu et à une entreprise terminée dans ses 90 jours.

`GET /businesses/{business}/reports/{id}`

state vaut queued, running, ready ou failed. Un Z porte les chiffres de la session qu’il a close ; un A son nombre d’articles et son total TTC ; un X n’en a pas, ils sont dans son fichier. Un rapport en échec dit pourquoi dans error_code et error_message.

`GET /businesses/{business}/reports/{id}/file`

format=csv (par défaut) ou xlsx. Le CSV est exact ; les cellules numériques du classeur sont des doubles, qui perdent des centimes à partir d’environ 10^13 CDF : pour rapprocher au centime, partez du CSV. 409 REPORT_NOT_READY avant ready (un rapport en échec en dit la cause dans le message). Deux téléchargements à la fois par partenaire ; au-delà, 429 avec Retry-After.

`POST /businesses/{business}/reports/{id}/retry`

Remet en file un rapport failed ; tout autre état répond 409 REPORT_NOT_FAILED. Un Z qui avait déjà clos sa session la garde : la relance produit les mêmes chiffres et ne clôt rien de plus.

Flux d’événements

`GET /events`

Les événements dans l’ordre strict de position, sans trou, conservés 30 jours. Passez la dernière position que vous détenez en after (absent ou 0 : on part du plus ancien conservé) et gardez next_after pour l’appel suivant ; limit va de 1 à 1 000. Une position en avance sur le flux répond 400 ; une position plus ancienne que le flux répond 410 FEED_CURSOR_EXPIRED, dont le message donne la position de reprise. Un même id d’événement peut revenir à une position ultérieure : gardez le premier.

Consommation

`GET /usage`

Des nombres seulement, aucun prix : factures et avoirs normalisés par entreprise, point de vente et jour de Kinshasa, de from à to (aaaa-MM-jj, inclus ; par défaut le mois en cours). 92 jours au plus par appel. format=csv (UTF-8, séparateur ;) donne la même chose en tableur.

Webhook

`GET /webhook`

Son adresse, son statut (active ou disabled), depuis quand il échoue et sa dernière livraison réussie. Le secret n’est jamais renvoyé ; 404 tant qu’aucun n’est configuré.

`PUT /webhook`

Crée votre webhook (201, avec son secret, montré une seule fois) ou en change l’adresse (200, sans secret). Envoyé sur un webhook désactivé, il le réactive à partir de la position courante : le flux sert de rattrapage. L’adresse doit être publique, commencer par https:// et utiliser le port 443 ou 8443. Les lots sont des plages de positions : il n’y a pas de filtre par événement.

`POST /webhook/rotate-secret`

Renvoie un nouveau secret, montré dans cette réponse seulement ; le précédent continue de signer à côté pendant 24 heures. Une Idempotency-Key est obligatoire. Un rejeu de la même clé répond le même webhook sans secret : la première réponse s’est perdue, faites une nouvelle rotation avec une nouvelle clé. Une nouvelle rotation dans les 24 heures met fin aussitôt au secret reçu à la première rotation, et garde le plus ancien valable.