Representación

El documento que habilita a VeriBai a remitir en nombre de cada emisor, y su flujo de firma.

Para remitir registros en nombre de un emisor, la administración exige un documento de representación firmado por ese emisor. Cada hacienda tiene el suyo, y la API genera el que corresponde según la hacienda del cliente:

En TEST la representación no bloquea nada. En LIVE es requisito: emitir o anular para un emisor sin representación firmada devuelve 403 REPRESENTATION_PENDING.

Estos endpoints pertenecen a la API de gestión: base URL https://manage-api.veribai.com, misma clave x-api-key.

Endpoints

Flujo

1. Genera el documento con GET …/representacion/generar. La respuesta incluye el PDF sin firmar y una URL temporal de descarga.

   Si al cliente le faltan datos para rellenar el formulario, la respuesta es un 400 con camposFaltantes: la lista de campos que faltan, con la misma ruta que usarías en la API (direccion.calle, por ejemplo). Complétalos con PATCH /v1/clientes/{nif} y vuelve a generar.

2. Firma por una de las dos vías:

   • Firma local: el emisor firma el PDF con su propio medio de firma y tu software lo sube con POST …/representacion/verificar (pdfFirmado en base64). El certificado del emisor nunca sale de sus manos.
   • Firma en la nube: POST …/representacion/firmar con pdf, certificado (el .p12 en base64) y password. Útil cuando tu plataforma ya custodia el certificado del cliente con su consentimiento.

3. Consulta el resultado con GET …/representacion/estado.

La respuesta de verificar detalla el resultado de la comprobación: firmaValida, infoFirmante (el sujeto y el emisor del certificado X.509), detallesVerificacion (el diagnóstico nivel a nivel) y contrafirmadoPorVeriBai. Cuando el documento queda pendiente de revisión, incluye además horasRevisionEstimadas. Si la firma se rechaza, la respuesta es un 400 cuyo code nombra la causa, con el mismo detallesVerificacion. Ver rechazos de verificar.

curl -X POST https://manage-api.veribai.com/v1/clientes/B98765432/representacion/firmar \
  -H "x-api-key: TU_CLAVE" \
  -H "Content-Type: application/json" \
  -d '{
    "pdf": "<PDF sin firmar, base64>",
    "certificado": "<certificado .p12, base64>",
    "password": "••••••••"
  }'

import os
from pathlib import Path

import veribai

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

resultado = client.representacion.firmar(
    "B98765432",
    pdf=Path("representacion.pdf").read_bytes(),
    certificado=Path("certificado.p12").read_bytes(),
    password=os.environ["VERIBAI_CERT_PASSWORD"],
)

const respuesta = await fetch("https://manage-api.veribai.com/v1/clientes/B98765432/representacion/firmar", {
  method: "POST",
  headers: {
    "x-api-key": "TU_CLAVE",
    "Content-Type": "application/json",
  },
  body: JSON.stringify({
    "pdf": "<PDF sin firmar, base64>",
    "certificado": "<certificado .p12, base64>",
    "password": "••••••••"
  }),
});

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

Estados

GET …/representacion/estado devuelve estadoRepresentacion (más firmaEnCurso, true mientras hay una firma pendiente de verificar):

Errores

Rechazos de verificar

Cuando el documento firmado no supera la verificación, verificar responde 400 con uno de estos códigos. detallesVerificacion acompaña siempre, con el resultado de cada nivel de comprobación.