Configure the B2Brouter API connection

B2Brouter API lets you integrate your ERP, ecommerce platform or custom application to create, query and send documents automatically.

This guide covers the basics to get started: where to find the account_id, how to generate an API key, the difference between staging and production, and how to make your first request.

For the complete technical detail of each endpoint, also see the developer documentation.

Before you start

• You need a B2Brouter account.
• You must have access to the Developers tab.
• For testing, start with the sandbox — it is the recommended environment for most tests. Use the full staging environment only for large-scale integrations or broad end-to-end tests.

Where to find the account_id

When you work with the API, many operations are performed against a specific account and require its account_id.

You can find it in two ways:

1. In B2Brouter, go to the Developers tab.
2. Click View IDs for each account or the edit group icon next to your group name.
3. In the account list, you will see the ID for each account.

You can also retrieve it through the API by listing the accounts in your group. In the response, pay special attention to the id and identifier fields.

How to generate an API key

1. Log in to your B2Brouter account.
2. Go to the Developers tab.
3. Open API Keys.
4. Create a new key or copy an existing one.
5. Store it in a safe place.

API keys are different for each environment. A production key does not work in staging, and a staging key does not work in production.

Difference between staging and production

B2Brouter has two main environments:

• Production: https://api.b2brouter.net
• Staging: https://api-staging.b2brouter.net

Recommendations:

• Use the sandbox for most tests and initial integration work.
• Use staging only for large-scale or broad end-to-end integration tests.
• Use production only after you have fully validated the integration flow.
• Keep credentials and configuration separate for each environment.

If you are working with an older API version (2025-01-01), some requests may still use app.b2brouter.net, but for newer versions the recommended base URL is api.b2brouter.net or api-staging.b2brouter.net.

Authentication

B2Brouter API authenticates requests with the following header:

• X-B2B-API-Key

Optionally, you can also send:

• X-B2B-API-Version

B2Brouter does not use Authorization: Bearer ... as the main authentication mechanism for this API. The correct way to authenticate is with X-B2B-API-Key.

First request with cURL

A good first test is to list the accounts available in your group:

curl --request GET \
  --url https://api-staging.b2brouter.net/accounts \
  --header 'X-B2B-API-Key: {YOUR_API_KEY}' \
  --header 'X-B2B-API-Version: 2025-10-13' \
  --header 'accept: application/json'

If the request is successful, you will get a JSON response with the available accounts. From there you can already use the account_id in requests such as:

curl --request GET \
  --url https://api-staging.b2brouter.net/accounts/{ACCOUNT_ID}/invoices \
  --header 'X-B2B-API-Key: {YOUR_API_KEY}' \
  --header 'X-B2B-API-Version: 2025-10-13' \
  --header 'accept: application/json'

Which account_id to use

When calling endpoints such as /accounts/{ACCOUNT_ID}/..., you can use:

• The numeric account ID.
• Or the account identifier, if your group uses it that way.

If you are unsure, always validate it first with GET /accounts.

Handling transient errors

In a real integration, it is important to handle temporary errors without treating them as permanent failures.

Error 429 Too Many Requests

This error means you exceeded the request limit.

We recommend that you:

• Reduce the frequency of API calls.
• Retry with progressive waiting time using exponential backoff.
• Avoid very aggressive polling loops.

Error 503 Service Unavailable

This error indicates a temporary service issue.

We recommend that you:

• Try again after a few seconds.
• Apply a maximum number of retry attempts.
• Log the error so it can be tracked.

General retry recommendation

For temporary errors such as 429 or 503:

• Retry a maximum of 3 to 5 times.
• Wait a bit longer between each attempt.
• Do not retry forever.

Webhooks

If you need automatic notifications when the status of an invoice or document changes, the best option is to use webhooks instead of making constant API queries.

This guide does not cover webhook setup in detail, but it is the recommended approach to reduce polling and receive near real-time updates.

Recommended next step

Once you have validated:

1. The API key.
2. Access to the correct environment.
3. The account_id you will use.

You can continue with the specific endpoints required by your integration in the API documentation.