Autenticación

Claves API por entorno, enviadas en la cabecera x-api-key.

Toda petición a la API se autentica con una clave API en la cabecera x-api-key:

curl "https://sandbox.veribai.com/v1/facturas?nifEmisor=B00000000" \
  -H "x-api-key: TU_CLAVE"

import veribai

client = veribai.Client(api_key="TU_CLAVE", environment="test")

pagina = client.facturas.listar("B00000000")
for factura in pagina:
    print(factura["numSerieFactura"])

const respuesta = await fetch("https://sandbox.veribai.com/v1/facturas?nifEmisor=B00000000", {
  method: "GET",
  headers: { "x-api-key": "TU_CLAVE" },
});

if (!respuesta.ok) throw new Error(`VeriBai ${respuesta.status}`);
const datos = await respuesta.json();

Claves por entorno

Las claves están ligadas al entorno en el que se crean:

Una clave Sandbox no funciona contra el entorno LIVE, ni al revés. Esto evita que una configuración incorrecta emita registros reales por accidente.

La misma clave autentica también la API de gestión (https://manage-api.veribai.com): emisores, representación, webhooks y validación de NIF. Ahí no se indica entorno: se detecta automáticamente a partir de la clave.

Comprobar la clave

curl https://sandbox.veribai.com/v1/cuenta \
  -H "x-api-key: TU_CLAVE"

import veribai

client = veribai.Client(api_key="TU_CLAVE", environment="test")

respuesta = client.cuenta.obtener()
print(respuesta["entorno"])

const respuesta = await fetch("https://sandbox.veribai.com/v1/cuenta", {
  method: "GET",
  headers: { "x-api-key": "TU_CLAVE" },
});

if (!respuesta.ok) throw new Error(`VeriBai ${respuesta.status}`);
const datos = await respuesta.json();

GET /v1/cuenta confirma que la clave es válida y dice a qué entorno pertenece, en qué plan está la cuenta y si su facturación está activa. Úsala en el arranque de la aplicación o en la integración continua: detecta una clave Sandbox en producción antes del primer alta.

Describe la cuenta, no la disponibilidad del servicio ni de la administración, y consume cuota. Campos y matices en Cuenta y cumplimiento.

Gestión de claves

Cada cuenta tiene una clave por entorno: una de Sandbox y una de LIVE. Se gestionan desde el panel, en Claves API. No hay claves adicionales por aplicación ni por emisor. La única separación es la de entornos.

• Guarda las claves en variables de entorno o en tu gestor de secretos, no en el código fuente ni en el repositorio. El cliente de Python lee VERIBAI_API_KEY y VERIBAI_ENVIRONMENT del entorno; el mismo código pasa de Sandbox a LIVE sin cambios. Un constructor sin environment= usa Sandbox solo mientras esa variable no esté definida, así que pásalo de forma explícita. Ver Entornos del cliente.
• Si varios servicios comparten la clave LIVE, registra dónde está desplegada: al rotarla, todos deben actualizarse dentro del solape.
• Si una clave se ve comprometida, rótala y revoca después la anterior; rotar por sí solo no la desactiva. Ver Clave comprometida.

Rotar una clave

Una clave recién rotada tarda hasta 30 segundos en quedar activa, normalmente menos de 15. La clave anterior sigue siendo válida durante 24 horas.

Hasta entonces, la petición con la clave nueva recibe 403 con el cuerpo {"message": "Forbidden"}, sin campo code. Responde la pasarela, no la API.

Después de rotar, sondea GET /v1/cuenta con la clave nueva hasta que responda 200, y cambia entonces. Unas pocas llamadas espaciadas bastan; consumen cuota como cualquier otra. Durante el solape la clave anterior sigue autenticando, así que no hay corte.

Rotar no reinicia la cuota. El contador mensual es por clave y la clave nueva hereda el consumo de la anterior en el momento de la rotación. Lo consumido se lee en el campo consumo de GET /v1/cuenta.

Clave comprometida

Durante el solape de 24 horas la clave antigua sigue autenticando. Rotar no la desactiva; hay que revocarla.

Son dos pasos, en este orden:

1. Rota la clave desde el panel y despliega la nueva, con el sondeo descrito arriba.
2. Revoca la anterior desde el panel, sin esperar a que expire el solape.

Rotar y revocar son operaciones independientes. Despliega la clave nueva antes de revocar la anterior; así los segundos de propagación no dejan a tu integración sin una clave válida.

La revocación tarda unos diez segundos en completarse. Durante ese tiempo, la clave antigua puede fallar en una petición y responder en la siguiente. Una petición rechazada no confirma la revocación; da la clave por revocada pasado ese plazo.

Errores de autenticación

Una petición sin clave, o con una clave inválida o revocada, se rechaza sin procesar la factura. La respuesta no distingue entre clave inexistente y clave revocada, para no revelar qué claves existen.