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=B76116342" \
  -H "x-api-key: TU_CLAVE"

import veribai

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

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

const respuesta = await fetch("https://sandbox.veribai.com/v1/facturas?nifEmisor=B76116342", {
  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 TEST 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. Es la llamada que conviene dejar en el arranque de la aplicación o en la integración continua: una clave TEST en producción se detecta ahí, no en el primer alta.

No es un endpoint de estado del servicio ni de monitorización. Habla de tu cuenta, no de la disponibilidad de Hacienda, y consume cuota. Campos y matices en Cuenta y cumplimiento.

Gestión de claves

Cada cuenta tiene una clave por entorno: una de TEST 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, nunca en el código fuente ni en el repositorio. El cliente de Python lee VERIBAI_API_KEY y VERIBAI_ENVIRONMENT del entorno, así que el mismo código pasa de TEST a LIVE sin tocar una línea. Esa comodidad tiene contrapartida: un constructor sin environment= queda a merced de la variable, y solo es sandbox mientras no esté definida. Pásalo explícito. Ver Entornos del cliente.
• Si varios servicios comparten la clave LIVE, deja anotado dónde está desplegada. El día que haya que rotarla, todos tienen que actualizarse dentro del solape.
• Si una clave se ve comprometida, rótala y revoca después la anterior. Rotar por sí solo no cierra la fuga. Ver Clave comprometida.

Rotar una clave

Una clave recién rotada tarda unos segundos en quedar activa: cuenta con hasta 30 segundos, y normalmente menos de 15. No es una incidencia. Es la propagación entre el plano de control de la pasarela y la capa que atiende las peticiones, y es la razón por la que la clave anterior sigue siendo válida durante 24 horas.

Mientras esa propagación no termina, la petición con la clave nueva se rechaza con 403 y el cuerpo {"message": "Forbidden"}, sin campo code. Ahí responde la pasarela, no la API.

No programes el cambio con un temporizador. Después de rotar, sondea con la clave nueva un endpoint de lectura barato (GET /v1/cuenta) hasta que responda 200, y cambia entonces. Unas pocas llamadas espaciadas bastan; como cualquier otra, consumen cuota. El solape de 24 horas existe precisamente para eso: la clave anterior sigue autenticando mientras tanto, así que el corte no llega a existir.

Rotar no amplía la cuota. El contador mensual va por clave, pero la clave nueva hereda el consumo de la anterior en el momento del relevo: rotar a mitad de mes no devuelve el cupo ya gastado. Lo consumido se lee en el campo consumo de GET /v1/cuenta.

Clave comprometida

El solape que hace cómoda una rotación planificada estorba cuando la clave se ha filtrado: durante esas 24 horas la clave antigua sigue autenticando. Rotar no la desactiva.

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.

Están separados a propósito. Así eliges tú cuándo asumir los segundos de propagación de la clave nueva, en lugar de que la revocación te los imponga en mitad de un incidente.

La revocación tarda unos diez segundos, y no se propaga de golpe: mientras tanto, la clave antigua puede fallar en una petición y responder en la siguiente. No compruebes la revocación sondeando con la clave antigua. Una petición rechazada no demuestra que la clave esté muerta, y dar por cerrada una fuga antes de tiempo es peor que no comprobarla.

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. Es deliberado, para no filtrar información.