Entreprises

Une entreprise est un de vos clients, enregistré avec son NIF.

{business} dans un chemin

Toute route sous /businesses/{business} accepte, au choix :

• notre identifiant : biz_2xJ4kQ9nVbT7mLpR3sYz, ou
• le vôtre, écrit ext:<external_id> : ext:plateforme-cust-001842.

Une entreprise qui n’est pas la vôtre, qui n’existe pas, ou dont la fenêtre de 90 jours après sa fin est close, répond le même 404 BUSINESS_NOT_FOUND. Vous ne pouvez pas les distinguer, et personne d’autre non plus.

external_id

external_id est votre propre identifiant de l’entreprise. Il est obligatoire, unique parmi vos entreprises, de 128 caractères au plus, et ne peut contenir que des lettres, des chiffres et . _ : @ -. Ni espace ni barre oblique : il doit tenir dans un chemin sous la forme ext:<external_id>.

Créer 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" }
}

Obligatoires : external_id, legal_name, nif. Le NIF s’écrit une lettre, sept chiffres, une lettre. trade_name, rccm, email, phone et address sont facultatifs. Une entreprise n’a pas de groupe de taxation par défaut qui lui soit propre : une ligne sans tax_group prend le défaut donné à la page Factures.

Réponse : 201 avec l’entreprise. Renvoyer le même external_id répond 200 avec la même entreprise et Idempotent-Replayed: true ; rien n’est créé deux fois. Le même external_id avec un autre NIF répond 409 EXTERNAL_ID_OTHER_NIF (une faute de frappe d’un côté ou de l’autre). L’en-tête Idempotency-Key est facultatif sur cette route.

{
  "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" }
}

Référence complète des champs : Créer une entreprise.

status vaut active, paused (votre propre pause), suspended (suspendue par nous : ses factures acceptées attendent que nous la levions ; elle revient alors à active, ou à paused si vous l’aviez mise en pause), ended ou closed. normalisation_ready est vrai quand au moins un point de vente est actif et détient un jeton DGI capable de normaliser aujourd’hui.

Les autres routes

Les autres routes des entreprises :

Route	Effet
GET /businesses?cursor=&limit=	Vos entreprises, de la plus ancienne à la plus récente, 50 par page par défaut, 100 au plus.
GET /businesses/{business}	Une entreprise.
PATCH /businesses/{business}	Modifie ce que vous envoyez : trade_name, email, phone, address (remplace toute l’adresse), rccm, nif. 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.
POST /businesses/{business}/suspend	Votre propre pause. L’entreprise passe à paused, les nouvelles factures répondent 409 BUSINESS_PAUSED, celles déjà acceptées attendent sans échouer. Émet business.suspended.
POST /businesses/{business}/resume	Retour à active. Émet business.resumed. Une entreprise que nous avons suspendue répond 409 BUSINESS_SUSPENDED et reste retenue jusqu’à ce que nous la levions.
POST /businesses/{business}/end	L’entreprise vous quitte (Le départ).

Modifier une entreprise : Modifier une entreprise.

Mettre en pause et reprendre

• Pause. Votre propre pause. L’entreprise passe à paused, les nouvelles factures répondent 409 BUSINESS_PAUSED, celles déjà acceptées attendent sans échouer. Émet business.suspended.
• Reprise. Retour à active. Émet business.resumed. Une entreprise que nous avons suspendue répond 409 BUSINESS_SUSPENDED et reste retenue jusqu’à ce que nous la levions.

Les événements business.suspended et business.resumed le disent dans le flux : voir le catalogue des événements. Lisez status, pas le type de l’événement, pour connaître l’état.

Un seul NIF dans tout Ripa

Un NIF ne peut être enregistré qu’une fois dans l’ensemble des systèmes de Ripa : par un client direct, par vous, ou par une autre plateforme. Si vous enregistrez un NIF déjà connu, la réponse est :

{
  "object": "error",
  "error": {
    "code": "NIF_ALREADY_REGISTERED",
    "message": "Ce NIF est déjà enregistré chez Ripa. Contactez Ripa pour la suite à donner.",
    "type": "conflict_error",
    "conflicting_field": "nif"
  },
  "meta": { "request_id": "req_02" }
}

(409.) Nous ne disons jamais qui détient le NIF, et rien dans la réponse ne permet de le deviner. La même règle vaut pour le RCCM (409 RCCM_ALREADY_REGISTERED). Que faire : contactez votre interlocuteur chez Ripa avec le NIF de l’entreprise et l’identifiant de requête. Il n’existe pas de dérogation que vous puissiez actionner vous-mêmes, ni d’approbation automatique.

Deux conséquences à anticiper. Un NIF mal saisi qui se trouve être celui d’un vrai contribuable prend le NIF de ce contribuable : vérifiez le NIF avant de l’envoyer. Si cela arrive, contactez-nous : une entreprise qui n’a jamais eu de facture ni d’avoir normalisé peut être supprimée par nos soins, ce qui libère son NIF aussitôt ; vous recevez business.deleted (Flux d’événements) et l’entreprise répond 404 à partir de là. Une entreprise qui a normalisé quoi que ce soit ne peut pas être supprimée. Et une entreprise qui vous a quittés garde son NIF enregistré chez nous (nous conservons son archive pendant la durée légale), si bien que le même contribuable qui rejoindrait une autre plateforme, ou qui reviendrait chez vous, serait refusé de la même façon et renvoyé vers nous.

L’appel qui enregistre un NIF a sa propre limite de débit, volontairement petite (Limites de débit).

Le départ

Terminer une entreprise

POST …/end répond { id, external_id, status: "ended", ended_at, queue_held } et est idempotent (un nouvel appel ne change rien et n’émet rien de plus). À partir de là :

• Les nouvelles factures et les nouveaux avoirs sont refusés par un 409 BUSINESS_ENDED. Les écritures sur l’entreprise sont refusées.
• Les factures déjà acceptées sont quand même normalisées et publiées. Une entreprise qui était en pause est reprise pour que sa file se vide. Une entreprise que nous avons suspendue reste retenue jusqu’à ce que nous la levions (queue_held: true le dit) ; sa clôture attend cela.
• Quand la file est vide, chaque point de vente qui a vendu depuis son dernier Z reçoit un Z final, puis l’entreprise se ferme d’elle-même (ses jetons sont révoqués). Son archive reste chez nous pendant la durée légale de conservation.
• Pendant 90 jours après ended_at, vous pouvez encore lire l’entreprise et ses factures, demander des rapports et prendre un export complet. Après 90 jours, l’entreprise répond 404 comme toute entreprise qui n’est pas la vôtre, et elle n’apparaît plus dans votre liste ni dans votre consommation.
• Un jeton peut encore être remplacé sur une entreprise terminée dont la file contient encore des factures (un jeton expiré les bloquerait sinon pour toujours), dans les 90 jours : PUT …/points-of-sale/{pos}/token y fonctionne, même une fois votre partenariat terminé ou pendant la suspension de votre compte. Avec une file vide, il répond 409 BUSINESS_ENDED (ou 403 PARTNER_ENDED, 403 PARTNER_SUSPENDED). Il reste refusé si nous avons suspendu l’entreprise : nous levons d’abord la suspension.
• Si, passé le jour 90, des factures sont encore en file (par exemple parce que le jeton n’a jamais été remplacé), rien n’est mis en échec et rien n’est abandonné.

Quand votre partenariat prend fin

Quand votre partenariat prend fin, toutes les entreprises se terminent de la même façon et vous avez les mêmes 90 jours ; après quoi tout appel répond 403 PARTNER_ENDED, jusqu’à la révocation de vos clés peu après, puis un 401 vide.

Transférer une entreprise vers son propre compte

Si une entreprise veut continuer à utiliser le service en direct, Ripa peut la transférer vers un compte autonome. À partir du transfert, vous n’y avez plus accès (elle répond 404). Son historique et ses numéros de facture continuent. Un événement business.ended vous dit qu’elle est partie, sans dire où.