Clients

Lister les clients

GET /v1/clients

Paramètre	Type	Description
`skip`	integer	Pagination offset
`take`	integer	Pagination limite
`search`	string	Recherche par nom, email ou IFU
`status`	string	`ACTIVE` ou `INACTIVE`
`categoryId`	string	Filtrer par catégorie

Obtenir un client

GET /v1/clients/{id}

Réponse :

{
  "id": "clx5678efgh",
  "name": "SARL MonClient",
  "email": "contact@monclient.com",
  "phone": "+226 70 00 00 00",
  "address": "Avenue Kwame Nkrumah, Ouagadougou",
  "ifu": "BF123456789",
  "status": "ACTIVE",
  "category": {
    "id": "clxcat001",
    "name": "PME"
  },
  "stats": {
    "totalInvoiced": 2950000,
    "totalPaid": 2360000,
    "outstanding": 590000,
    "invoiceCount": 8
  },
  "createdAt": "2026-01-15T10:30:00Z"
}

Créer un client

POST /v1/clients

{
  "name": "SARL MonClient",
  "email": "contact@monclient.com",
  "phone": "+226 70 00 00 00",
  "address": "Avenue Kwame Nkrumah, Ouagadougou",
  "ifu": "BF123456789",
  "categoryId": "clxcat001"
}

Contraintes métier

name est obligatoire.
L'email client doit être valide si vous utilisez l'envoi automatique des factures.
Un client archivé ne peut plus être utilisé pour de nouveaux documents.
L'archive conserve l'historique des pièces déjà émises.

Modifier un client

PATCH /v1/clients/{id}

Envoyez uniquement les champs à modifier.

Archiver un client

DELETE /v1/clients/{id}

L'archivage est doux (soft delete). Le client reste accessible dans l'historique des factures.

Factures d'un client

GET /v1/clients/{id}/invoices

Retourne toutes les factures liées à ce client, avec pagination.

Erreurs fréquentes

Code HTTP	`error.code`	Cas typique
`400`	`VALIDATION_ERROR`	Champ requis absent (`name`)
`404`	`NOT_FOUND`	Client introuvable
`409`	`CONFLICT`	Conflit métier (ex. état incompatible)

Exemple de réponse de validation :

{
  "error": {
    "code": "VALIDATION_ERROR",
    "message": "Le champ 'name' est obligatoire.",
    "details": {
      "field": "name",
      "rule": "required"
    }
  }
}

Bonnes pratiques d'intégration

Utilisez search + pagination (skip, take) au lieu de charger tout l'annuaire.
Mettez en cache localement les clients les plus utilisés et invalidez après mutation.
Avant création, vérifiez s'il existe déjà un client équivalent (email/IFU) pour limiter les doublons.

On this page