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, et inversement.
- Compte et sociétés :
/me,/companies,/mandatespour les fiduciaires. - Facturation : clients, modèles de facture, factures, devis, factures récurrentes, avec leurs PDF et leur envoi par e-mail.
- Paie : employés, fiches de salaire (unitaire et par lot), absences.
- Dépenses et comptabilité : dépenses fournisseurs, transactions bancaires importées, état financier annuel.
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, dépenses, états financiers) soit activé. 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 Free. 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.
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.
- 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 le déploiement Convex qui la sert : une adresse en .convex.site, affichée dans le panneau Clés API juste sous vos clés. Le panneau du sandbox affiche l'adresse du sandbox, celui de la production l'adresse de 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 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 vaut l'origine d'où vous l'avez téléchargé, 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 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 et, pour les règles transverses, conventions et erreurs. La Swagger UI de votre déploiement reste la référence de chaque champ.