Référence de l’API (bêta)

L’API de To Bill est celle que l’app utilise elle-même : clients, factures, offres, articles, dépenses, banque, comptabilité, TVA, salaires et temps. Une clé API personnelle l’ouvre à vos scripts et à vos outils, avec vos droits. La référence interactive de l’API décrit chaque route qu’une clé peut appeler, ses paramètres et ses réponses, donne des exemples en curl, JavaScript, Python et PHP, et vous laisse essayer une requête avec votre clé.

La référence est en anglais

Comme la plupart des références techniques, elle est rédigée en anglais, la langue des développeurs. Cette page en résume l’essentiel.

Une version bêta

L’API est en version bêta (0.x). Ses routes et leurs réponses peuvent changer sans préavis : il n’y a ni garantie de compatibilité, ni support pour son utilisation directe. Pour connecter un assistant IA, utilisez le serveur MCP, qui est l’interface stable : voir Connecter un assistant IA.

S’authentifier

Chaque requête porte une clé API personnelle dans l’en-tête HTTP Authorization :

curl https://app.tobill.ch/api/clients -H "Authorization: Bearer tb_pk_…"

La clé se crée dans Paramètres › Connexions IA et API : voir L’API et les clés API. Elle agit en votre nom, dans l’entreprise où vous l’avez créée, avec vos droits dans cette entreprise. Une clé Lecture seule n’envoie que des requêtes de lecture (GET) ; une clé Lecture et modification peut aussi créer, modifier et supprimer.

Les erreurs

Une requête refusée reçoit une réponse JSON de cette forme : { "statusMessage": "error", "message": "…", "error_code": "…", "fallback": "…" }. message est un code stable, à tester dans votre programme ; fallback est une phrase lisible, par exemple le champ en cause.

Code HTTP	Signification
400	Données invalides.
401	Clé absente, invalide, expirée ou révoquée.
403	Refusé : clé en lecture seule, droit manquant, abonnement sans accès à l’API, ou partie de To Bill fermée aux clés (not_available_with_api_token).
404	Introuvable dans cette entreprise.
429	Trop de requêtes : attendez le nombre de secondes indiqué par l’en-tête Retry-After.

Les limites

• 300 requêtes par minute et par clé ; une modification compte pour deux.
• Une clé n’ouvre ni la connexion à votre compte, ni l’abonnement, ni les paiements, ni la gestion de l’équipe et des clés, ni une autre entreprise, ni le cockpit d’une fiduciaire, ni les actions en masse. Ces routes ne figurent pas dans la référence.

La spécification OpenAPI

La référence est générée à partir du document OpenAPI 3.1 de l’API. Vous pouvez l’importer dans un outil comme Postman ou en générer un client :

Quoi	Adresse
Référence interactive	https://docs.tobill.ch/api
Spécification OpenAPI 3.1	https://app.tobill.ch/api/openapi.json

Essayer une requête

Dans la référence, le bouton Test Request envoie la requête depuis votre navigateur, directement à https://app.tobill.ch, sans intermédiaire. Votre clé ne part que chez To Bill et n’est pas enregistrée : elle disparaît quand vous fermez la page. Une requête de modification modifie vraiment vos données : pour découvrir l’API, essayez-la avec une clé Lecture seule.