Configurar la conexión API de B2Brouter

Configurar la conexión API

La API de B2Brouter te permite integrar tu ERP, ecommerce o aplicación propia para crear, consultar y enviar documentos automáticamente.

En esta guía encontrarás la información básica para empezar: dónde localizar el account_id, cómo generar una clave API, qué diferencia hay entre producción y pruebas y cómo hacer tu primera petición.

Para el detalle técnico completo de los endpoints, consulta también la documentación para desarrolladores.

Antes de empezar

• Necesitas una cuenta de B2Brouter.
• Debes tener acceso a la pestaña Desarrolladores.
• Para hacer pruebas, empieza con el sandbox — es el entorno recomendado para la mayoría de pruebas. Utiliza el entorno de staging completo solo para integraciones a gran escala o pruebas exhaustivas de extremo a extremo.

Dónde encontrar el account_id

Cuando trabajas con la API, muchas operaciones se realizan sobre una cuenta concreta y necesitan su account_id.

Puedes encontrarlo de dos maneras:

1. Dentro de B2Brouter, ve a la pestaña Desarrolladores.
2. Haz clic en Ver los IDs de cada cuenta o en el icono de editar del grupo que aparece junto al nombre del grupo.
3. En la lista de cuentas verás el ID correspondiente a cada cuenta.

También puedes obtenerlo vía API haciendo una petición para listar las cuentas del grupo. En la respuesta, fíjate especialmente en los campos id e identifier.

Cómo generar una API key

1. Accede a tu cuenta de B2Brouter.
2. Ve a la pestaña Desarrolladores.
3. Entra en API Keys.
4. Crea una nueva clave o copia una ya existente.
5. Guárdala en un lugar seguro.

Las claves API son diferentes según el entorno. La clave de producción no sirve para staging, y la de staging no sirve para producción.

Diferencia entre staging y producción

B2Brouter tiene dos entornos principales:

• Producción: https://api.b2brouter.net
• Staging: https://api-staging.b2brouter.net

Recomendaciones:

• Utiliza el sandbox para la mayoría de pruebas y el trabajo de integración inicial.
• Utiliza staging solo para pruebas a gran escala o de extremo a extremo.
• Utiliza producción solo cuando ya hayas validado completamente el flujo.
• Mantén separadas las credenciales y configuraciones de cada entorno.

Si trabajas con una versión antigua de la API (2025-01-01), algunos accesos todavía pueden utilizar app.b2brouter.net, pero para las versiones nuevas la base recomendada es api.b2brouter.net o api-staging.b2brouter.net.

Autenticación

La API de B2Brouter se autentica con la cabecera:

• X-B2B-API-Key

Opcionalmente, también puedes enviar:

• X-B2B-API-Version

B2Brouter no utiliza Authorization: Bearer ... como mecanismo principal de autenticación para esta API. La forma correcta de autenticarse es con X-B2B-API-Key.

Primera petición con cURL

Una buena primera prueba es listar las cuentas disponibles de tu grupo:

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

Si la petición es correcta, obtendrás una respuesta JSON con las cuentas disponibles. A partir de ahí ya podrás utilizar el account_id en peticiones como, por ejemplo:

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

Qué account_id debes usar

Cuando hagas peticiones a endpoints como /accounts/{ACCOUNT_ID}/..., puedes utilizar:

• El ID numérico de la cuenta.
• O bien el identificador de la cuenta, si tu grupo lo utiliza así.

Si tienes dudas, empieza siempre validándolo con la petición GET /accounts.

Gestión de errores transitorios

En una integración real, es importante gestionar los errores temporales sin considerarlos un error definitivo.

Error 429 Too Many Requests

Este error indica que has superado el límite de peticiones.

Te recomendamos:

• Reducir la frecuencia de las llamadas.
• Hacer retry con espera progresiva (exponential backoff).
• Evitar bucles de consulta demasiado frecuentes.

Error 503 Service Unavailable

Este error indica una incidencia temporal del servicio.

Te recomendamos:

• Volver a intentarlo al cabo de unos segundos.
• Aplicar un número máximo de intentos.
• Registrar el error para poder hacer seguimiento.

Recomendación general de retry

Para errores temporales como 429 o 503:

• Haz entre 3 y 5 reintentos como máximo.
• Espera un poco más entre cada intento.
• No reintentes indefinidamente.

Webhooks

Si necesitas recibir notificaciones automáticas cuando cambia el estado de una factura o de un documento, la mejor opción es utilizar webhooks en lugar de hacer consultas continuas a la API.

En esta guía no entramos en el detalle de la configuración de webhooks, pero es la vía recomendada para reducir consultas y recibir actualizaciones en tiempo real.

Siguiente paso recomendado

Una vez hayas validado:

1. La clave API.
2. El acceso al entorno correcto.
3. El account_id que vas a utilizar.

Ya puedes continuar con los endpoints específicos que necesite tu integración en la documentación API.