Démarrage rapide

Ce guide suit le chemin d’une première facture. Chaque étape renvoie à la page qui la détaille.

Vous enregistrez une entreprise (un de vos clients) avec son NIF. Vous enregistrez ses points de vente : chacun est un e-MCF, identifié par son NID, avec le jeton que la DGI lui a délivré.
Vous envoyez une facture ou un avoir pour cette entreprise. Nous répondons 202 tout de suite, avec la facture pending. Nous ne vous faisons jamais attendre la DGI.
La DGI normalise la facture en arrière-plan. Vous en apprenez le résultat par webhook, en lisant le flux d’événements, ou en lisant la facture.
Une facture normalisée porte tout ce qu’il faut pour que vous l’imprimiez vous-même : le code de la DGI, les données du QR code, les compteurs, les totaux, les lignes. Nous ne produisons aucun PDF pour vous.
Vous pouvez demander les rapports de la DGI (X, Z, A) en CSV ou en Excel, lire votre consommation, et récupérer un export complet d’une entreprise.

1. Votre clé et l’URL de base

URL de base : https://api.getripa.com/api/platform/v1 (production) et https://api-dev.getripa.com/api/platform/v1 (test).

Chaque appel porte votre clé :

Authorization: Bearer rpa_pk_live_xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx

Développez sur l’environnement de test. Voir Clés API et droits et Données de test.

2. Enregistrer une entreprise

POST /businesses

{
  "external_id": "plateforme-cust-001842",
  "legal_name": "Kasongo Distribution SARL",
  "nif": "A1234567B",
  "trade_name": "Kasongo Distribution",
  "rccm": "CD/KIN/RCCM/24-A-12345",
  "email": "compta@kasongo.example",
  "phone": "+243991234567",
  "address": { "street": "12 avenue du Commerce", "city": "Kinshasa", "province": "Kinshasa" }
}

La réponse est 201 avec l’entreprise :

{
  "object": "business",
  "data": {
    "id": "biz_2xJ4kQ9nVbT7mLpR3sYz",
    "external_id": "plateforme-cust-001842",
    "legal_name": "Kasongo Distribution SARL",
    "trade_name": "Kasongo Distribution",
    "nif": "A1234567B",
    "status": "active",
    "created_at": "2026-11-05T08:00:00Z",
    "points_of_sale_count": 0,
    "normalisation_ready": false
  },
  "meta": { "request_id": "req_01" }
}

Détail des champs : Créer une entreprise. Un même external_id renvoyé ne crée rien de plus : voir Entreprises.

3. Enregistrer un point de vente

Un point de vente est un e-MCF. Une entreprise doit en avoir au moins un, avec un jeton valide, avant qu’une facture puisse être normalisée.

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

{
  "nid": "CD01004159-1",
  "dgi_token": "eyJhbGciOi...",
  "name": "Caisse principale",
  "time_zone": "Africa/Lubumbashi",
  "address": { "street": "12 avenue du Commerce", "city": "Lubumbashi", "province": "Haut-Katanga" },
  "phone": "+243991234567"
}

Obligatoires : nid, dgi_token, name. time_zone est un identifiant de région ; absent, Africa/Kinshasa. Le jeton est vérifié auprès de la DGI avant tout enregistrement ; il doit appartenir au NIF de l’entreprise et à ce NID, et aucune route ne le renvoie jamais. La réponse est 201 :

{
  "object": "point_of_sale",
  "data": {
    "id": "ent_2xJ4kQ9nVbT7mLpR3sYz",
    "business_id": "biz_2xJ4kQ9nVbT7mLpR3sYz",
    "nid": "CD01004159-1",
    "nim": "CD01004159-1",
    "name": "Caisse principale",
    "pos_code": "01",
    "time_zone": "Africa/Lubumbashi",
    "status": "active",
    "token_status": "active",
    "token_expires_at": "2027-05-01T00:00:00Z",
    "created_at": "2026-11-05T08:05:00Z"
  },
  "meta": { "request_id": "req_03" }
}

Voir Points de vente.

4. Envoyer une facture

POST /api/platform/v1/businesses/ext:plateforme-cust-001842/invoices
Authorization: Bearer rpa_pk_live_...
Content-Type: application/json

{
  "external_reference": "VENTE-2026-000123",
  "sale_time": "2026-11-05T08:12:00Z",
  "currency": "CDF",
  "client": { "type": "PM", "name": "Mbuyi Services SARL", "nif": "A7654321C", "address": "5 rue de la Paix, Gombe" },
  "items": [
    { "description": "Ramette papier A4", "code": "PAP-A4", "unit": "pce", "quantity": 2, "unit_price": 11600, "tax_group": "B" }
  ],
  "payments": [ { "method": "ESPECES", "amount": 23200 } ],
  "operator_name": "Sarah Kabeya",
  "notes": "Merci de votre confiance."
}

Réponse 202 :

{
  "object": "invoice",
  "data": {
    "id": "inv_2xJ4kQ9nVbT7mLpR3sYz",
    "normalisation_status": "pending",
    "created_at": "2026-11-05T08:12:41Z",
    "external_reference": "VENTE-2026-000123",
    "nid": "CD01004159-1",
    "sale_time": "2026-11-05T08:12:00Z",
    "defaults_applied": ["target", "items[].item_type"],
    "type": "FV",
    "business": { "id": "biz_2xJ4kQ9nVbT7mLpR3sYz", "external_id": "plateforme-cust-001842" }
  },
  "meta": { "request_id": "req_04" }
}

Voir Factures et Idempotence.

5. Apprendre le résultat

La DGI normalise la facture en arrière-plan. Vous en apprenez le résultat par webhook, en lisant le flux d’événements, ou en lisant la facture.

Le webhook vous signale que le flux a du nouveau.
Le flux d’événements est la référence de tout ce qui s’est passé.
Une facture normalisée porte tout ce qu’il faut pour que vous l’imprimiez vous-même.