Tu ERP sigue mandando
Adaptar un ERP a TicketBAI no tiene por qué significar meter dentro del producto la firma, los XML de tres haciendas y el encadenamiento. Con KubiBAI, tu software conserva sus clientes, sus líneas, sus precios y su numeración. Cuando emite una factura, la manda en JSON a una API REST y recibe de vuelta el resultado de la hacienda foral, el identificador TBAI y el QR para la factura.
Es el mismo planteamiento para un ERP clásico, un software de gestión sectorial o un SaaS que factura por cuenta de muchas empresas. Lo que cambia es cuántas empresas gestionas, y de eso va el apartado «Una API key por empresa».
Qué te toca a ti y qué no
Te toca a ti:
- Decidir cuándo se emite una factura y con qué numeración.
- Montar el JSON con los datos de la factura: emisor, destinatarios, conceptos y desglose fiscal.
- Guardar lo que devuelve KubiBAI, sobre todo el
signature_value y el identificador de la factura, y mostrar su estado a tu usuario.
Te quitas de encima:
- Generar el XML TicketBAI, con la estructura que pide cada hacienda, a partir de un único formato JSON.
- Firmarlo. KubiBAI firma con su certificado de Software Garante, o con el tuyo si eres titular de uno.
- El encadenamiento con la factura anterior, si activas el encadenamiento automático de la empresa. Es opcional y se activa desde el panel web.
- El envío a Araba, Bizkaia o Gipuzkoa y la gestión de su respuesta.
Una API key por empresa
KubiBAI trabaja con dos credenciales. La API key de usuario (X-Qbikode-UserApiKey) es la tuya, como intermediario, y sirve para dar de alta empresas y consultar la configuración. Cada empresa o profesional recibe además su propia API key (X-Qbikode-ClientApiKey), con la que se emiten sus facturas.
El alta es una llamada a POST /clientcompanies con el territorio, el NIF, el nombre o la razón social y si es persona física. La respuesta incluye la API key de esa empresa. Si tu software factura por muchos clientes, el alta se puede automatizar desde tu propio proceso de alta de empresas, y cada una opera con su credencial.
Los detalles, con los campos obligatorios, están en la guía de empresas y credenciales.
Las autorizaciones de representación
Cuando KubiBAI actúa por vía telemática en nombre de una empresa, esa empresa tiene que firmar una autorización de representación. Se carga por empresa de tres maneras: desde el panel, con una petición multipart/form-data o con una petición JSON con el archivo en Base64 (PDF, JPG o PNG).
Dos cosas conviene saber antes de diseñar el flujo:
- No hace falta en Araba ni si eres titular de Software Garante.
- Un
200 al subir el documento confirma que se ha recibido, no que se haya validado. Mientras está pendiente de validación, las operaciones que la requieren no se pueden hacer, y KubiBAI te avisa cuando se aprueba o se rechaza.
Más detalle en la guía de autorizaciones.
Facturas ordinarias, rectificativas y anulaciones
La mayoría del tráfico de un ERP son facturas completas, pero hay que cubrir los casos que se salen del camino feliz:
- Rectificativas. Por sustitución (
rectificative_type_code: "S") la nueva factura lleva los importes correctos y la base y la cuota originales; por diferencias (I) solo registra la diferencia. Se indica el motivo, de R1 a R5, y qué factura se corrige.
- Anulaciones. Son un registro adicional de TicketBAI: invalidan la factura a efectos fiscales sin borrarla, y su número no se reutiliza.
- Correcciones sin cambiar el total. En Araba y Gipuzkoa, Zuzendu permite corregir datos del emisor, del destinatario o de los conceptos. Si cambia el precio final, toca una rectificativa.
Todos tienen su JSON en los ejemplos de la API.
Lo que cambia según el territorio
Los tres territorios comparten formato, pero no reglas. Algunas diferencias que se notan al integrar:
- Los conceptos (
concepts) son obligatorios en Araba y Gipuzkoa y pueden omitirse en Bizkaia, salvo que generes también FacturaE.
- En Bizkaia, las comunidades de bienes, las sociedades civiles y las comunidades de propietarios se tramitan por el modelo 140 y envían los datos de renta en
income_data_items.
- El LROE es propio de Bizkaia. Con él puedes enviar gastos (modelo 140), facturas recibidas (modelo 240) y operaciones de bienes, siempre que seas titular de Software Garante y uses tu propio certificado.
- Zuzendu existe en Araba y Gipuzkoa, pero no en Bizkaia.
Para el contexto fiscal de Bizkaia, tienes la guía de BATUZ, TicketBAI y LROE.
Un destinatario extranjero se identifica con other_id_country_code, other_id_type y other_id_card_id en lugar de un NIF. Para facturar a una administración pública, generate_facturae: true genera en la misma petición la factura TicketBAI y el XML FacturaE 3.2.1, con los centros DIR3 del destinatario. KubiBAI no envía el FacturaE a FACe: la entrega la gestionas tú.
Síncrono o asíncrono
Si tu ERP emite en lote, de noche o por muchas empresas, no tiene por qué esperar a la hacienda en cada llamada. Con async_mode en lite o full, la petición vuelve enseguida y el resultado te llega por webhook o lo consultas por el estado de la factura. Con none, recibes el resultado en la propia respuesta.
Del entorno de pruebas a producción
Las facturas del entorno de pruebas se envían a los servidores de pruebas de TicketBAI, así que validas el flujo completo, con firma y respuesta de la hacienda, sin datos reales. Cuando todo encaja, cambias la URL base (de wstests.kubibai.com a kws.kubibai.net) y usas las credenciales de producción.
Cómo se integra
- Pide acceso al entorno de pruebas con tu API key de usuario.
- Da de alta una empresa por territorio y copia su API key.
- Carga la autorización de representación si la empresa la necesita.
- Envía una factura básica y sigue con los casos que te toquen.
- Revisa el flujo de errores y reenvíos, y pasa a producción.
Si tus clientes están también en territorio común, KubiFACTU resuelve lo mismo para la AEAT: VeriFactu para ERP.
