Clientes (emisores)

Alta y gestión de los emisores en cuyo nombre factura tu software.

En VeriBai, cada empresa o autónomo para quien tu software emite facturas es un cliente de tu cuenta: el emisor. Todo emisor debe estar dado de alta antes de emitir su primera factura: una petición con un emisor.nif no registrado bajo tu cuenta se rechaza con 403.

Estos endpoints pertenecen a la API de gestión: base URL https://manage-api.veribai.com, misma clave x-api-key. El entorno (Sandbox o LIVE) se detecta automáticamente a partir de la clave.

Endpoints

La eliminación y restauración de clientes se gestionan desde el panel.

Crear un cliente

curl -X POST https://manage-api.veribai.com/v1/clientes/crear \
  -H "x-api-key: TU_CLAVE" \
  -H "Content-Type: application/json" \
  -d '{
    "nif": "B00000000",
    "nombre": "Restaurant La Buena Mesa SL",
    "email": "contacto@restaurant.com",
    "tipoUsuario": "empresa",
    "hacienda": "verifactu",
    "direccion": {
      "calle": "Gran Via",
      "numero": "1",
      "codigoPostal": "08001",
      "ciudad": "Barcelona",
      "provincia": "Barcelona"
    },
    "representante": {
      "nombre": "Juan Pérez García",
      "nif": "00000000T",
      "direccion": {
        "calle": "Gran Via",
        "numero": "1",
        "codigoPostal": "08001",
        "ciudad": "Barcelona",
        "provincia": "Barcelona"
      }
    }
  }'

import veribai

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

respuesta = client.clientes.crear({
    "nif": "B00000000",
    "nombre": "Restaurant La Buena Mesa SL",
    "email": "contacto@restaurant.com",
    "tipoUsuario": "empresa",
    "hacienda": "verifactu",
    "direccion": {
        "calle": "Gran Via",
        "numero": "1",
        "codigoPostal": "08001",
        "ciudad": "Barcelona",
        "provincia": "Barcelona",
    },
    "representante": {
        "nombre": "Juan Pérez García",
        "nif": "00000000T",
        "direccion": {
            "calle": "Gran Via",
            "numero": "1",
            "codigoPostal": "08001",
            "ciudad": "Barcelona",
            "provincia": "Barcelona",
        },
    },
})

const respuesta = await fetch("https://manage-api.veribai.com/v1/clientes/crear", {
  method: "POST",
  headers: {
    "x-api-key": "TU_CLAVE",
    "Content-Type": "application/json",
  },
  body: JSON.stringify({
    "nif": "B00000000",
    "nombre": "Restaurant La Buena Mesa SL",
    "email": "contacto@restaurant.com",
    "tipoUsuario": "empresa",
    "hacienda": "verifactu",
    "direccion": {
      "calle": "Gran Via",
      "numero": "1",
      "codigoPostal": "08001",
      "ciudad": "Barcelona",
      "provincia": "Barcelona"
    },
    "representante": {
      "nombre": "Juan Pérez García",
      "nif": "00000000T",
      "direccion": {
        "calle": "Gran Via",
        "numero": "1",
        "codigoPostal": "08001",
        "ciudad": "Barcelona",
        "provincia": "Barcelona"
      }
    }
  }),
});

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

{
  "message": "Cliente creado correctamente",
  "cliente": {
    "nif": "B00000000",
    "nombre": "Restaurant La Buena Mesa SL",
    "hacienda": "verifactu",
    "tipoUsuario": "empresa",
    "estado": "activo",
    "estadoRepresentacion": "pendiente",
    "validacionCensal": {
      "estado": "identificado",
      "validadoEn": "2026-04-03T09:00:00Z"
    },
    "direccion": {
      "calle": "Gran Via",
      "numero": "1",
      "codigoPostal": "08001",
      "ciudad": "Barcelona",
      "provincia": "Barcelona"
    },
    "creadoEn": "2026-04-03T09:00:00Z",
    "representante": {
      "nombre": "Juan Pérez García",
      "nif": "00000000T",
      "direccion": {
        "calle": "Gran Via",
        "numero": "1",
        "codigoPostal": "08001",
        "ciudad": "Barcelona",
        "provincia": "Barcelona"
      }
    }
  }
}

201 Created devuelve el cliente completo en el sobre { "message", "cliente" }. El alta valida el formato del NIF, su unicidad global y el límite de clientes de tu plan. Las tres comprobaciones son atómicas. B00000000 y 00000000T son NIF de ejemplo: la AEAT no admite NIF con el número todo ceros, y el alta los rechaza con 400 VALIDATION_ERROR, igual que un carácter de control incorrecto. Sustitúyelos por NIF reales; en Sandbox, el de tu empresa o el de un cliente que te lo autorice.

Campos

Campos derivados en las respuestas

Tu propia empresa como emisor

Si facturas en tu propio nombre, tu empresa se da de alta como un emisor más: POST /v1/clientes/crear con tu propio NIF y los mismos campos que cualquier otro cliente. No hay endpoint aparte. Ese emisor ocupa una plaza de tu plan como los demás.

La respuesta lo marca con clientePropio: true. El campo se deriva de comparar el NIF del alta con el de tu cuenta; no se envía ni se modifica.

Dos respuestas difieren de las del alta de un tercero:

El alta de un tercero responde igual en ambos casos, para no revelar qué NIF están registrados en VeriBai. Con tu propio NIF la respuesta sí es explícita.

El 200 exige que la ficha pertenezca a tu cuenta, no solo que el NIF coincida. Una ficha con tu NIF en otra cuenta no se devuelve.

Confirma la hacienda antes de enviar el alta. Es inmutable, y tu propio emisor no puede desactivarse ni eliminarse (409 SELF_CLIENT_PROTECTED). Una hacienda equivocada en tu propio emisor no se corrige por API.

representante es obligatorio para tipoUsuario: empresa, también en el alta de tu propia empresa: nombre, NIF y dirección completa. Son los datos del documento de representación del paso siguiente. Un autónomo que se da de alta a sí mismo no lo lleva.

Listado y plazas del plan

GET /v1/clientes devuelve tus emisores paginados y, con ellos, el consumo del plan en el entorno de la clave.

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

import veribai

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

respuesta = client.clientes.listar()
print(respuesta["clientesUsados"], respuesta["limitePlan"])

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

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

{
  "entorno": "test",
  "clientes": [
    {
      "nif": "B00000000",
      "nombre": "Restaurant La Buena Mesa SL",
      "hacienda": "verifactu",
      "estado": "activo",
      "estadoRepresentacion": "pendiente",
      "estadoCenso": "identificado",
      "modoCadena": "unica",
      "faseAltaCapacidad": "no_contratada"
    }
  ],
  "total": 1,
  "limitePlan": 25,
  "clientesUsados": 18,
  "clientesDisponibles": 7
}

total cuenta filas de la página, no emisores de la cuenta: con limite=20 y 137 emisores dados de alta, total es 20. El número de emisores de la cuenta está en clientesUsados.

Ausente no es cero

limitePlan, clientesUsados y clientesDisponibles aparecen los tres o ninguno. Se omiten cuando la cuenta no tiene límite configurado y también si su lectura falla. El listado responde 200 con clientes completo en ambos casos.

Su ausencia significa «límite desconocido», no «cero». Si los tres campos faltan, oculta la interfaz de plazas en lugar de bloquear el alta. La comprobación definitiva es la del alta, que es atómica.

El límite se ajusta por cuenta y puede no coincidir con ninguna tabla de planes. Léelo de este endpoint, no del plan contratado.

Los límites y los contadores son por entorno: Sandbox y LIVE llevan cada uno el suyo. Los tres campos describen el entorno de la clave (el que devuelve entorno), no la cuenta en conjunto.

clientesUsados cuenta emisores activos, no filas, y cambia con el estado de cada uno:

Dos consecuencias. Con emisores inactivos, clientesUsados es menor que el número de filas de clientes. Reactivar o restaurar un emisor pasa de nuevo por el límite y puede rechazarse.

Ejemplo: una cuenta con limitePlan: 10, ocho emisores dados de alta y uno de ellos inactivo responde clientesUsados: 7 y clientesDisponibles: 3. Contar las ocho filas daría «8 de 10» y ocultaría una de las tres plazas libres.

El emisor propio estuvo exento del límite hasta el 10 de septiembre de 2026. Si tu cuenta es anterior a esa fecha, su clientesUsados puede seguir una unidad por debajo de sus emisores activos.

Alta capacidad en las fichas

modoCadena y faseAltaCapacidad acompañan a cada emisor, en las filas del listado y en el detalle. Indican si el emisor tiene Alta capacidad contratada y en qué fase está, sin llamar a otro endpoint.

Los dos campos se omiten si su lectura falla; el listado responde 200 igualmente. Un campo ausente equivale al valor por defecto: unica para modoCadena y no_contratada para faseAltaCapacidad.

Ambos valores pertenecen al emisor, no al entorno: Sandbox y LIVE responden lo mismo.

Modificar y desactivar

PATCH /v1/clientes/{nif} acepta cambios parciales de nombre, direccion, representante, epigrafeIAE y portalHabilitado. Un cuerpo sin ninguno de esos cinco campos responde 400 VALIDATION_ERROR. hacienda no se modifica y se ignora: un emisor que cambia de hacienda es un alta nueva.

portalHabilitado es estrictamente booleano: "true", 1 o "" se rechazan. Activarlo es la mitad del interruptor: el portal de clientes se habilita también por cuenta, y esa parte la activa el equipo de VeriBai.

Mientras hay una firma de representación en curso, los campos del documento (nombre, direccion, representante) quedan bloqueados: la respuesta es 409 SIGNING_IN_PROGRESS con camposBloqueados. Cancela la firma con DELETE …/representacion/firma-en-curso o complétala, y repite la petición.

PATCH /v1/clientes/{nif}/estado alterna entre activo e inactivo con cuerpo { "estado": "inactivo" }. Solo se emite para emisores activos. Un cliente inactivo no consume plaza de tu plan: al desactivarlo sale de clientesUsados, y reactivarlo pasa de nuevo por el límite. Si la cuenta está llena, la reactivación responde 409 CLIENT_LIMIT_REACHED.

La respuesta lleva message, nif, estado y entorno. Cuando el emisor ya estaba en el estado pedido, la llamada responde 200 sin entorno. Comprueba que el campo existe antes de leerlo.

Un emisor eliminado no se reactiva por aquí: responde 409 CLIENT_DELETED. Se restaura desde el panel, que comprueba la ventana de 30 días.

Errores