API

Olvano dispose d'une API REST pour connecter vos propres systèmes — créer et lire des factures, gérer des contacts et écouter des événements via les webhooks. Cette page vous mène d'un token à votre premier appel ; la liste complète et exécutable des endpoints se trouve dans la référence interactive.

Avant de commencer

Il vous faut deux choses :

1. Un compte sur le forfait byznys (le forfait free n'a pas d'API).
2. Un token API rattaché à ce compte (voir ci-dessous).

Les tokens sont créés par le propriétaire du compte. Un token appartient à un seul compte et porte ses propres autorisations (scopes), ce qui vous permet d'émettre un token distinct par intégration.

Créer un token API

Dans l'application, allez dans Réglages → Tokens API (/app/{slug}/settings/api-tokens), choisissez Nouveau token, nommez-le et sélectionnez ses autorisations. Le token en clair n'est affiché qu'une seule fois — copiez-le immédiatement et conservez-le en lieu sûr.

Les tokens sont préfixés par sg_. Seul un condensé HMAC est stocké : le token ne peut donc jamais être réaffiché — si vous le perdez, créez-en un nouveau et supprimez l'ancien.

Autorisations (scopes)

La lecture (GET) des ressources courantes ne demande aucun scope ; l'écriture, si. Les opérations réservées au propriétaire (gestion des tokens, des webhooks et des comptes bancaires) ne sont jamais accessibles à un token API — même émis par un propriétaire, il renvoie 403.

Authentification et URL de base

Authentifiez chaque requête avec le token dans l'en-tête Authorization :

Authorization: Bearer sg_your_token

L'URL de base est le domaine de votre instance + /api. Les endpoints de compte ont la forme /api/accounts/{slug}/…. Les exemples ci-dessous utilisent des variables d'environnement :

export STARGATE="https://app.stargate.app"   # remplacez par le domaine de votre instance (en local http://localhost:3000)
export SLUG="your-account-slug"
export TOKEN="sg_your_token"

Votre première requête

Lister les factures d'un compte :

curl "$STARGATE/api/accounts/$SLUG/invoices" \
  -H "Authorization: Bearer $TOKEN"

La réponse est une liste paginée :

{
  "invoices": [ { "id": "…", "number": "2026-0001", "status": "open", "total": "3630.00" } ],
  "total": 128,
  "page": 1,
  "pageSize": 40
}

Pagination, tri et recherche

Les endpoints de liste acceptent ces paramètres de requête :

Les factures peuvent en plus être filtrées par status, documentType et subjectId. Un paramètre invalide ne casse jamais la liste — la valeur par défaut est utilisée à la place (par ex. ?page=abc → 1). Chaque réponse porte total, page et pageSize, ce qui rend le nombre de pages facile à calculer.

Créer une facture

curl -X POST "$STARGATE/api/accounts/$SLUG/invoices" \
  -H "Authorization: Bearer $TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "subjectId": "CUSTOMER_ID",
    "lines": [
      { "name": "Consulting", "quantity": 2, "unitPrice": "1500", "vatRate": 21 }
    ]
  }'

subjectId est l'identifiant du client — récupérez-le dans la liste des contacts (GET /api/accounts/$SLUG/subjects) ou créez-en un via POST …/subjects. Les champs obligatoires sont subjectId et au moins une ligne dans lines (chacune avec name et unitPrice). En option, vous pouvez envoyer documentType, currency, variableSymbol, due, issuedOn et d'autres — schéma complet dans la référence interactive.

En cas de succès, la réponse est 201 accompagnée de la facture créée :

{ "invoice": { "id": "…", "number": "2026-0002", "status": "open", "total": "3630.00" } }

Erreurs

Les erreurs partagent une enveloppe cohérente — un statut HTTP plus un JSON avec statusMessage et un champ data pour le traitement automatique :

{
  "statusCode": 400,
  "statusMessage": "Invalid invoice",
  "data": { "formErrors": [], "fieldErrors": { "subjectId": ["Required"] } }
}

Pour les erreurs métier, data.code est un code exploitable par machine (par ex. subject_not_found) sur lequel vous pouvez vous appuyer davantage que sur le texte du message.

Limites des forfaits

Le forfait free ne fait aucun appel API (quota 0) ; byznys dispose de l'API et de toutes les fonctionnalités. Lorsqu'une limite est dépassée (par ex. le nombre de contacts), l'API renvoie 402 avec plan_limit_reached ; pour une fonctionnalité hors forfait (webhooks, dépenses…), elle renvoie 403 avec plan_feature_unavailable. Consultez les limites et l'usage actuels de votre compte via :

curl "$STARGATE/api/accounts/$SLUG/entitlements" -H "Authorization: Bearer $TOKEN"

Webhooks

Un webhook vous notifie des événements en temps réel, plutôt que d'interroger l'API en boucle. Les webhooks sont une fonctionnalité du forfait byznys et sont gérés par le propriétaire du compte.

Enregistrez-en un via l'API (ou dans les réglages du compte) :

curl -X POST "$STARGATE/api/accounts/$SLUG/webhooks" \
  -H "Authorization: Bearer $TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "webhookUrl": "https://your-server.com/hooks/stargate",
    "events": ["invoice_paid", "invoice_sent"],
    "authHeader": "Bearer your-shared-secret"
  }'

Indiquez des noms précis dans events, ou * pour tous. Événements disponibles :

invoice_created, invoice_sent, invoice_paid, invoice_overdue, invoice_cancelled, invoice_uncollectible, invoice_viewed, invoice_reminder_sent, recurring_generator_invoice_created.

Olvano envoie un POST à votre URL avec le corps :

{ "event_name": "invoice_paid", "body": { "…": "event data" } }

• Si vous définissez authHeader, il est envoyé comme en-tête Authorization — utilisez-le pour vérifier que la requête provient bien de Olvano.
• Chaque livraison porte un en-tête Idempotency-Key (UUID) — utilisez-le pour dédupliquer.
• La livraison est réessayée jusqu'à 5× avec un backoff exponentiel tant que vous ne renvoyez pas un statut 2xx. Les livraisons en échec sont listées via GET …/webhooks/{id}/failed_deliveries.

Référence interactive

La liste complète et toujours à jour des endpoints — avec les paramètres, les schémas et la possibilité de les appeler directement depuis le navigateur :

• Ouvrir la référence API (/api-docs)
• Schéma OpenAPI exploitable par machine : /api/_openapi.json