Aller au contenu principal

API REST

Augias expose une API REST sous /api/* qui reprend l'interface web : clients, factures, devis, paiements, factures récurrentes, taxes, etc. L'authentification passe par un jeton d'API propre à chaque utilisateur. La référence complÚte des points d'accÚs est générée automatiquement et servie par votre instance sur /api/docs.

astuce

Vous prĂ©fĂ©rez un langage de requĂȘte souple Ă  des points d'accĂšs fixes ? L'API GraphQL donne accĂšs aux mĂȘmes donnĂ©es autrement.

CrĂ©er un jeton d'API​

Connectez-vous à Augias et ouvrez Clés API dans le menu de votre profil (ou allez directement sur /profile/api). Cliquez sur Créer un jeton en haut à droite de la liste.

La page des jetons d'API avec les statistiques, le bandeau d'information, le bouton de création et un jeton existant

Dans la fenĂȘtre CrĂ©er un nouveau jeton API, renseignez :

  • Nom (obligatoire) : un libellĂ© pour le jeton. Choisissez de quoi reconnaĂźtre son usage, par exemple IntĂ©gration comptable ou Zapier.
  • Description (facultative) : une note plus longue sur le rĂŽle du jeton.

La fenĂȘtre de crĂ©ation d'un jeton avec les champs Nom et Description

Cliquez sur Enregistrer. La fenĂȘtre affiche alors la valeur du jeton :

La fenĂȘtre de confirmation avec la valeur du jeton, le bouton de copie et l'avertissement

attention

Le jeton n'est affichĂ© qu'une fois, juste aprĂšs sa crĂ©ation. Cliquez sur Copier et rangez-le dans un gestionnaire de mots de passe ou le coffre de secrets de votre intĂ©gration avant de cliquer sur J'ai copiĂ© le jeton. S'il est perdu, rĂ©voquez-le et crĂ©ez-en un autre : la valeur d'origine ne peut pas ĂȘtre retrouvĂ©e.

Consulter vos jetons​

La liste montre tous vos jetons, avec ces colonnes :

  • Nom, Description : ce que vous avez saisi Ă  la crĂ©ation ;
  • Nombre d'utilisations : le nombre total de requĂȘtes faites avec ce jeton ;
  • DerniĂšre utilisation : la date de la derniĂšre requĂȘte, vide s'il n'a jamais servi ;
  • Créé le : la date de crĂ©ation.

Les quatre cartes au-dessus de la liste résument ces données pour tous vos jetons : Jetons actifs, Appels API ce mois-ci, DerniÚre activité et Jeton le plus utilisé.

La liste se recherche et se trie. La valeur du jeton n'est plus jamais affichée aprÚs sa création : seul son nom l'est.

Consulter l'historique des requĂȘtes​

Chaque requĂȘte authentifiĂ©e avec succĂšs par un jeton est enregistrĂ©e pour ce jeton. Cliquez sur Voir l'historique sur la ligne du jeton pour ouvrir la liste des requĂȘtes.

L'historique des requĂȘtes avec mĂ©thode, point de terminaison, statut, adresse IP et agent utilisateur

Chaque ligne indique :

  • Date : l'arrivĂ©e de la requĂȘte ;
  • MĂ©thode : GET, POST, PATCH, PUT ou DELETE ;
  • Point de terminaison : le chemin appelĂ© (par exemple /api/invoices) ;
  • Statut : le code HTTP renvoyĂ© ;
  • Adresse IP : l'adresse du client au moment de la requĂȘte ;
  • Agent utilisateur : l'en-tĂȘte User-Agent envoyĂ© par le client.

L'historique se filtre par pĂ©riode, par mĂ©thode et par plage de statut, et affiche au plus les 100 requĂȘtes les plus rĂ©centes. Les authentifications manquĂ©es (sans jeton ou avec un mauvais jeton) ne sont pas enregistrĂ©es : seules les rĂ©ussies le sont.

RĂ©voquer un jeton​

Pour révoquer un jeton, cochez-le dans la liste, puis choisissez Révoquer dans les actions groupées.

attention

La rĂ©vocation est immĂ©diate, sans fenĂȘtre de confirmation. Le jeton est supprimĂ© avec tout son historique. Toute application qui l'utilise reçoit 401 Unauthorized dĂšs sa requĂȘte suivante : mettez vos intĂ©grations Ă  jour avant de rĂ©voquer.

Pour remplacer un jeton sans interruption, créez d'abord le nouveau, basculez votre intégration dessus, vérifiez qu'il fonctionne (sa DerniÚre utilisation se met à jour), puis seulement révoquez l'ancien.

Authentifier les requĂȘtes​

Envoyez le jeton dans l'en-tĂȘte HTTP X-API-TOKEN de chaque requĂȘte :

curl -H "X-API-TOKEN: <votre-jeton>" \
-H "Accept: application/ld+json" \
https://votre-instance.example/api/invoices

L'API est sans Ă©tat : pas de session, pas de jeton CSRF, pas d'aller-retour de connexion. Envoyez l'en-tĂȘte Ă  chaque requĂȘte. Un jeton vaut pour un utilisateur et une entreprise ; si votre compte appartient Ă  plusieurs entreprises, crĂ©ez un jeton par entreprise en passant sur chacune dans l'application avant de crĂ©er son jeton.

Sans jeton valide, le serveur répond 401 Unauthorized avec un corps JSON :

{ "message": "No API token provided" }

Formats de rĂ©ponse​

L'API nĂ©gocie le format par l'en-tĂȘte Accept. Formats disponibles :

Valeur d'AcceptFormat
application/ld+json (défaut)JSON-LD avec hypermédia Hydra
application/jsonJSON simple
application/hal+jsonJSON HAL
application/vnd.api+jsonJSON:API
application/xml ou text/xmlXML

Les collections sont paginées par 30 éléments par page par défaut. Le paramÚtre itemsPerPage change ce nombre :

curl -H "X-API-TOKEN: <votre-jeton>" \
"https://votre-instance.example/api/invoices?page=2&itemsPerPage=50"

Les erreurs sont renvoyées au format RFC 7807 application/problem+json, avec un title et un detail lisibles et un type exploitable par programme.

Limites de dĂ©bit​

L'API est limitĂ©e Ă  300 requĂȘtes par minute, en fenĂȘtre glissante. Le compteur est tenu par jeton pour les requĂȘtes authentifiĂ©es, et par adresse IP sinon.

Chaque rĂ©ponse indique l'Ă©tat de votre compteur dans ses en-tĂȘtes :

En-tĂȘteSignification
X-RateLimit-LimitLe budget total par fenĂȘtre (300).
X-RateLimit-RemainingLes requĂȘtes restantes dans la fenĂȘtre en cours.
X-RateLimit-ResetL'horodatage Unix de remise à zéro.

Au-delĂ , la rĂ©ponse est 429 Too Many Requests, avec un en-tĂȘte Retry-After et un corps application/problem+json. Attendez le nombre de secondes indiquĂ© par Retry-After avant de rĂ©essayer.

RĂ©fĂ©rence des points d'accĂšs​

L'interface Swagger interactive de votre installation fait foi : elle reflĂšte toujours exactement les ressources et les champs de votre version.

https://votre-instance.example/api/docs

Les principales ressources :

  • /api/invoices et /api/recurring-invoices
  • /api/quotes
  • /api/clients, /api/contacts et /api/addresses
  • /api/payments
  • /api/taxes
  • /api/api-tokens (gĂ©rer vos propres jetons par l'API)

Toutes les ressources acceptent les verbes habituels : GET pour les collections et les éléments, POST pour créer, PATCH pour modifier, DELETE pour supprimer. Les montants sont exprimés dans la plus petite unité de la devise (les centimes pour l'euro), et la devise vient du client concerné.

DĂ©pannage​

401 Unauthorized Ă  chaque requĂȘte​

Le jeton manque, est mal saisi ou a Ă©tĂ© rĂ©voquĂ©. Comparez la valeur de l'en-tĂȘte X-API-TOKEN avec l'original : des espaces en dĂ©but ou en fin, ou des guillemets parasites, se glissent souvent lors d'un copier-coller depuis un terminal ou un gestionnaire de mots de passe. Si le jeton ne fonctionne vraiment plus, crĂ©ez-en un autre et mettez votre intĂ©gration Ă  jour.

429 Too Many Requests​

Vous avez dĂ©passĂ© 300 requĂȘtes par minute. Lisez l'en-tĂȘte Retry-After et attendez au moins ce nombre de secondes. Pour une intĂ©gration Ă  fort volume, regroupez les requĂȘtes, mettez en cache les lectures frĂ©quentes et Ă©talez les appels sur la fenĂȘtre plutĂŽt que de les enchaĂźner.

L'authentification rĂ©ussit mais la requĂȘte est refusĂ©e en 403​

Le jeton est valide, mais l'utilisateur n'a pas le droit de faire cette action. Vérifiez que la ressource appartient à l'utilisateur (ou qu'il a le bon rÎle dans l'entreprise propriétaire) et que le jeton a été créé quand cette entreprise était active.

L'historique n'enregistre pas vos appels​

Seules les authentifications rĂ©ussies sont enregistrĂ©es. Des requĂȘtes qui renvoient 401 n'apparaissent pas dans Voir l'historique, mĂȘme si elles atteignent le serveur. Faites au moins une requĂȘte qui renvoie 2xx et rafraĂźchissez l'historique pour vĂ©rifier que le jeton fonctionne.