Guides
Start typing to search…

Getting Started: Setting Up Your Integration

First steps Flow (basic configuration)

1) Configure the tax data for the accounts [REQUIRED]

From the app (gear icon) or via API through the /accounts endpoint. Create as many accounts as you need in staging for testing.

  • eDocExchange: create accounts for your companies in the App (manual linking in the “Developers” section). If you are a reseller, you can automate eDocExchange provisioning to offer a more complete service to your end customers.
  • eDocSync: create user accounts via API (POST /accounts).
curl --request POST      --url https://api-staging.b2brouter.net/accounts/      --header 'X-B2B-API-Key: {YOUR_API_KEY}'  --header 'X-B2B-API-Version: {YOUR_API_VERSION}'      --header 'accept: application/json'      --header 'content-type: application/json'      --data '
{
  "account": {
    "country": "{COUNTRY_CODE}",
    "tin_value": "{YOUR_TAX_IDENTIFICATION_NUMBER}",
    "tin_scheme": "{YOUR_TAX_IDENTIFICATION_SCHEME}",
    "name": "{ENTERPRISE_NAME}",
    "address": "{YOUR_STREET}",
    "city": "{YOUR_CITY}",
    "postalcode": "00000",
    "email": "{MAIN_EMAIL}"
  }
}

When you create an account via API, read the id from the response and persist it in your environment for future requests for that company.

2) Activate transports [Recommended: b2brouter, mail & peppol] [Optional] [REQUIRED Peppol BE cases]

curl --request POST \     --url https://api-staging.b2brouter.net/accounts/{ACCOUNT_ID}/transports \     --header 'X-B2B-API-Key: {YOUR_API_KEY}'  \ --header 'X-B2B-API-Version: {YOUR_API_VERSION}'\    --header 'accept: application/json' \     --header 'content-type: application/json' \     --data '
{
  "transport": {
    "code": "peppol",
    "enabled": true,
    "reception": true,
    "standard_documents": true,
    "invoice": true,
    "credit_note": true,
    "application_response": true,
    "pin_scheme": "{YOUR_IDENTIFICATION_NUMBER}",
    "pin_value": "{YOUR_IDENTIFICATION_SCHEME}"
  }
}
'

3) Activate Tax Report [REQUIRED ES & IT cases]

curl --request POST      --url https://api-staging.b2brouter.net/accounts/{ACCOUNT_ID}/tax_report_settings      --header 'X-B2B-API-Key: {YOUR_API_KEY}'    --header 'X-B2B-API-Version: {YOUR_API_VERSION}'      --header 'accept: application/json'      --header 'content-type: application/json'      --data '
{
  "tax_report_setting": {
    "code": "verifactu",
    "auto_generate": true,
    "auto_send": true,
    "enabled": true,
    "reason_vat_exempt": "E1",
    "special_regime_key": "01",
    "special_regime_key_igic": "01",
    "reason_no_subject": "N1",
    "credit_note_code": "R1"
  }
}
'

4) List accounts to retrieve the ACCOUNT_ID [Optional]

If you don’t already have the IDs for your integration group, this is the fastest way to list them. You can also copy an account’s ID from the App → Developers tab.

curl --request GET      --url 'https://api-staging.b2brouter.net/accounts?offset=0&limit=25'      --header 'X-B2B-API-Key: {YOUR_API_KEY}'      --header 'X-B2B-API-Version: {YOUR_API_VERSION}'      --header 'accept: application/json'

Basic flow (End-to-End)

1) Lookup Contacts [Optional]

If found, you can jump straight to step 4) by retrieving the id.

curl --request GET      --url 'https://api-staging.b2brouter.net/accounts/{ACCOUNT_ID}/contacts?offset=0&limit=25&name=B2Brouter%20Global%20S.L.'      --header 'X-B2B-API-Key: {YOUR_API_KEY}'       --header 'X-B2B-API-Version: {YOUR_API_VERSION}'      --header 'accept: application/json'

2) Lookup in the directory [Optional]

If it exists, you can use the data to create your contact.

curl --request GET      --url https://api-staging.b2brouter.net/directory/es/ESB63276174      --header 'X-B2B-API-Key: {YOUR_API_KEY}'       --header 'X-B2B-API-Version: {YOUR_API_VERSION}'      --header 'accept: application/json'

3) Create contact [Optional]

curl --request POST      --url https://api-staging.b2brouter.net/accounts/{ACCOUNT_ID}/contacts      --header 'X-B2B-API-Key: {YOUR_API_KEY}'       --header 'X-B2B-API-Version: {YOUR_API_VERSION}'      --header 'accept: application/json'      --header 'content-type: application/json'      --data '
{
  "contact": {
    "language": "en",
    "is_client": true,
    "is_provider": true,
    "public_sector": false,
    "name": "B2Brouter Global S.L.",
    "tin_value": "ESB63276174",
    "tin_scheme": "9920",
    "country": "es",
    "email": "[email protected]",
    "address": "Avda. Diagonal, 433 1º1ª",
    "postalcode": "08036",
    "province": "Barcelona",
    "city": "Barcelona",
    "transport_type_code": "b2brouter",
    "document_type_code": "xml.facturae.3.2.2",
    "payment_method": 1
  }
}
'

If you are unsure which tin_scheme, transport_type_code or document_type_code to use, remember to use the Code Lists endpoints.

4) Create and send a simple invoice [REQUIRED]

Remember that if you don’t want to manage contacts in B2Brouter, Instead of using contact_id, you can embed a full contact object inside the invoice in the same POST /invoices request; in that case, provide the contact details on every invoice. If your system already generates a recognized e-invoice XML, the simplest integration is to import it directly. However, if you serve customers in multiple countries, JSON is usually more portable because some formats have country-specific fields. Use GET /document_types to check available document types.

curl --request POST      --url https://api-staging.b2brouter.net/accounts/{ACCOUNT_ID}/invoices      --header 'X-B2B-API-Key: {YOUR_API_KEY}'       --header 'X-B2B-API-Version: {YOUR_API_VERSION}'      --header 'content-type: application/json'      --data '
{
  "send_after_import": true,
  "invoice": {
    "type": "IssuedInvoice",
    "bank_account": {
      "type": "iban"
    },
    "terms": "custom",
    "invoice_lines_attributes": [
      {
        "unit": 1,
        "quantity": 1,
        "description": "Example Service",
        "price": 10,
        "taxes_attributes": [
          {
            "name": "VAT",
            "category": "S",
            "percent": 21
          }
        ]
      }
    ],
    "apply_taxes_to_charge": false,
    "charge_is_reimbursable_expense": false,
    "number": "123456",
    "contact_id": {CONTACT.ID},
    "date": "2025-09-24",
    "due_date": "2025-10-24"
  }
}
'

5) Retrieve data of the issued invoice [OPTIONAL]

Once sent, you can retrieve the invoice.id from the response and perform a GET with all the information. If you have Tax Report enabled (ES/IT), you can also retrieve the tax_report_id to see all the details. Remember that you can configure Webhooks for state changes.

5.1) List invoices

To fetch the most recent invoices as JSON:

curl --request GET \
     --url 'https://api-staging.b2brouter.net/accounts/{ACCOUNT_ID}/invoices?offset=0&limit=25' \
     --header 'X-B2B-API-Key: {YOUR_API_KEY}' \
     --header 'X-B2B-API-Version: {YOUR_API_VERSION}' \
     --header 'accept: application/json'

5.2) Get an invoice

To retrieve a specific invoice as JSON (most fields are already returned in the creation response):

curl --request GET \
     --url https://api-staging.b2brouter.net/invoices/{INVOICE_ID}?include=lines \
     --header 'X-B2B-API-Key: {YOUR_API_KEY}'
     --header 'X-B2B-API-Version: {YOUR_API_VERSION}'

5.3) Get an invoice with a specific document type

If you need the rendered electronic invoice in a specific format:

curl --request GET \
     --url https://api-staging.b2brouter.net/invoices/{INVOICE_ID}/as/{document_type_code} \
     --header 'X-B2B-API-Key: {YOUR_API_KEY}'
     --header 'X-B2B-API-Version: {YOUR_API_VERSION}'

By performing a GET on the "download_legal_url" provided in the invoice payload, you can download the legal document delivered to the end user (for re-sending or archiving on your si

5.4) Get a Tax Report [ES & IT CASES]

Fetch all the details of a declaration, including the link and QR:

curl --request GET \
     --url https://api-staging.b2brouter.net/tax_reports/{TAX_REPORT_ID} \
     --header 'X-B2B-API-Key: {YOUR_API_KEY}' \
     --header 'X-B2B-API-Version: {YOUR_API_VERSION}'
     --header 'accept: application/json'

Move to production

  1. Register (if you haven’t yet) at https://app.b2brouter.net/en/register

  2. Once logged in, go to Subscription and subscribe to eDocExchange monthly according to the approximate volume of transactions.

  3. Minimal technical changes to migrate:

    • Change the domain from staging to production.
    • Use the new API key.
    • Update the {ACCOUNT_ID} (if they differ).
    • The payload and functional behavior are the same across environments.

You don’t need to have the whole integration finished: you can go to production with the basic flow and you will still have staging available to continue developing with the support of B2Brouter technicians.

Best practices

  • If you manage multiple companies and they need access to B2Brouter, separate them into groups for privacy. (User management and ownership from the account settings in the app).
  • Do not send real invoices from staging via email or b2brouter to real recipients: create test accounts and contacts (you can do internal sends to review reception with a test email).
  • Avoid using real NIF/Tax IDs of third parties you won’t integrate.
  • Simplify the process: aim for a clean, global flow; avoid unnecessary local rules if the transport and format already solve them.
  • Prioritize JSON. Although B2Brouter can convert to the vast majority of global formats, working with our base format lets you invoice globally in all kinds of formats without legal issues.

Recommended guides to get started

User's Manual

For users who need to use the Web Application, our platform documentation is available here:

https://www.b2brouter.net/v2025-10-13/docs/#/en/README

Let's start!

Remember that throughout the whole process we will be happy to help you through Support.

Good luck with your integration process!

Updated 3 days ago