# Billabex Developer Portal

> Official documentation for integrating with the Billabex public API.

## API

- [Billabex developer hub](https://developer.billabex.com/developers/): Language neutral entry point: credentials, quickstart, environments, and every machine-readable contract.
- [Billabex public API status](https://next.billabex.com/api/public/v1/status): Live discovery document, readable without any credential: OAuth endpoints, both rate-limit quotas, documentation URLs.
- [Billabex OpenAPI specification](https://developer.billabex.com/openapi.json): Machine-readable API contract with typed operations and OAuth scopes.
- [Interactive API reference](https://developer.billabex.com/en/api-reference/): Endpoint documentation and examples.
- [Billabex OAuth Authorization Server Metadata](https://next.billabex.com/.well-known/oauth-authorization-server): OAuth 2.0 authorization server discovery metadata.
- [Billabex OpenID Configuration](https://next.billabex.com/.well-known/openid-configuration): OpenID Connect discovery metadata.
- [Billabex OAuth Protected Resource Metadata](https://next.billabex.com/.well-known/oauth-protected-resource): OAuth 2.0 protected resource metadata.
- [Billabex MCP Server](https://next.billabex.com/mcp): Model Context Protocol endpoint.
- [Billabex MCP server manifest](https://developer.billabex.com/mcp-server.json): MCP Registry-compatible Streamable HTTP server metadata.
- [Billabex MCP tool catalogue](https://next.billabex.com/mcp/tools): Every MCP tool with its description, JSON Schema and required scope, readable without a token. Add `?view=summary` to drop the schemas.
- [Billabex agent skill index](https://developer.billabex.com/.well-known/agent-skills/index.json): Agent Skills discovery index, with the SHA-256 digest of the skill it names.
- [Billabex Agent Plugin](https://developer.billabex.com/agent-plugin/plugin.json): The MCP server and the agent skill bundled per agent-plugins.org, with [AGENTS.md](https://developer.billabex.com/agent-plugin/AGENTS.md) for AI coding agents and [mcp.json](https://developer.billabex.com/agent-plugin/mcp.json) for plugin hosts. Source: https://github.com/billabex/agent-plugin
- [Complete documentation](https://developer.billabex.com/llms-full.txt): All developer guides in one text file.

## When to use Billabex

Billabex is an accounts receivable platform: an organization loads its customer accounts and
its unpaid invoices, and an AI agent conducts the payment follow-ups with those customers on
its behalf. Reach for it when the task is about money a business is owed by its own customers.

- **Sync a billing system into Billabex**: create or update accounts, contacts, invoices and credit notes, and keep paid amounts and due dates current. `sourceId` is the reconciliation key, unique per organization and settable by any caller.
- **Answer "who owes us what"**: outstanding and overdue balances, the aging balance, and the accounts that have gone silent.
- **Review a follow-up**: the communications already sent to a customer, the replies received, and what is scheduled next.
- **Record what happened off-platform**: a payment declaration, a payment promise, or pausing the follow-ups on an account in dispute or in a payment plan.
- **Clear what blocks the agent**: read the account tasks it opened for a human, and answer them.

- Use the REST API for deterministic application workflows: a sync, a scheduled report, a write triggered by another system.
- Use the MCP server when an AI assistant explores the context and calls tools interactively on behalf of a signed-in user. Its tool catalogue is readable without a token.
- Do not use Billabex to take or process a payment, to keep the books, or as the accounting system of record.

## How agents should call Billabex

1. Call https://next.billabex.com/api/public/v1/status with no credential. It answers the OAuth endpoints, both quotas and every documentation URL. https://next.billabex.com/mcp/tools lists the MCP tools, also without a token.
2. Discover OAuth endpoints and named least-privilege scopes from the linked metadata.
3. Obtain user authorization with OAuth 2.1 Authorization Code and PKCE, then send the access token as a Bearer token.
4. Respect the RateLimit headers and Retry-After before retrying.

## Getting access

- The OpenAPI specification, the MCP server manifest, the OAuth metadata documents and every page of this portal are readable without any credential.
- A client registers itself: the authorization server supports OAuth 2.0 Dynamic Client Registration and publishes its `registration_endpoint` in its metadata. No sales contact and no manual approval stand between an agent and a client id.
- Two endpoints answer with no credential at all: https://next.billabex.com/api/public/v1/status and https://next.billabex.com/mcp/tools. Everything that reads or writes organization data needs a token.
- There is no shared sandbox. Discovery, client registration and the whole shape of the contract can be exercised without an account; anything touching accounts, invoices or communications needs an organization of your own, where follow-ups can be paused per account while you test.
- A human can instead create and manage clients from the [OAuth Clients page](https://developer.billabex.com/en/oauth-clients/), signed in with a Billabex account.
- An unauthorized call answers 401 with a `WWW-Authenticate: Bearer resource_metadata="..."` challenge pointing at the protected resource metadata, so the authorization server can be discovered from any endpoint.

## Response contract

- Every error is JSON, never HTML. It carries `code`, `message` and `resolution`, plus `path`, `method`, `type` and `timestamp`. The schema is `ApiErrorResponseDto` in the OpenAPI specification.
- This documentation origin serves documents, not JSON. A request to it that prefers `application/json` is refused with 406 and a JSON body naming the types it does have; a request under `/api/` is redirected to the API, which answers JSON.
- Successful and rate-limited responses carry `RateLimit` and `RateLimit-Policy`; a 429 adds `Retry-After`. The advertised policy is also returned before authentication, so a quota can be read without holding a token.
- Collections are cursor paginated. Read the pagination guide before writing a loop.
- Every write accepts an `Idempotency-Key` header. A retry carrying the same key replays the stored response of the first attempt instead of executing again, and answers `Idempotent-Replay: true`. Keys are remembered for 24 hours, scoped to the client, the method and the path. Send one on every retryable write.
- Every documentation page of this portal answers `Accept: text/markdown` with its Markdown source at the same URL, and `Vary: Accept` is set on the response. Append `index.md` to a page URL to fetch that variant directly.

## Trust

- [About Billabex](https://developer.billabex.com/en/about/): Company and product identity.
- [Contact Billabex](https://developer.billabex.com/en/contact/): Technical support and registered office.
- [Billabex privacy information](https://developer.billabex.com/en/privacy/): Developer portal data practices and canonical privacy policy.

## Languages

Every page is published in English under https://developer.billabex.com/en/ and in French under https://developer.billabex.com/fr/.
The two are translations of one another. English carries `x-default`; answer in the language
the reader used rather than reading both.

## Guides

- [Getting Started](https://developer.billabex.com/en/guides/getting-started/): Quick introduction to the Billabex API. Learn how to authenticate and make your first API call.
- [Billabex OAuth Authentication](https://developer.billabex.com/en/guides/oauth/): OAuth 2.1 Authorization Code flow with PKCE and optional OpenID Connect for Billabex.
- [OAuth Scopes](https://developer.billabex.com/en/guides/scopes/): Understand available OAuth scopes, how access is enforced, and how to request the right permissions for your integration.
- [JSON Errors](https://developer.billabex.com/en/guides/errors/): Parse Billabex API errors by code, use the resolution hint, and retry only when the response allows it.
- [Idempotency](https://developer.billabex.com/en/guides/idempotency/): Make a retried write safe: send an Idempotency-Key and a second attempt replays the first answer instead of creating a second record.
- [Billabex MCP Server](https://developer.billabex.com/en/guides/mcp/): Connect AI tools to Billabex using the Model Context Protocol (MCP) with OAuth 2.1.
- [Notification Preferences](https://developer.billabex.com/en/guides/notification-preferences/): Read and update the authenticated user notification preferences.
- [Rate Limiting](https://developer.billabex.com/en/guides/rate-limiting/): Understand the OAuth token rate-limiting model, why it is designed this way, and what your integration should implement.
- [Audit Journal](https://developer.billabex.com/en/guides/audit-journal/): Read who did what in an organization: one entry per successful command, filterable by account, actor and free text.
- [Pagination & Filtering](https://developer.billabex.com/en/guides/pagination/): Understand Billabex cursor pagination and the filters parameter, and what your integration should implement.
- [Account Sources](https://developer.billabex.com/en/guides/sources/): Learn how to link and unlink external data sources to accounts via the API.
- [Original invoice of a credit note](https://developer.billabex.com/en/guides/credit-note-original-invoice/): Link a credit note to the invoice it came from, without creating an allocation or moving any balance.
- [Upsert Operations](https://developer.billabex.com/en/guides/upsert/): Create or update resources in a single idempotent request using upsert endpoints.
- [Contacts](https://developer.billabex.com/en/guides/contacts/): Manage customer contacts associated with accounts.
- [File Uploads](https://developer.billabex.com/en/guides/file-uploads/): Upload invoice, credit note and email attachment files using binary or base64 encoding.
- [Account Tasks & Interactions](https://developer.billabex.com/en/guides/account-tasks/): Respond to Billabex agent account tasks: search, list, get, cancel, set aside, and add user interactions.
- [Send an SMS or a letter](https://developer.billabex.com/en/guides/outgoing-messages/): Preview, price, and send a paid follow-up without creating a duplicate.
- [Read the aging balance](https://developer.billabex.com/en/guides/aging-balance/): Analyse net outstanding amounts by age bucket, currency, and customer account.

## Guides (français)

- [Démarrage](https://developer.billabex.com/fr/guides/demarrage/): Introduction rapide à l'API Billabex : s'authentifier et faire son premier appel.
- [Authentification OAuth Billabex](https://developer.billabex.com/fr/guides/oauth/): Flux d'autorisation OAuth 2.1 par code avec PKCE, et OpenID Connect en option.
- [Scopes OAuth](https://developer.billabex.com/fr/guides/scopes/): Comprendre les scopes disponibles, comment l'accès est contrôlé, et comment demander les bonnes permissions pour votre intégration.
- [Erreurs JSON](https://developer.billabex.com/fr/guides/erreurs/): Interpréter les erreurs de l'API Billabex par leur code, suivre la piste de résolution, et ne réessayer que lorsque la réponse l'autorise.
- [Idempotence](https://developer.billabex.com/fr/guides/idempotence/): Rendre une écriture rejouable sans risque : envoyez un Idempotency-Key et la seconde tentative rejoue la première réponse au lieu de créer un second enregistrement.
- [Serveur MCP Billabex](https://developer.billabex.com/fr/guides/mcp/): Connecter un outil IA à Billabex par le Model Context Protocol (MCP), avec OAuth 2.1.
- [Préférences de notification](https://developer.billabex.com/fr/guides/preferences-de-notification/): Lire et modifier les préférences de notification de l'utilisateur authentifié.
- [Limites de débit](https://developer.billabex.com/fr/guides/limites-de-debit/): Comprendre le modèle de limitation par jeton OAuth, pourquoi il est conçu ainsi, et ce que votre intégration doit implémenter.
- [Journal d'audit](https://developer.billabex.com/fr/guides/journal-d-audit/): Lire qui a fait quoi dans une organisation : une entrée par commande réussie, filtrable par compte, par acteur et par texte libre.
- [Pagination et filtres](https://developer.billabex.com/fr/guides/pagination/): Comprendre la pagination par curseur de Billabex et le paramètre filters, et ce que votre intégration doit implémenter.
- [Sources de compte](https://developer.billabex.com/fr/guides/sources-de-compte/): Relier et délier une source de données externe à un compte, par API.
- [Facture d’origine d’un avoir](https://developer.billabex.com/fr/guides/facture-d-origine-d-un-avoir/): Relier un avoir à sa facture d’origine sans créer d’allocation ni modifier les soldes.
- [Opérations upsert](https://developer.billabex.com/fr/guides/upsert/): Créer ou mettre à jour une ressource en une seule requête idempotente.
- [Contacts](https://developer.billabex.com/fr/guides/contacts/): Gérer les contacts clients rattachés à un compte.
- [Envoi de fichiers](https://developer.billabex.com/fr/guides/televersement-de-fichiers/): Envoyer les fichiers de factures, d'avoirs et de pièces jointes d'email, en binaire ou en base64.
- [Tâches de compte et interactions](https://developer.billabex.com/fr/guides/taches-de-compte/): Répondre aux tâches ouvertes par l'agent Billabex : rechercher, lister, consulter, annuler, mettre de côté, et ajouter une interaction.
- [Envoyer un SMS ou un courrier](https://developer.billabex.com/fr/guides/messages-sortants/): Prévisualiser, chiffrer et envoyer une relance payante sans créer de doublon.
- [Lire la balance âgée](https://developer.billabex.com/fr/guides/balance-agee/): Analyser les encours nets par ancienneté, devise et compte client.