--- title: "Démarrage" description: "Introduction rapide à l'API Billabex : s'authentifier et faire son premier appel." canonical: https://developer.billabex.com/fr/guides/demarrage/ lang: fr alternate: https://developer.billabex.com/en/guides/getting-started/ last-updated: 2026-10-25 --- # Démarrage > Introduction rapide à l'API Billabex : s'authentifier et faire son premier appel. Source: https://developer.billabex.com/fr/guides/demarrage/ Langue: Français (fr) Version anglaise: https://developer.billabex.com/en/guides/getting-started/ Bienvenue dans l'API Billabex 👋 Ce guide vous mène pas à pas de l'authentification à vos premiers appels réussis. À la fin, vous aurez : - un client OAuth configuré ; - un jeton d'accès ; - l'identifiant de votre organisation ; - vos premiers appels en lecture et en écriture. ## Qu'est-ce que Billabex ? Billabex est une **plateforme d'automatisation du suivi des paiements propulsée par l'IA**, qui aide les entreprises à encaisser plus vite leurs créances. Notre agent : - relance automatiquement les factures impayées ; - communique avec les clients en plusieurs langues ; - adapte son ton et son rythme avec tact et diplomatie. Avec l'API Billabex, vous pouvez : - **gérer les factures et les avoirs** par programme ; - **synchroniser les comptes clients et leurs contacts** ; - **suivre les communications et les soldes** ; - **intégrer Billabex à vos parcours de facturation**. ## Prérequis Avant de commencer, assurez-vous d'avoir : 1. **un compte Billabex** L'accès est uniquement sur invitation. Pour obtenir un compte, un échange avec un commercial est obligatoire : prenez rendez-vous sur , puis créez votre compte depuis le lien d'invitation reçu. 2. **une organisation** créée par Billabex, à laquelle vous avez été invité 3. **un client OAuth** créé dans le portail développeur ## Étape 0 : regarder avant de s'authentifier Un appel, sans identifiant ni compte : ```bash curl -i https://next.billabex.com/api/public/v1/status ``` Il renvoie les endpoints de métadonnées OAuth, l'endpoint d'enregistrement dynamique de client, les deux quotas de limitation de débit et toutes les URL de documentation ; ses en-têtes montrent la famille `RateLimit` en conditions réelles. Le catalogue des outils MCP, sur `https://next.billabex.com/mcp/tools`, est ouvert de la même façon. Tout ce qui suit lit ou écrit des données appartenant à une organisation, et exige donc un jeton. Il n'existe pas de sandbox partagé : demandez à Billabex une organisation dédiée à vos tests, et mettez en pause les relances des comptes que vous y utilisez pour qu'aucun message ne parte vers un vrai client. ## Étape 1 : créer un client OAuth Rendez-vous dans **Portail développeur → Clients OAuth** et créez un client. Vous retrouvez les mêmes clients dans la webapp Billabex, sur **Mon compte → Mes clients OAuth** : ils appartiennent à votre compte utilisateur, pas à une organisation. Vous devrez fournir : - **Nom du client** : le nom de votre application - **URI de redirection** : votre URL de rappel OAuth Par exemple `https://votreapp.com/callback` - **Scopes** : les permissions dont votre application a besoin (voir le [guide des scopes](/fr/guides/scopes/)) Une fois créé, vous recevez : - un `client_id` ; - un `client_secret`, affiché une seule fois. Conservez le secret client en lieu sûr. ## Étape 2 : implémenter l'authentification OAuth Billabex utilise le **flux OAuth 2.1 d'autorisation par code avec PKCE**. Sur le principe : - votre application prouve son identité par PKCE ; - l'utilisateur approuve l'accès ; - vous recevez des jetons à durée de vie courte pour appeler l'API. Concrètement, vous allez : 1. générer un vérificateur et un défi PKCE ; 2. rediriger l'utilisateur vers la page d'autorisation ; 3. recevoir un code d'autorisation ; 4. échanger ce code contre un jeton d'accès et un jeton de rafraîchissement. ### Générer les paramètres PKCE Générez un `code_verifier` et le `code_challenge` correspondant. Gardez le vérificateur en mémoire : vous le réutiliserez à l'échange. ```javascript // Générer le vérificateur (chaîne aléatoire) const codeVerifier = generateRandomString(128); // Générer le défi (empreinte SHA256 du vérificateur, encodée en base64url) const codeChallenge = base64UrlEncode(sha256(codeVerifier)); ``` ### Rediriger vers la page d'autorisation Construisez l'URL d'autorisation et redirigez l'utilisateur. ```javascript const authUrl = new URL('https://next.billabex.com/api/oauth/authorize'); authUrl.searchParams.append('client_id', 'YOUR_CLIENT_ID'); authUrl.searchParams.append('redirect_uri', 'https://votreapp.com/callback'); authUrl.searchParams.append('response_type', 'code'); authUrl.searchParams.append('scope', 'invoices:read accounts:read'); authUrl.searchParams.append('code_challenge', codeChallenge); authUrl.searchParams.append('code_challenge_method', 'S256'); authUrl.searchParams.append('state', generateRandomString(16)); // Rediriger l'utilisateur vers authUrl ``` Validez toujours le `state` renvoyé, pour vous protéger des attaques CSRF. ### Échanger le code contre des jetons Après approbation, votre URI de redirection reçoit un code d'autorisation. Échangez-le sur l'endpoint de jeton. ```javascript const response = await fetch('https://next.billabex.com/api/oauth/token', { method: 'POST', headers: { 'Content-Type': 'application/json' }, body: JSON.stringify({ grant_type: 'authorization_code', code: authorizationCode, redirect_uri: 'https://votreapp.com/callback', code_verifier: codeVerifier, client_id: 'YOUR_CLIENT_ID', client_secret: 'YOUR_CLIENT_SECRET', }), }); const tokens = await response.json(); ``` Exemple de réponse : ```json { "access_token": "...", "token_type": "Bearer", "expires_in": 3600, "refresh_token": "...", "scope": "invoices:read accounts:read" } ``` Pour le détail, voyez le [guide OAuth](/fr/guides/oauth/). ## Étape 3 : récupérer l'identifiant de votre organisation La plupart des endpoints exigent un `organizationId`. Utilisez votre jeton d'accès pour lister les organisations auxquelles vous appartenez et choisir celle sur laquelle travailler. ```javascript const response = await fetch('https://next.billabex.com/api/public/v1/organizations?first=10', { headers: { Authorization: `Bearer ${accessToken}`, 'Content-Type': 'application/json', }, }); const data = await response.json(); const organizationId = data.nodes?.[0]?.id; ``` ## Étape 4 : votre premier appel Avec un jeton d'accès et un identifiant d'organisation, vous pouvez appeler l'API publique. Exemple : lister les comptes de votre organisation. ```javascript const response = await fetch( 'https://next.billabex.com/api/public/v1/accounts?organizationId=YOUR_ORG_ID&first=10', { headers: { Authorization: `Bearer ${accessToken}`, 'Content-Type': 'application/json', }, }, ); const data = await response.json(); console.log(data); ``` ### Avec cURL ```bash curl -X GET "https://next.billabex.com/api/public/v1/accounts?organizationId=YOUR_ORG_ID&first=10" \ -H "Authorization: Bearer YOUR_ACCESS_TOKEN" \ -H "Content-Type: application/json" ``` ## Étape 5 : gérer la pagination L'API Billabex utilise une **pagination par curseur**. - Lisez `pageInfo.endCursor` dans la réponse - Passez-le en paramètre `after` pour obtenir la page suivante - Quand `endCursor` est absent, vous êtes au bout ```javascript const nextPageResponse = await fetch( `https://next.billabex.com/api/public/v1/accounts?organizationId=YOUR_ORG_ID&first=10&after=${data.pageInfo.endCursor}`, { headers: { Authorization: `Bearer ${accessToken}`, 'Content-Type': 'application/json', }, }, ); ``` Le [guide de la pagination](/fr/guides/pagination/) entre dans le détail. ## Étape 6 : créer une facture Créer une facture est une **opération d'écriture**, qui exige le scope `invoices:all`. Cet endpoint attend : - du `multipart/form-data` ; - un fichier PDF ou image ; - les métadonnées et les montants de la facture ; - une adresse de facturation, dont les champs peuvent être vides mais doivent être présents. Exemple : ```javascript const formData = new FormData(); formData.append('accountId', 'ACCOUNT_ID'); formData.append('number', 'INV-2024-001'); formData.append('issuedDate.year', '2024'); formData.append('issuedDate.month', '1'); formData.append('issuedDate.day', '15'); formData.append('dueDate.year', '2024'); formData.append('dueDate.month', '2'); formData.append('dueDate.day', '15'); formData.append('totalAmount', '1500.00'); formData.append('taxAmount', '300.00'); formData.append('paidAmount', '0'); formData.append('poNumber', 'PO-2024-001'); formData.append('billingAddress.street', '1 rue Exemple'); formData.append('billingAddress.city', 'Paris'); formData.append('billingAddress.postalCode', '75001'); formData.append('billingAddress.country', 'FR'); formData.append('file', fileBlob, 'facture.pdf'); const response = await fetch('https://next.billabex.com/api/public/v1/invoices', { method: 'POST', headers: { Authorization: `Bearer ${accessToken}`, }, body: formData, }); const invoice = await response.json(); ``` ## Dates et instants L'API distingue deux sortes de dates. Une **date calendaire** désigne un jour, sans heure ni fuseau horaire. Dans les réponses, la plupart des dates calendaires, comme les dates d'émission, les échéances et les dates de référence, sont un objet de trois nombres. Par exemple, l'échéance d'une facture, ou celle d'une fraction dans `GET /api/public/v1/accounts/{accountId}/financial-overview` : ```json { "dueDate": { "year": 2026, "month": 10, "day": 15 } } ``` Un **instant** désigne un moment précis, et il est une chaîne ISO 8601 en UTC, comme la date d'envoi d'un email : ```json { "sentAt": "2026-10-15T08:30:00.000Z" } ``` Lisez une date calendaire par le nom de ses champs. L'ordre des propriétés d'un objet JSON n'est pas garanti, et l'objet n'est pas une chaîne : `dueDate.slice(0, 10)` échoue. Pour l'afficher, partez de ses composantes : ```javascript const { year, month, day } = invoice.dueDate; const label = `${String(day).padStart(2, '0')}/${String(month).padStart(2, '0')}/${year}`; // "15/10/2026" ``` Ne convertissez pas une échéance en instant UTC pour l'afficher : `new Date(Date.UTC(2026, 9, 15))` affiché dans un fuseau à l'ouest de Greenwich donne le 14 octobre. Un instant, lui, se convertit dans le fuseau de l'utilisateur : ```javascript new Date(email.sentAt).toLocaleString('fr-FR', { timeZone: 'Europe/Paris' }); // "15/10/2026 10:30:00" ``` Deux champs d'un compte font exception : `bodaccNoticeDate` (date de publication de l'annonce au BODACC) et `bodaccJudgmentDate` (date du jugement) sont des jours, mais ils sont envoyés en instants à minuit UTC, comme `"2026-08-23T00:00:00.000Z"`. Lisez leur partie date en UTC et ne les convertissez jamais en heure locale, qui afficherait la veille à l'ouest de Greenwich : ```javascript const noticeDay = account.bodaccNoticeDate?.slice(0, 10); // "2026-08-23" ``` Le `authorizedPaymentDeadline` d'un courrier ou d'un message sortant est lui aussi un jour, mais il revient en chaîne `AAAA-MM-JJ`, telle qu'elle a été envoyée (`"2026-08-25"`) : lisez-le tel quel, sans le convertir en instant. En entrée, suivez le schéma de chaque endpoint. La création de facture prend les composantes en champs séparés (`dueDate.year`, `dueDate.month`, `dueDate.day`), les endpoints JSON qui modifient une échéance prennent le même objet, et quelques paramètres, comme les filtres de liste, prennent une chaîne `AAAA-MM-JJ`. La [référence de l'API](/fr/reference-api/) donne le type de chaque champ. ## Les champs inconnus sont refusés L'API répond `400 Bad Request` quand le corps d'une requête porte un champ que l'endpoint ne déclare pas, en nommant le champ fautif : ```json { "statusCode": 400, "message": "property phone should not exist" } ``` C'est délibéré. Accepter le champ et l'ignorer laisserait un champ renommé ou mal orthographié disparaître derrière un `201 Created`, et vous ne le découvririez qu'au moment où la donnée manque. Un `400` échoue tout de suite, dans vos tests d'intégration plutôt qu'en production. En pratique : envoyez exactement les champs documentés pour l'endpoint. Ne renvoyez pas un objet de réponse entier dans une requête d'écriture, les réponses portant des champs en lecture seule (`id`, `createdAt`, totaux calculés) qu'aucun endpoint d'écriture ne déclare. ## Pour aller plus loin Vous êtes prêt à intégrer Billabex 🎉 Lectures recommandées : - **[Authentification OAuth](/fr/guides/oauth/)** : OAuth en détail - **[Scopes OAuth](/fr/guides/scopes/)** : les permissions disponibles - **[Limites de débit](/fr/guides/limites-de-debit/)** : éviter de les atteindre - **[Pagination](/fr/guides/pagination/)** : parcourir efficacement les données - **[Sources de compte](/fr/guides/sources-de-compte/)** : relier un compte à un système externe - **[Opérations upsert](/fr/guides/upsert/)** : créer ou mettre à jour de façon idempotente - **[Contacts](/fr/guides/contacts/)** : gérer les personnes d'un compte - **[Tâches et interactions](/fr/guides/taches-de-compte/)** : répondre aux tâches ouvertes par l'agent - **[Envoi de fichiers](/fr/guides/televersement-de-fichiers/)** : encodage binaire et base64 - **[Référence de l'API](/fr/reference-api/)** : documentation complète des endpoints ## Support Besoin d'aide, ou un retour sur ce guide ? Écrivez-nous via le [formulaire de contact](https://www.billabex.com/fr/contactez-nous/). ## Langues de l’interface et de l’organisation La langue utilisateur et le champ `language` des réglages d’organisation acceptent `fr`, `en` et `es` (espagnol d’Espagne). La langue de l’organisation régit les nouvelles tâches internes et les invitations, indépendamment de celle des membres. La langue des contacts reste distincte. Les exports de factures acceptent aussi `locale=es`. `GET /accounts/{accountId}/dunning` et l’outil MCP `get-account-dunning-status` renvoient `situationSummary` (`summaryEn`, `summaryFr`, `summaryEs`, `generatedAt`). Le résumé est null s’il n’a jamais été généré; `summaryEs` reste null sur un ancien résumé jusqu’à sa prochaine génération. Les dates sont en ISO 8601. Aucun outil MCP supplémentaire n’est nécessaire. La même route renvoie `blockingTaskIds`, les identifiants des tâches ouvertes qui bloquent les relances du compte, plus anciennes d’abord (vide sinon). Lisez chacune avec `GET /account-tasks/{accountTaskId}`. L’outil MCP `list-accounts` porte ce champ sur chaque compte de la page. --- Billabex developer portal. OpenAPI specification: https://developer.billabex.com/openapi.json. Agent instructions: https://developer.billabex.com/llms.txt. Complete documentation: https://developer.billabex.com/llms-full.txt.