Documentación
Autenticación
La API usa dos credenciales con papeles distintos: la API keyautentica a tu software ante FactuBridge; el certificado electrónico autentica el envío de los registros ante la AEAT. Tu integración solo maneja la primera.
API key
Tu software se autentica con una API key, que se envía en la cabeceraAuthorization de cada petición:
Authorization: Bearer fb_live_9f2c8e1a7b3d...- La generas tú mismo desde el portal web (sección «API keys») y se muestra una sola vez: nunca viaja por correo ni pasa por nosotros. Si se pierde o se compromete, la rearmas desde el portal (la anterior queda revocada al instante).
- Guárdala como secreto de servidor. Nunca la incluyas en código cliente (web, app móvil) ni en repositorios.
- Una petición sin clave o con clave revocada recibe
401 Unauthorized.
Puedes comprobar en cualquier momento que tu clave es válida y a qué NIF y entorno apunta:
curl "$BASE_URL/health" \
-H "Authorization: Bearer $FACTUBRIDGE_API_KEY"
# → {
# "status": "operativo",
# "nif": "A12345678",
# "entorno": "produccion"
# }Certificados: quién firma ante la AEAT
Hay dos modalidades, y se deciden en el alta de cada obligado tributario:
| Modalidad | Cómo funciona | Para quién |
|---|---|---|
| Colaborador social (por defecto) | FactuBridge remite los registros con el certificado de Intergal, registrada como colaborador social ante la AEAT. Requiere la autorización de representación firmada por el obligado. | La mayoría de los casos: nadie tiene que exportar ni mover su certificado. |
| Certificado propio (entidades) | La entidad sube su certificado de representante o su sello (PFX) desde su navegador en el portal de FactuBridge. Se cifra con AES-256-GCM antes de almacenarse. | Entidades que prefieren que cada envío vaya firmado con su propia identidad y ya custodian ese certificado en sus sistemas. |
Los certificados de persona física no se admiten en esta modalidad. Su clave privada es personal e intransferible por la Declaración de Prácticas de Certificación de la FNMT y por el artículo 7 de la Ley 6/2020, y ninguna autorización del titular habilita a un tercero a firmar con ella. El obligado que sea persona física —esté o no dado de alta como autónomo— delega la remisión por la modalidad de colaborador social, donde firma Intergal con su propio certificado. En la modalidad de certificado propio el titular es siempre una entidad, sea persona jurídica o entidad sin personalidad jurídica del artículo 35.4 de la Ley General Tributaria, y nos encomienda la custodia de su certificado como encargado del tratamiento.
El certificado nunca viaja por la API. No existe ningún endpoint público para enviar certificados: la subida se hace por el portal web, autenticada con usuario y contraseña del propio obligado. El detalle del cifrado en reposo (envelope encryption, claves maestras solo en memoria, auditoría append-only) está descrito en lapágina de seguridad.
Multi-NIF
Si tu software da servicio a varios obligados tributarios (una gestoría, un ERP vertical), cada obligado tiene su alta y su certificado, y cada instalación de SIF su API key. El modelo completo está enMulti-NIF.