API Boardiwa Business

L'API permet à une caisse, une application de vente ou un logiciel métier d'enregistrer des ventes comptabilisées automatiquement, de lire les clients, factures et paiements d'un dossier, et d'être prévenu des événements par webhook.

Authentification

Créez une clé dans Paramètres de facturation, onglet API. Une clé donne accès à un seul dossier et porte des autorisations :ventes:ecrire et/ou lecture. Envoyez-la dans l'en-tête :

Authorization: Bearer bbk_...

La clé n'est affichée qu'une fois. Révoquez-la immédiatement en cas de fuite.

Environnement de test

Une clé créée en environnement « Test » (préfixe bbk_test_) valide chaque vente et renvoie une réponse simulée ("simulation": true) sans rien enregistrer. Les routes de lecture renvoient les données réelles du dossier. Utilisez-la pour développer votre intégration, puis passez à une clé de production.

Enregistrer une vente

POST https://business.boardiwa.com/api/v1/ventes
Content-Type: application/json

{
  "reference_externe": "TICKET-2026-000123",
  "journal_code": "CA",
  "moyen_paiement": "especes",
  "lignes": [
    { "produit_code": "PAIN-BAGUETTE", "quantite": 3 },
    { "designation": "Croissant", "prix_unitaire": 350, "quantite": 2, "taux_tva": 18, "groupe_taxation": "B" }
  ]
}

Réponse 201 : { "facture_id", "numero", "montant_ttc", "deja_enregistree": false }. La facture est confirmée, comptabilisée et encaissée dans le journal de trésorerie indiqué. Renvoyer la même reference_externe (coupure réseau, double envoi) renvoie la facture existante avec le code 200 et "deja_enregistree": true : une vente n'est jamais facturée deux fois.

Lire les données

• GET https://business.boardiwa.com/api/v1/clients?recherche=&page=1&par_page=50
• GET https://business.boardiwa.com/api/v1/factures?statut=confirmee&du=2026-01-01&au=2026-12-31&client_id= : montant TTC, déjà encaissé, reste dû
• GET https://business.boardiwa.com/api/v1/factures/{id} : lignes et règlements
• GET https://business.boardiwa.com/api/v1/paiements?du=&au=&facture_id=

Les listes renvoient { "donnees": [...], "page", "par_page", "total" } ; 200 éléments au plus par page.

Webhooks

Déclarez une adresse HTTPS dans l'onglet API et choisissez les événements : facture.confirmee, facture.annulee, paiement.recu. Boardiwa envoie un POST JSON :

{
  "id": "6c1f...",
  "evenement": "paiement.recu",
  "cree_le": "2026-09-17T10:15:02Z",
  "dossier_id": "...",
  "donnees": { "paiement_id": "...", "facture_id": "...", "montant": 25000, "date": "2026-09-17", "moyen": "MTN MoMo" }
}

Chaque envoi porte l'en-tête X-Boardiwa-Signature: t=<horodatage>,v1=<signature>, où la signature est le HMAC-SHA256 de <horodatage>.<corps brut> avec le secret affiché à la création du webhook. Vérifiez-la et refusez un horodatage de plus de 5 minutes :

// Node.js
const crypto = require("crypto");
function signatureValide(corpsBrut, entete, secret) {
  const { t, v1 } = Object.fromEntries(entete.split(",").map((p) => p.split("=")));
  if (Math.abs(Date.now() / 1000 - Number(t)) > 300) return false;
  const attendu = crypto.createHmac("sha256", secret).update(t + "." + corpsBrut).digest("hex");
  return crypto.timingSafeEqual(Buffer.from(attendu), Buffer.from(v1));
}

Répondez par un code 2xx en moins de 10 secondes. En cas d'échec, Boardiwa réessaie après 1 minute, 5 minutes, 30 minutes, 2 heures et 12 heures. Un même événement peut arriver deux fois : utilisez le champ id pour ignorer les doublons.

Codes de réponse et limites

• 400 : requête invalide (le message indique le champ en cause).
• 401 : clé absente, invalide, révoquée ou expirée.
• 403 : la clé n'a pas l'autorisation nécessaire.
• 422 : refus métier (exercice fermé, journal inconnu, abonnement expiré...).
• 429 : plus de 60 appels par minute pour une clé (en-tête Retry-After).
• 500 : erreur interne, sans détail technique ; réessayez plus tard.