Guía de migración v2025-01-01 → v2025-10-13

Todo lo que necesitas para actualizar tu código.

Esta guía te ayuda a actualizar de X-B2B-API-Version: 2025-01-01 a X-B2B-API-Version: 2025-10-13, centrándose en lo que necesitas cambiar, no solo en lo que ha cambiado.

Changelog Para la lista completa de adiciones y correcciones, consulta el changelog de v2025-10-13.

Actualización de tu integración

Actualizar la URL base: Cambia la URL base de tu API de app.b2brouter.net o app-staging.b2brouter.net a api.b2brouter.net o api-staging.b2brouter.net respectivamente.
Añadir cabecera de versión: Incluye la cabecera X-B2B-API-Version: 2025-10-13 en todas las solicitudes, o configura la versión predeterminada en los ajustes de clave de API de tu grupo.
Eliminar extensiones de formato: Elimina las extensiones .json o .xml de todas las rutas de endpoint. Todas las respuestas son ahora JSON por defecto.
Actualizar segmentos de ruta:

Reemplaza /projects/ por /accounts/ en todas las rutas
Reemplaza /clients/ por /contacts/ en todas las rutas
Elimina el prefijo /users/ de los endpoints de listas de códigos
Elimina el prefijo /api/v1/ de los endpoints de directorio e informes fiscales

Actualizar el manejo de paginación: Actualiza tu código para leer los datos de paginación del objeto meta en lugar de las propiedades de nivel raíz:

Antiguo (v2025-01-01)
Nuevo (v2025-10-13)

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

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

Actualizar nombres de propiedades: Reemplaza todas las referencias a client por contact en el código de manejo de solicitudes y respuestas:

Antiguo (v2025-01-01)
Nuevo (v2025-10-13)

// Cuerpo de la solicitud
{
  "invoice": {
    "client_id": 123,
    "client": {
      "name": "Client Name",
      "taxcode": "9920:ESD29766391"
    }
  }
}

// Cuerpo de la respuesta
{
  "invoice": {
    "id": 123,
    "client": { ... }
  }
}

// Cuerpo de la solicitud
{
  "invoice": {
    "contact_id": 123,
    "contact": {
      "name": "Contact Name",
      "tin_scheme": "9920",
      "tin_value": "ESD29766391"
    }
  }
}

// Cuerpo de la respuesta
{
  "invoice": {
    "id": 123,
    "contact": { ... }
  }
}

Consolidar listados de facturas: Reemplaza los endpoints separados de listado de facturas con el endpoint consolidado /accounts/{account}/invoices usando el parámetro type:

Para facturas recibidas: GET /accounts/{account}/invoices?type=ReceivedInvoice
Para autofacturas: GET /accounts/{account}/invoices?type=IssuedSelfInvoice
Para facturas simplificadas: GET /accounts/{account}/invoices?type=IssuedSimplifiedInvoice

Actualizar informes fiscales: Reemplaza los endpoints de informes fiscales obsoletos por los nuevos endpoints consolidados en /accounts/{account}/tax_reports y /tax_reports/{id}. Consulta la nueva API de informes fiscales para más detalles.
Manejar respuestas completas: Actualiza tu código para manejar representaciones completas de recursos devueltas por las operaciones PUT, DELETE y POST en lugar de respuestas 204 vacías.
Eliminar soporte XML: Si tu integración dependía de respuestas XML, convierte tu código para manejar únicamente respuestas JSON.
Actualizar atributos de factura obsoletos: Reemplaza los atributos de factura obsoletos por sus alternativas estandarizadas:

Antiguo (v2025-01-01)
Nuevo (v2025-10-13)

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

{
  "invoice": {
    "customer_contact_person": "John Doe",
    // state eliminado - usar POST /invoices/{id}/mark_as en su lugar
    "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"
  }
}

Actualizar atributos de contacto/cliente: Reemplaza los atributos de contacto obsoletos por sus alternativas estandarizadas:

Antiguo (v2025-01-01)
Nuevo (v2025-10-13)

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

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

Actualizar códigos de enrutamiento: Los campos de código de enrutamiento (cin1_value, cin1_scheme, …, cin5_value, cin5_scheme) ya no se aceptan como atributos de contacto de nivel superior. Deben enviarse dentro de un contenedor routing_codes:

Antiguo (v2025-01-01)
Nuevo (v2025-10-13)

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

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

En las respuestas, los códigos de enrutamiento también se devuelven dentro del objeto routing_codes.

Actualizar cambios de estado de factura: Reemplaza las actualizaciones directas del atributo state con el endpoint mark_as:

Antiguo (v2025-01-01)
Nuevo (v2025-10-13)

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

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

Prueba de tu migración

Recomendamos probar exhaustivamente tu integración en el entorno de staging (api-staging.b2brouter.net) antes de desplegar en producción. La cabecera X-B2B-API-Version te permite probar la nueva versión sin afectar a tu integración actual.