L'API publique de Bill Alps expose, en REST, ce que l'application fait à l'écran : clients, factures, devis, employés, fiches de salaire, dépenses et comptabilité. Ce guide vous emmène de zéro à un premier appel réussi, sur le sandbox, sans rien toucher à vos données de production.
BASE=https://<deployment>.convex.site/api/v1
KEY=ba_...1. Ce que couvre l'API
L'API v1 tourne au-dessus du même code que l'application : chaque route appelle la logique métier de l'app, avec les mêmes contrôles, les mêmes quotas et les mêmes PDF. Ce qui est refusé à l'écran est refusé par l'API.
- Compte et sociétés :
/me,/companies(profil et logo de la société),/mandatespour les fiduciaires. - Facturation : clients (à l'unité ou par lot), catalogue de produits et listes de produits, modèles de facture, factures, devis, factures récurrentes, avec leurs PDF et leur envoi par e-mail.
- Paie : employés, absences, fiches de salaire (création à l'unité ou par lot, validation, envoi, correction, duplication, PDF par lot), jours fériés et aperçus, état des liens de l'espace employé.
- Dépenses et banque : dépenses et justificatifs, brouillons et extraction par IA, transactions bancaires importées.
Le contrat publie aussi les routes du grand livre, de la TVA et des comptes annuels, mais elles répondent 403 LEDGER_DISABLED en production.
Les routes adressées à une société (/companies/{companyId}/…) exigent que cette société soit sur le plan Business, et que le module concerné (facturation, paie ou comptabilité) soit activé dans Mon compteModules. Si votre abonnement Business ne couvre pas un module activé, ses routes répondent quand même, mais avec les limites du plan Starter. Les clés sont des identifiants serveur à serveur : les endpoints n'ont pas de CORS, volontairement, donc jamais de clé dans un navigateur ou une application mobile.
2. Commencer sur le sandbox
Dans le sandbox, chaque société est vue comme Business quel que soit son plan réel, ce qui ouvre toutes les routes même à un compte Starter. Les e-mails ne partent pas, Stripe ne facture rien, les invitations d'équipe ne sont pas envoyées. Tout le reste fonctionne, y compris les tâches planifiées : c'est l'endroit idéal pour construire et tester une intégration.
Deux différences avec la production. Le grand livre y est ouvert, donc ses routes n'y répondent pas 403 LEDGER_DISABLED ; le plan comptable et les écritures ne sont toutefois pas copiés, il faut activer la comptabilité sur le sandbox pour les utiliser. Et sur un environnement vide, la société créée garde les quotas du plan Starter, même si toutes les routes lui répondent.
3. Créer une clé
- Créez la clé depuis n'importe quelle société Business que vous administrez : la société ne sert qu'à autoriser la création, la clé est personnelle et ne porte aucune société.
- Il faut le rôle propriétaire ou admin sur la société active, et celle-ci doit être sur Business (dans le sandbox, c'est toujours le cas).
- Une clé appartient à la personne qui l'a créée, pas à la société : elle agit sur toutes les sociétés auxquelles cette personne a accès, avec ses permissions. Jusqu'à 10 clés actives par utilisateur.
- Le champ Expiration vaut Aucune expiration par défaut. Une clé expirée répond
401 INVALID_API_KEY, comme une clé révoquée. - Pour faire tourner une clé : créez-en une seconde, migrez votre intégration, puis révoquez la première depuis le même écran.
4. Base URL et en-tête
L'API ne vit pas sur l'hôte de l'application mais sur une adresse en .convex.site, propre à chaque environnement. Le panneau Clés API ne l'affiche pas en clair : son lien Swagger de l'API ouvre https://<deployment>.convex.site/api/docs, et la base URL est la même origine suivie de /api/v1. Le panneau du sandbox pointe vers le sandbox, celui de la production vers la production ; les clés ne sont pas interchangeables entre les deux, une clé de sandbox est inconnue de la production.
Chaque requête porte la clé dans l'en-tête Authorization :
Authorization: Bearer ba_...5. Premier appel
Le premier appel à faire est GET /me : il vous dit qui porte la clé et sur quoi elle peut agir.
curl -H "Authorization: Bearer $KEY" $BASE/meLa réponse contient data.companies[], chaque société avec son id, votre role, son plan effectif et ses modules. Ces id sont ceux que prennent toutes les routes /companies/{companyId}/…. La même liste existe en tableau brut :
curl -H "Authorization: Bearer $KEY" $BASE/companiesUne société sur Starter ou Équipe (plan vaut free ou team) apparaît dans la liste, mais ses routes répondent 403 PLAN_NOT_ALLOWED. Choisissez une société dont le module qui vous intéresse est activé, et vous êtes prêt pour les guides suivants.
6. Documentation interactive
Chaque déploiement se décrit lui-même. Sur https://<deployment>.convex.site/api/docs, une Swagger UI présente le contrat en vigueur : cliquez sur Authorize, collez une clé ba_, puis « Try it out » sur n'importe quelle route. La clé reste dans le stockage local du navigateur jusqu'au Logout, donc préférez une clé révocable et le sandbox.
Le document OpenAPI 3.1 est servi sur https://<deployment>.convex.site/api/v1/openapi.json, public, sans clé, avec CORS ouvert. Il est généré à la demande à partir de la table des routes et des schémas de requête et de réponse : ce qu'il décrit est exactement ce que l'API applique. servers[0].url reprend l'origine d'où vous l'avez téléchargé, suivie de /api/v1, production et sandbox pointent donc chacun sur eux-mêmes. Collez l'URL dans editor.swagger.io pour le parcourir, ou servez-vous-en pour générer un client.
Sur le sandbox, le panneau Mon compteClés API propose aussi un lien Documentation DEV vers le schéma de données de l'application (diagramme entités-relations), utile pour comprendre comment les ressources se tiennent entre elles.
La suite se lit dans l'ordre qui vous convient : facturer par l'API, paie, dépenses et comptabilité par l'API, cycle de paie par l'API et, pour les règles transverses, conventions et erreurs. La Swagger UI de votre déploiement reste la référence de chaque champ.