# Billabex Developer Portal

> Official documentation for integrating with the Billabex public API.

## API

- [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/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.
- [Complete documentation](https://developer.billabex.com/llms-full.txt): All developer guides in one text file.

## When to use Billabex

- Use Billabex to synchronize customer accounts, contacts, invoices, credit notes, and payment status from another business system.
- Use Billabex to inspect outstanding receivables, payment follow-ups, communications, and tasks that need user input.
- Use the REST API for deterministic application workflows. Use the MCP server when an AI assistant must inspect context and call Billabex tools interactively.
- Do not use Billabex as a payment processor or as the accounting system of record.

## How agents should call Billabex

1. Read the OpenAPI specification or connect to the MCP endpoint without credentials to discover the authentication challenge.
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.

## Trust

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

## Guides

- [Getting Started](https://developer.billabex.com/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/guides/oauth/): OAuth 2.1 Authorization Code flow with PKCE and optional OpenID Connect for Billabex.
- [OAuth Scopes](https://developer.billabex.com/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/guides/errors/): Parse Billabex API errors by code, use the resolution hint, and retry only when the response allows it.
- [Billabex MCP Server](https://developer.billabex.com/guides/mcp/): Connect AI tools to Billabex using the Model Context Protocol (MCP) with OAuth 2.1.
- [Notification Preferences](https://developer.billabex.com/guides/notification-preferences/): Read and update the authenticated user notification preferences.
- [Rate Limiting](https://developer.billabex.com/guides/rate-limiting/): Understand the OAuth token rate-limiting model, why it is designed this way, and what your integration should implement.
- [Pagination & Filtering](https://developer.billabex.com/guides/pagination/): Understand Billabex cursor pagination and the filters parameter, and what your integration should implement.
- [Account Sources](https://developer.billabex.com/guides/sources/): Learn how to link and unlink external data sources to accounts via the API.
- [Upsert Operations](https://developer.billabex.com/guides/upsert/): Create or update resources in a single idempotent request using upsert endpoints.
- [Contacts](https://developer.billabex.com/guides/contacts/): Manage customer contacts associated with accounts.
- [File Uploads](https://developer.billabex.com/guides/file-uploads/): Upload invoice and credit note documents using binary or base64 encoding.
- [Account Tasks & Interactions](https://developer.billabex.com/guides/account-tasks/): Respond to Billabex agent account tasks: search, list, get, cancel, and add user interactions.
- [Envoyer un SMS ou un courrier](https://developer.billabex.com/guides/outgoing-messages/): Prévisualiser, chiffrer et envoyer une relance payante sans créer de doublon.