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

token_status vaut not_configured, active, expiring_soon ou expired. Un e-MCF ne peut être relié qu’à un seul compte : un NID déjà actif ailleurs répond 409 ENTITY_NID_CLAIMED, avec le NID dans conflicting_value ; faites-le détacher de l’autre compte ou utilisez un autre NID.

Les autres routes

Route	Effet
GET /businesses/{business}/points-of-sale	Tous les points de vente de l’entreprise.
PUT /businesses/{business}/points-of-sale/{pos}/token	Remplace le jeton, corps { "dgi_token": "..." }. Vérifié auprès de la DGI comme le premier ; la file du point de vente reprend d’elle-même.
POST /businesses/{business}/points-of-sale/{pos}/deactivate	Le désactive. Refusé par un 409 POS_HAS_QUEUED_INVOICES tant que des factures l’attendent. Émet pos.deactivated. Renvoyer son NID répond 409 ENTITY_NID_EXISTS : réactivez-le plutôt (ligne suivante). Si une facture acceptée à cet instant précis se retrouve sans point de vente actif dans son entreprise, vous recevez business.queue_blocked et un e-mail à votre contact technique. Réactivez le point de vente, ou ajoutez-en un avec un autre NID, et elle est normalisée.
POST /businesses/{business}/points-of-sale/{pos}/reactivate	Réactive un point de vente que vous avez désactivé : il reprend les factures, sa file repart et il retrouve son Z automatique. Il garde le jeton qu’il avait : si ce jeton a expiré entre-temps, token_status le dit et sa file reste en pause jusqu’à ce que vous le remplaciez par la route ci-dessus. Le répéter sur un point de vente actif répond 200 avec le point de vente, sans rien émettre de plus. Refusé comme toute écriture : 409 BUSINESS_ENDED, BUSINESS_PAUSED, BUSINESS_SUSPENDED, 403 PARTNER_SUSPENDED, PARTNER_ENDED. Émet pos.reactivated.

Un point de vente inconnu, ou celui d’une autre entreprise, répond 404 POINT_OF_SALE_NOT_FOUND.

Remplacer un jeton

Remplace le jeton, corps { "dgi_token": "..." }. Vérifié auprès de la DGI comme le premier ; la file du point de vente reprend d’elle-même.

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

{ "dgi_token": "eyJhbGciOi..." }

Quand un jeton expire. Les factures déjà acceptées n’échouent pas : elles attendent, et la file du point de vente est mise en pause. Vous en êtes prévenus par pos.token_expiring (à l’avance), pos.token_expired et pos.token_invalid. Remplacez le jeton avec la route ci-dessus et la file reprend.

• 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.

Les deux routes qui appellent la DGI ont une limite de débit plus petite que les autres (Limites de débit).