Hela

Première clé, premier appel

Dix minutes, du compte Hela au premier GET qui renvoie vos ventes.

1. Ouvrir la page Développeurs

Dans l'application, choisissez l'entreprise, puis Administration → Développeurs. La page n'est visible qu'avec la permission developers:manage ; le propriétaire et les administrateurs l'ont.

Vous y trouvez trois choses : l'adresse de base de l'API de ce serveur, l'identifiant de l'entreprise, et les boutons pour créer des clés et des webhooks.

2. Créer une clé

Nouvelle clé, puis :

  • un nom qui dit à quoi elle sert (« Zapier », « Site vitrine », « Script compta ») ;
  • un mode : production ou test. Une clé de test lit les vraies données mais toute écriture est refusée, ce qui en fait l'outil idéal pour développer ;
  • des portées : cochez le strict nécessaire. Une clé qui lit les ventes n'a pas besoin de inventory:update.

La clé n'est affichée qu'une seule fois. Copiez-la dans votre gestionnaire de secrets. Elle commence par hela_live_ ou hela_test_.

3. Premier appel

export HELA_KEY="hela_test_…"
export HELA_API="https://api.example.com/v1"
export COMPANY="4c1d…"   # l'identifiant affiché sur la page Développeurs

curl -s "$HELA_API/companies/$COMPANY/sales?limit=5" \
  -H "Authorization: Bearer $HELA_KEY" | jq .

La réponse est une liste de ventes. Chaque montant est un entier en unité mineure, accompagné de la devise : voir Entreprises, documents, argent.

4. Une écriture

Passer en clé de production, puis enregistrer un paiement sur une facture :

curl -s -X POST "$HELA_API/companies/$COMPANY/sales/<saleId>/payments" \
  -H "Authorization: Bearer $HELA_KEY" \
  -H "Content-Type: application/json" \
  -H "Idempotency-Key: paiement-2026-09-28-0001" \
  -d '{ "walletId": "<walletId>", "amount": 125.00, "note": "Virement reçu" }'

L'en-tête Idempotency-Key est facultatif mais recommandé pour toute écriture : si votre programme réessaie après un délai réseau, Hela rejoue la première réponse au lieu d'enregistrer deux paiements. Voir Pagination, erreurs, idempotence.

Les corps de requête des écritures acceptent les montants en unité majeure (125.00), comme un humain les tape ; les réponses les renvoient en unité mineure (12500). Cette asymétrie est voulue : la saisie est pour vous, le stockage est pour la machine.

5. Un webhook

Sur la même page, Nouveau webhook : une adresse HTTPS et les événements qui vous intéressent. Hela envoie aussitôt un ping ; le bouton Tester le renvoie à volonté. Le secret, affiché une fois, sert à vérifier la signature de chaque envoi.

Ensuite

  • Le schéma OpenAPI complet est servi par le serveur lui-même : GET /openapi.json, et une interface de consultation sur /docs.
  • Le SDK TypeScript encapsule tout cela avec les types.
  • Sans code : Zapier, Make, n8n.

فقرة خاطئة أو ناقصة؟ راسلنا.