Primers passos

Configurar les dades fiscals dels comptes [OBLIGATORI]

Des de l’app, icona d’engranatge, o via API a través de l’endpoint /accounts. Crea tants comptes com necessitis al sandbox per fer proves.

eDocExchange: crea comptes per a les teves empreses a l’App amb l’enllaç manual a la secció Developers. Si ets reseller, pots automatitzar l’aprovisionament d’eDocExchange per oferir un servei més complet als teus clients finals.
eDocSync: crea comptes d’usuari via API amb 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}"
    }
  }'

Quan crees un compte via API, llegeix l’id de la resposta i desa’l al teu entorn per a futures peticions d’aquella empresa.

Guia de comptes: https://developer.b2brouter.net/docs/accounts_guide
Configuració de la teva empresa: https://www.b2brouter.net/docs/#/en/set-up/setting-up-your-company
Guia d’esquemes: https://developer.b2brouter.net/docs/schemes_guide#/
Referència API: https://developer.b2brouter.net/reference/create-account#/

Activar transports [Recomanat: b2brouter, mail i peppol] [Opcional] [OBLIGATORI per a casos Peppol BE]

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_SCHEME}",
      "pin_value": "{YOUR_IDENTIFICATION_NUMBER}"
    }
  }'

Guia de transports: https://developer.b2brouter.net/docs/transports_guide/
Referència API: https://developer.b2brouter.net/reference/create-transport/

Activar Tax Report [OBLIGATORI en casos ES i IT]

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"
    }
  }'

Guia de tax reports: https://developer.b2brouter.net/docs/tax_report_settings_guide
Referència API: https://developer.b2brouter.net/reference/create-tax-report-setting#/

Llistar comptes per recuperar l’`ACCOUNT_ID` [Opcional]

Si encara no tens els IDs del teu grup d’integració, aquesta és la manera més ràpida de llistar-los. També pots copiar l’ID d’un compte des de la pestanya App → Developers.

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'

Referència API: https://developer.b2brouter.net/reference/get-accounts#/

Pas següent: segueix la guia del flux d’enviament end-to-end per crear contactes, crear o importar factures, enviar-les i recuperar o descarregar els documents finals.

Cercar contactes [Opcional]

Si el trobes, pots saltar directament al pas 4) recuperant l’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'

Referència API: https://developer.b2brouter.net/reference/get-contacts#/

Cercar al directori [Opcional]

Si existeix, pots fer servir les dades per crear el contacte.

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'

Guia del directori: https://developer.b2brouter.net/docs/directory#/
Referència API: https://developer.b2brouter.net/reference/lookup-directory-by-country#/

Crear contacte [Opcional]

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": "john.doe@example.com",
      "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
    }
  }'

Si no tens clar quin tin_scheme, transport_type_code o document_type_code cal utilitzar, recorda que pots fer servir els endpoints de Code Lists.

Guia d’esquemes: https://developer.b2brouter.net/docs/schemes_guide#/
Referència API: https://developer.b2brouter.net/reference/create-contact#/
Referència API tipus de transport: https://developer.b2brouter.net/reference/get-transport-types#/
Referència API tipus de document: https://developer.b2brouter.net/reference/get-document-types#/
Referència API esquemes: https://developer.b2brouter.net/reference/get-schemes#/

Les factures que crees o importes després no sobreescriuen les dades d’aquest contacte, tret que la crida porti update_contact=true. Consulta l’apartat 2.3 de la guia Enviar factures (d’extrem a extrem).

Crear i enviar una factura simple [OBLIGATORI]

Recorda que, si no vols gestionar contactes a B2Brouter, en lloc d’utilitzar contact_id, pots incrustar un objecte contact complet dins de invoice a la mateixa petició POST /invoices; en aquest cas, hauràs de proporcionar les dades del contacte a cada factura. Si el teu sistema ja genera un XML de factura electrònica reconegut, la integració més simple és importar-lo directament. Ara bé, si dones servei a clients de diversos països, JSON acostuma a ser més portable perquè alguns formats tenen camps específics de país. Utilitza GET /document_types per comprovar els tipus de document disponibles.

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"
    }
  }'

Enviar factures via JSON, exemple Peppol: https://developer.b2brouter.net/docs/send_an_invoice_through_peppol_via_json_payload#/
Guia de càlcul de factures: https://developer.b2brouter.net/docs/invoice_calculation#/
Guia de mètodes de pagament: https://developer.b2brouter.net/docs/payment_method_guide#/
Referència API: https://developer.b2brouter.net/reference/create-invoice#/
Referència API import XML: https://developer.b2brouter.net/reference/import-invoice#/

Recuperar les dades de la factura emesa [OPCIONAL]

Un cop enviada, pots recuperar l’invoice.id de la resposta i fer un GET amb tota la informació. Si tens Tax Report activat, casos ES o IT, també pots recuperar el tax_report_id per veure’n tots els detalls. Recorda que pots configurar Webhooks per als canvis d’estat.

Llistar factures

Per obtenir les factures més recents en 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'

Obtenir una factura

Per recuperar una factura específica en JSON:

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}' \
  --header 'accept: application/json'

Obtenir una factura amb un tipus de document específic

Si necessites la factura electrònica renderitzada en un format concret:

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}' \
  --header 'accept: application/json'

Fent un GET sobre el download_legal_url proporcionat al payload de la factura, pots descarregar el document legal lliurat a l’usuari final per reenviar-lo o arxivar-lo al teu sistema. Alternativament, pots cridar directament GET /invoices/{id}/as/legal per obtenir el mateix document legal arxivat sense haver d’obtenir primer download_legal_url del payload de la factura; això no genera cap transacció facturable — consulta Descarregar factures i Transaction: View_as.

Obtenir un Tax Report [CASOS ES i IT]

Obtén tots els detalls d’una declaració, incloent-hi l’enllaç i el 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'

Enviar factures, end-to-end: https://developer.b2brouter.net/docs/send_invoices_end_to_end#/

Passar a producció

Registra’t, si encara no ho has fet, a https://app.b2brouter.net/en/register
Un cop dins, ves a Subscription i subscriu-te a eDocExchange mensual segons el volum aproximat de transaccions.
Canvis tècnics mínims per migrar:
- Des de sandbox: canvia la clau test_ per una clau de producció. La base URL, https://api.b2brouter.net, es manté igual.
- Des de staging: canvia el domini de api-staging.b2brouter.net a api.b2brouter.net i fes servir la clau API de producció.
- Actualitza l’{ACCOUNT_ID}, si difereix entre entorns.
- El payload i el comportament funcional són els mateixos a tots els entorns.

No cal tenir tota la integració acabada: pots passar a producció amb el flux bàsic i continuar desenvolupant amb el suport dels tècnics de B2Brouter.

Bones pràctiques

Si gestiones múltiples empreses i necessiten accés a B2Brouter, separa-les en grups per privacitat.
No enviïs factures reals des de sandbox o staging via email o b2brouter a destinataris reals.
Evita utilitzar NIF/Tax IDs reals de tercers amb qui no t’integraràs.
Simplifica el procés: busca un flux net i global.
Prioritza JSON. Encara que B2Brouter pugui convertir a la majoria de formats globals, treballar amb el nostre format base facilita facturar globalment sense problemes legals.

Guies recomanades per començar

Comptes: https://developer.b2brouter.net/docs/accounts_guide
Directori: https://developer.b2brouter.net/docs/directory
Transports: https://developer.b2brouter.net/docs/transports_guide
Tax report settings: https://developer.b2brouter.net/docs/tax_report_settings_guide
Esquemes / identificadors: https://developer.b2brouter.net/docs/schemes_guide#/
Pagaments: https://developer.b2brouter.net/docs/payment_method_guide#/

Manual d’usuari

Per als usuaris que necessiten utilitzar l’aplicació web, la documentació de la plataforma és aquí:

https://www.b2brouter.net/docs/#/en/README

Comencem!

Recorda que durant tot el procés estarem encantats d’ajudar-te a través de Support.

Bona sort amb el teu procés d’integració!