Entreprises, documents, argent
Les quelques notions qui reviennent dans chaque appel.
L'entreprise
Tout est rangé par entreprise. Un compte Hela peut en gérer plusieurs ; chacune a ses propres ventes, son stock, ses portefeuilles, ses clés d'API et ses connexions aux partenaires. Dans l'API, l'identifiant de l'entreprise est dans le chemin : /companies/{companyId}/…. Une clé n'ouvre que l'entreprise qui l'a créée.
Les documents
| Document | Ce que c'est | Événements principaux |
|---|---|---|
Vente (sale) |
Un ticket de caisse ou une facture. Une vente a des lignes, un total, un statut de paiement et un statut de livraison. | sale.created, invoice.issued, invoice.paid, invoice.partially_paid, invoice.refunded, sale.cancelled |
Devis (quote) |
Une offre, qui peut être acceptée, signée, convertie en vente. | quote.created, quote.accepted, quote.signed, quote.converted |
Achat (purchase) |
Une commande ou une facture fournisseur. | purchase.created, purchase.received, purchase.paid |
Livraison (delivery) |
Un bon de livraison attaché à une vente. | delivery.created |
Mouvement (transaction) |
Une entrée ou une sortie d'argent dans un portefeuille. | transaction.created, payment.received |
Dépense (expense) |
Une sortie d'argent sans facture fournisseur. | expense.created |
Séjour (stay) |
Une réservation de chambre (module hôtel). | stay.checked_in, stay.checked_out |
Entrée de temps (time_entry) |
Des heures travaillées pour un client. | time_entry.created |
Une vente est une facture quand elle est adressée à un partenaire identifié ou qu'elle porte un reste à payer ; un ticket de comptoir payé sur-le-champ est une vente au comptant. Plusieurs connecteurs permettent de choisir d'ignorer les ventes au comptant (réglage « ventes de comptoir »).
Les partenaires
Un partenaire (partner) est un client, un fournisseur, ou les deux. Il porte un nom, des coordonnées, un numéro fiscal, et — pour la facturation électronique — un pays, un numéro de TVA et un identifiant Peppol.
L'argent
Chaque montant est un entier en unité mineure, accompagné de sa devise :
{ "amount": 12500, "currency": "USD" } // 125,00 USD
{ "amount": 20000, "currency": "CDF" } // 20 000 FC — le franc n'a pas de décimales
{ "amount": 1500, "currency": "KES" } // 15,00 KES
Le nombre de décimales dépend de la devise, pas d'un réglage. Pour convertir vers un nombre lisible, divisez par 10^décimales de la devise ; le SDK le fait (toMajor). Ne stockez jamais un montant en virgule flottante.
Une entreprise a une devise de base et peut vendre dans d'autres devises ; une vente en devise étrangère porte son taux (rateToBase) figé au moment de la vente.
Les dates
Toutes les dates sont en ISO 8601 UTC (2026-09-28T14:03:00.000Z). L'entreprise a un fuseau horaire (timezone), utilisé pour délimiter « la journée » dans les rapports et les clôtures de caisse.
Les identifiants
Les identifiants sont des UUID. Les documents portent aussi un numéro lisible (ERNS-SALE-260928-0012) dont le format se règle dans les paramètres ; c'est le numéro qu'il faut montrer, l'UUID qu'il faut stocker.
Les permissions
Chaque action de l'API correspond à une permission du produit (sales:view, sales:create, inventory:update, …). Une clé d'API porte un sous-ensemble de ces permissions appelé portées. Les permissions réservées aux humains (settings:members, developers:manage, billing:*) ne peuvent pas être données à une clé ; trois portées n'existent que pour les clés : events:read, webhooks:manage, exports:create.