Guia de migració v2025-01-01 → v2025-10-13

Aquesta guia t’ajuda a actualitzar de X-B2B-API-Version: 2025-01-01 a X-B2B-API-Version: 2025-10-13, centrant-se en el que has de canviar, no només en el que ha canviat.

Changelog Per al llistat complet d'afegits i correccions, consulta el changelog de v2025-10-13.

Actualitzar la teva integració

1. Actualitza la Base URL: canvia la base URL de l’API de app.b2brouter.net o app-staging.b2brouter.net a api.b2brouter.net o api-staging.b2brouter.net.
2. Afegeix la capçalera de versió: inclou X-B2B-API-Version: 2025-10-13 a totes les peticions, o configura la versió per defecte a la configuració de l’API Key del teu grup.
3. Elimina extensions de format: elimina .json o .xml de totes les rutes d’endpoint. Totes les respostes ara són JSON per defecte.
4. Actualitza segments de ruta:

• Substitueix /projects/ per /accounts/
• Substitueix /clients/ per /contacts/
• Elimina el prefix /users/ dels endpoints de code list
• Elimina el prefix /api/v1/ dels endpoints de directori i tax report

5. Actualitza el tractament de paginació: llegeix les dades de paginació des de meta en lloc de propietats d’arrel:

Antic (v2025-01-01)

const totalCount = response.total_count;
const offset = response.offset;
const limit = response.limit;

Nou (v2025-10-13)

const totalCount = response.meta.total_count;
const offset = response.meta.offset;
const limit = response.meta.limit;

6. Actualitza noms de propietats: substitueix totes les referències a client per contact tant en peticions com en respostes:

Antic (v2025-01-01)

// cos de petició
{
  "invoice": {
    "client_id": 123,
    "client": {
      "name": "Client Name",
      "taxcode": "9920:ESD29766391"
    }
  }
}

// cos de resposta
{
  "invoice": {
    "id": 123,
    "client": { ... }
  }
}

Nou (v2025-10-13)

// cos de petició
{
  "invoice": {
    "contact_id": 123,
    "contact": {
      "name": "Contact Name",
      "tin_scheme": "9920",
      "tin_value": "ESD29766391"
    }
  }
}

// cos de resposta
{
  "invoice": {
    "id": 123,
    "contact": { ... }
  }
}

7. Consolida els llistats de factures: substitueix endpoints separats per l’endpoint unificat /accounts/{account}/invoices amb el paràmetre type:

• Factures rebudes: GET /accounts/{account}/invoices?type=ReceivedInvoice
• Autofactures: GET /accounts/{account}/invoices?type=IssuedSelfInvoice
• Factures simplificades: GET /accounts/{account}/invoices?type=IssuedSimplifiedInvoice

8. Actualitza tax reports: substitueix els endpoints antics per /accounts/{account}/tax_reports i /tax_reports/{id}. Consulta la New Tax Reports API.
9. Gestiona respostes completes: adapta el teu codi perquè PUT, DELETE i POST retornen representacions completes del recurs i no respostes buides 204.
10. Elimina suport XML: si la teva integració depenia de respostes XML, converteix-la perquè treballi només amb JSON.
11. Actualitza atributs de factura obsolets:

Antic (v2025-01-01)

{
  "invoice": {
    "contact_person": "John Doe",
    "state": "accepted",
    "customer_party_identification": "12345",
    "accounting_cost": "DEPT-001",
    "iban": "ES6000000000000000000000",
    "bic": "ABCDESMMXXX",
    "num_contracte": "CONTRACT-2024",
    "organ_gestor": "ORG-001",
    "oficina_comptable": "OFF-001"
  }
}

Nou (v2025-10-13)

{
  "invoice": {
    "customer_contact_person": "John Doe",
    "contact": {
      "party_identification": "12345"
    },
    "buyer_accounting_reference": "DEPT-001",
    "bank_account": {
      "iban": "ES6000000000000000000000",
      "bic": "ABCDESMMXXX"
    },
    "contract_number": "CONTRACT-2024",
    "managing_unit": "ORG-001",
    "accounting_unit": "OFF-001"
  }
}

12. Actualitza atributs de contacte/client obsolets:

Antic (v2025-01-01)

{
  "contact": {
    "old_channel": "peppol",
    "taxcode": "9920:ESD29766391",
    "contact": "John Doe",
    "bank_account": "ES6000000000000000000000",
    "company_identifier": "A12345678",
    "transport_type": "peppol",
    "document_type": "xml.ubl.invoice.bis3",
    "posta_elettronica_certificata": "pec@example.it",
    "codice_destinatario": "ABC1234"
  }
}

Nou (v2025-10-13)

{
  "contact": {
    "transport_type_code": "peppol",
    "tin_scheme": "9920",
    "tin_value": "ESD29766391",
    "contact_person": "John Doe",
    "bank_account_number": "ES6000000000000000000000",
    "cin_value": "A12345678",
    "document_type_code": "xml.ubl.invoice.bis3",
    "certified_email": "pec@example.it",
    "recipient_code": "ABC1234"
  }
}

13. Actualitza routing codes: els camps cin1_value, cin1_scheme … cin5_value, cin5_scheme ja no s’accepten com a atributs top-level del contacte. S’han d’enviar dins d’un objecte routing_codes:

Antic (v2025-01-01)

{
  "contact": {
    "name": "Ajuntament de Girona",
    "cin1_value": "L01170792",
    "cin1_scheme": "8014",
    "cin2_value": "L01170792",
    "cin2_scheme": "8014",
    "cin3_value": "L01170792",
    "cin3_scheme": "8014"
  }
}

Nou (v2025-10-13)

{
  "contact": {
    "name": "Ajuntament de Girona",
    "routing_codes": {
      "cin1_value": "L01170792",
      "cin1_scheme": "8014",
      "cin2_value": "L01170792",
      "cin2_scheme": "8014",
      "cin3_value": "L01170792",
      "cin3_scheme": "8014"
    }
  }
}

Les respostes també retornen aquests routing codes dins de l’objecte routing_codes.

14. Actualitza els canvis d’estat de factura: substitueix les actualitzacions directes del camp state per l’endpoint mark_as:

Antic (v2025-01-01)

PUT /invoices/{id}.json
{
  "invoice": {
    "state": "accepted"
  }
}

Nou (v2025-10-13)

POST /invoices/{id}/mark_as
{
  "state": "accepted"
}

Provar la migració

Recomanem provar a fons la integració a l’entorn staging (api-staging.b2brouter.net) abans de desplegar a producció. La capçalera X-B2B-API-Version et permet provar la nova versió sense afectar la integració actual.