Hela

L'API en un coup d'œil

L'API Hela est une API REST en JSON, la même que celle qu'utilise l'application. Tout ce que l'écran fait, l'API le fait.

Adresse de base

https://<votre-serveur>/v1

Le serveur publie son schéma OpenAPI 3.1 sur GET /openapi.json et une interface de consultation sur /docs. Le schéma est généré depuis le code à chaque déploiement : il ne peut pas décrire une route qui n'existe pas.

Authentification

Une clé d'API dans l'en-tête Authorization :

Authorization: Bearer hela_live_3f9c…

Les clés se créent dans Administration → Développeurs. Chaque clé porte des portées qui limitent ce qu'elle peut faire. Détails : Authentification et portées.

Forme des réponses

  • Un objet pour une ressource, un tableau ou une page { data, nextCursor, hasMore } pour une collection.
  • Les montants sont des entiers en unité mineure, avec leur devise. Voir Entreprises, documents, argent.
  • Les erreurs portent un code stable (field-required:walletId) plutôt qu'une phrase. Voir Pagination, erreurs, idempotence.

Les familles de routes

Préfixe Ce qu'on y trouve
/companies/{id}/sales, /purchases, /deliveries Les documents de vente et d'achat, leurs paiements, livraisons, remboursements, annulations
/companies/{id}/quotes Les devis et leur conversion
/companies/{id}/items, /categories, /stock… Le catalogue et le stock
/companies/{id}/partners Clients et fournisseurs
/companies/{id}/wallets, /transactions, /budgets La trésorerie
/companies/{id}/time-entries Les heures et leur facturation
/companies/{id}/reports/… Rapports, grand livre, exports comptables
/companies/{id}/fiscal/… Régimes de facturation électronique, journal scellé
/companies/{id}/integrations/… Connexions aux partenaires
/companies/{id}/api-keys, /webhooks, /events Le coin des développeurs

La liste exhaustive, avec chaque champ, est dans le schéma OpenAPI. La page Ressources en donne une lecture guidée.

Limites

Clé de production Clé de test
Requêtes par minute 600 (réglable par clé) 60
Écritures oui refusées (403 forbidden)
Taille d'une page 50 par défaut, 200 au plus idem

Au-delà de la limite, le serveur répond 429 Too Many Requests. Un Retry-After indique quand revenir.

Versions

La version est dans l'adresse (/v1). Dans une version, les changements sont additifs : un champ peut apparaître, jamais disparaître ni changer de sens. Les événements suivent la même règle. Une version 2 de l'API aurait son propre préfixe et vivrait à côté de la première pendant au moins douze mois.

Pour aller plus vite

Un passage est faux ou manquant ? Écrivez-nous.