Cuenta y cumplimiento

Comprobar la clave y el estado de la cuenta, y obtener la Declaración Responsable vigente.

Dos endpoints de nivel de cuenta. Uno dice qué clave tienes y en qué estado está la cuenta; el otro devuelve el documento de cumplimiento vigente. Ninguno se refiere a una factura concreta, y ninguno lleva nifEmisor.

GET /v1/cuenta

Comprobación de clave y entorno: confirma que la clave es válida, dice a qué entorno pertenece y si la facturación de la cuenta está activa. No lleva parámetros. Se resuelve a partir de la propia 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();

{
  "entorno": "test",
  "plan": "minimum",
  "estadoCuenta": "activa",
  "facturacionActiva": true,
  "nifClientePrincipal": "A12345678",
  "consumo": {
    "usadas": 312,
    "restantes": 688,
    "limite": 1000,
    "periodo": "MONTH",
    "observadoEn": "2026-08-23T10:04:00Z"
  },
  "consultadoEn": "2026-08-23T10:12:00Z"
}

Una clave ausente, inválida o revocada no llega al endpoint: la rechaza antes la puerta de API. estadoCuenta: "desconocido" significa que no se pudo leer el estado de facturación, no que haya un problema con la cuenta; facturacionActiva sigue reflejando lo que harán los endpoints de emisión.

Cuota consumida (consumo)

El bloque consumo dice cuánto llevas gastado del cupo mensual de esa clave. La cuota va por clave, no por cuenta: cada clave tiene su propio contador. Rotar no lo reinicia: la clave nueva hereda el consumo de la anterior. El traspaso es una foto del instante de la rotación, así que lo que la clave antigua siga gastando durante el resto del solape no se traslada. De ahí que usadas + restantes pueda quedar por debajo de limite tras una rotación. Es el comportamiento correcto, y no hay nada que cuadrar.

Dos matices que conviene tratar bien en el código:

El bloque puede faltar, y su ausencia no es un cero. Una clave recién creada, o una lectura que no se pudo resolver, devuelven la respuesta sin consumo, no con restantes: 0, que significaría justo lo contrario: que has agotado el cupo. Comprueba que el campo existe antes de leerlo, y trata su ausencia como «todavía no se sabe».

observadoEn es parte de la cifra, no decoración. El contador se refresca en ciclos cortos y los datos de la pasarela llegan con unos minutos de retraso encima, así que el número puede ir hasta unos diez minutos por detrás. Sirve para saber cuánto te queda y para avisar antes de llegar al tope; no sirve para decidir si la siguiente llamada concreta va a entrar. Esa la resuelve el 429.

Qué no es este endpoint

No informa del estado del servicio. Describe tu cuenta. No consulta a la AEAT ni a las haciendas forales, y no dice nada sobre su disponibilidad. Por eso no se llama /v1/health.

No es un objetivo de monitorización. Cuenta contra la cuota mensual como cualquier otra llamada con clave API. Su sitio son las comprobaciones de arranque y de integración continua (al desplegar, al rotar una clave, al configurar un entorno nuevo), no un sondeo periódico. Ver Límites.

facturacionActiva: true no significa «ya puedo emitir». Cubre la facturación de tu cuenta y nada más. En LIVE el alta pasa una segunda puerta, por emisor: la representación de ese emisor debe estar firmada, o la llamada responde 403 REPRESENTATION_PENDING. Este endpoint se resuelve desde la clave, así que no puede saber para qué emisor será tu siguiente llamada. Ese estado se consulta por cliente, en el campo estadoRepresentacion de GET /v1/clientes/{nif} o en GET /v1/clientes/{nif}/representacion/estado.

GET /v1/cumplimiento/declaracion-responsable

Devuelve la URL de la Declaración Responsable vigente, el documento con el que VeriBai certifica que su sistema informático de facturación cumple el reglamento. Si tu producto se apoya en VeriBai como sistema de facturación, es el documento que tus propios clientes acabarán pidiéndote.

curl https://manage-api.veribai.com/v1/cumplimiento/declaracion-responsable \
  -H "x-api-key: TU_CLAVE"

import veribai

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

respuesta = client.cumplimiento.declaracion_responsable()

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

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

{
  "url": "https://docshare.veribai.com/compliance/declaracion-responsable.pdf",
  "key": "compliance/declaracion-responsable.pdf",
  "lastModified": "2026-06-20T09:14:22+00:00",
  "storageClass": "STANDARD"
}

Si todavía no hay documento publicado, la respuesta es 404 NOT_UPLOADED_YET.

Por qué pedirla en lugar de fijar la URL

Una URL escrita a mano en el código envejece mal: si el documento cambia de sitio, el enlace que muestras a tus clientes deja de funcionar y nadie lo descubre hasta que alguien lo pulsa. Pidiéndola obtienes la URL vigente, un 404 limpio mientras no haya documento, y lastModified para saber cuándo ha cambiado.

El endpoint necesita clave; el documento no. La url es de lectura anónima a propósito: un cliente potencial, un auditor o la propia Administración deben poder leer la Declaración Responsable sin tener cuenta en VeriBai. No la trates como un secreto ni la sirvas detrás de tu propia autenticación. Puedes enlazarla directamente o cachearla, pero vuelve a leer lastModified antes de dar por hecho que los bytes siguen siendo los mismos.