API BCE sandbox de integración: claves y datos ficticios
Modo de prueba de API BCE: claves pk_test, una API de prueba idéntica a la v2 y números de empresa ficticios para cada caso, sin cuota ni datos reales.
Construye y prueba tu integración sin tocar datos reales ni tu cuota. La API de prueba responde exactamente como la API live (mismas rutas, mismo sobre JSON, mismos códigos de error) con empresas ficticias.
Cómo funciona#
- Crea un par de claves de prueba (
pk_test_…/sk_test_…) en tu cuenta. - Llama a
https://api-bce.be/test/v2en lugar dehttps://companybelgium.be/api/v2, con las mismas cabeceras. - Para pasar a producción, cambia la URL base y usa una clave live: tu código no cambia.
curl https://api-bce.be/test/v2/enterprise/0999.999.130 \
-H "X-API-Key: $API_BCE_KEY_TEST" \
-H "X-API-Secret: $API_BCE_SECRET_TEST"Las claves de prueba nunca llegan a datos reales, y la API de prueba rechaza las claves live: no puedes confundirlas por error.
Números de empresa de prueba#
Como las tarjetas de prueba de Stripe, cada número provoca un caso concreto. Todos pasan el control módulo 97.
| Número | Comportamiento |
|---|---|
0999.999.130 | Empresa activa, datos completos (actividades, establecimientos, cuentas anuales, administradores). |
0999.999.229 | Quiebra abierta (juridicalSituationCode 050, inDistress true). |
0999.999.328 | Empresa cesada (estado Stopped). |
0999.999.427 | Persona física (autónomo), sin cuentas anuales. |
0999.999.724 | 403 en /financial y /roles: se requiere un plan superior. |
0999.999.526 | 429: cuota mensual superada. |
0999.999.625 | 500: error del servidor (y 503 en VIES). |
0999.999.823 | 404: número válido, empresa desconocida. |
0999.999.999 | 400: número no válido (control módulo 97 incorrecto). |
Números de IVA (VIES)#
| Número | Comportamiento |
|---|---|
BE0999999130 | Válido, con nombre y dirección. |
BE0999999328 | No válido (empresa cesada). |
BE0999999625 | 503: VIES no disponible. |
Establecimientos#
| Número | Comportamiento |
|---|---|
2.999.999.172 | Sede de la empresa activa. |
2.999.999.271 | Sucursal en Gante. |
2.999.999.370 | Establecimiento de la empresa en quiebra. |
Límites#
El modo de prueba permite 1.000 solicitudes por hora y por clave de prueba, sin cuota mensual. Los webhooks aún no están disponibles en modo de prueba.
Probar cada escenario de API BCE sin datos reales#
El modo de prueba sirve sobre todo para los casos difíciles de reproducir. Una empresa en quiebra, una cuota agotada o un fallo de VIES son raros en el día a día. Sin embargo, tu código debe gestionarlos bien desde el primer día. Por eso cada número de prueba provoca un caso concreto. Así puedes escribir tests automáticos que cubran todos los caminos de tu integración.
Por ejemplo, un flujo de alta de proveedores puede probar tres ramas. Con 0999.999.130 la empresa está activa y se acepta. Con 0999.999.229 aparece una quiebra abierta y el alta se bloquea. Por último, con 0999.999.328 la empresa está cesada y tu formulario pide otro número.
Cómo organizar tus tests#
- Define la URL base en una variable:
https://api-bce.be/test/v2en desarrollo,https://companybelgium.be/api/v2en producción. - Prueba el 429 con 0999.999.526 y verifica que tu lógica de espera funciona.
- Prueba el 500 con 0999.999.625 y confirma que reintentas con backoff.
- Prueba el 403 con 0999.999.724 en
/financialy/rolespara mostrar un mensaje claro. - Usa 0999.999.427 para una persona física sin cuentas anuales.
Límites y precauciones#
El modo de prueba permite 1.000 solicitudes por hora y por clave de prueba, sin cuota mensual. Por tanto, puedes lanzar tu suite en integración continua sin gastar tu plan. Ten en cuenta, sin embargo, que los webhooks aún no están disponibles en modo de prueba. Prueba esa parte con la entrega de prueba de la API de webhooks. Además, recuerda que los datos son ficticios: no los muestres nunca a un usuario final.
Integrar el modo de prueba en tu CI
En integración continua, cada ejecución debería cubrir los mismos números de prueba. Primero, guarda las claves de prueba como secretos del sistema de CI, igual que las claves reales. Luego escribe un test por número: actividad, quiebra, cese, persona física, 403, 429 y 500. Así una regresión en tu lógica de errores aparece antes del despliegue. Además, comprueba el número 0999.999.999, que devuelve un 400 por dígitos de control incorrectos, y 0999.999.823, que devuelve un 404.
Preguntas frecuentes sobre API BCE en modo de prueba#
¿Las respuestas de prueba tienen el mismo formato que API BCE en producción?
Sí. La API de prueba usa las mismas rutas, el mismo sobre JSON y los mismos códigos de error que la v2 real. Solo cambian la URL base y las claves.
¿Puedo validar un IVA en modo de prueba?
Sí. BE0999999130 es válido con nombre y dirección, BE0999999328 no es válido y BE0999999625 simula un VIES no disponible con un 503.
¿Cómo paso a producción?
Cambia la URL base y usa una clave live. Las claves de prueba nunca llegan a datos reales, así que no hay riesgo de mezcla.