Integración Billingo
Billingo es una plataforma húngara de facturación en línea conforme con NAV Online Számla 3.0. Una vez configurada en CADENSA, puedes emitir facturas fiscales húngaras legalmente v álidas directamente desde tus entradas de tiempo — con declaración automática a NAV y sincronización desde tu libreta de contactos de Billingo.
Requisitos Previos
- Una cuenta Billingo activa (con acceso a API)
- Una clave API Billingo v3 (ver abajo)
- Al menos un bloque de facturas (számlablokk) configurado en Billingo
- Rol Admin mínimo en la unidad de CADENSA
Paso 1 — Obtener tu Clave API de Billingo
- Inicia sesión en app.billingo.hu
- En el menú izquierdo, haz clic en Beállítások (Configuración)
- Haz clic en API en el menú de configuración
- Haz clic en + Új API kulcs létrehozása (Crear nueva clave API)
- Asigna un nombre (p.ej.,
CADENSA) - Copia la clave generada inmediatamente — solo se muestra una vez
Nunca compartas tu clave API ni la incluyas en el control de versiones. Cualquiera con la clave puede crear facturas en tu nombre.
Paso 2 — Configurar en CADENSA
- Abre Configuración → Factura en CADENSA
- Selecciona Billingo 🇭🇺 como proveedor
- Aparecerá un mensaje informativo:
Encuentra tu clave API de Billingo en: app.billingo.hu → Beállítások → API → API kulcs létrehozása
- Pega tu clave API en el campo API Key
- Haz clic en Probar Conexión — un
verde confirma la validez - Haz clic en Guardar
El botón Guardar permanece desactivado hasta que la prueba de conexión sea exitosa.
Paso 3 — Establecer Valores por Defecto
| Configuración | Valor recomendado (HU) | Descripción |
|---|---|---|
| Moneda por defecto | HUF | Moneda usada en nuevas facturas |
| IVA % por defecto | 27 | Tipo estándar húngaro (ÁFA) |
| Días de vencimiento | 8 o 30 | Días hasta la fecha de vencimiento |
| Tipo de documento por defecto | Factura | Preseleccionado en el diálogo de generación |
| País del emisor | HU | Código de país ISO 3166-1 alpha-2 de tu empresa |
El campo País del emisor habilita sugerencias inteligentes de IVA (inversión del sujeto pasivo, detección de exportación) en el diálogo de generación de facturas. Sin él, CADENSA usa el tipo de IVA doméstico del comprador. Consulta Generación de Facturas — Sugerencia de IVA para más detalles.
Paso 4 — Configuración Específica de Billingo
| Configuración | Descripción |
|---|---|
| ID de Bloque de Facturas | El bloque de facturas de Billingo a usar. CADENSA selecciona automáticamente el primer bloque activo si se deja vacío. Para un bloque específico, introduce el ID desde Billingo → Beállítások → Bizonylattömbök. |
| ID de Cuenta Bancaria | Opcional. El ID de tu cuenta bancaria de Billingo — aparece en la factura. |
| Método de Pago | Método de pago por defecto (wire_transfer, cash, bankcard, etc.). |
| Idioma de la Factura | Idioma de emisión (hu, en, de, es, etc.). |
Paso 5 — (Opcional) Modo Sandbox / Prueba
Activa el modo Sandbox para probar la generación de facturas sin emitir facturas reales declaradas a NAV. Las facturas sandbox:
- No aparecen en tu lista oficial de Billingo
- No se declaran a NAV
- Se descartan después de las pruebas
Interruptor: Configuración → Factura → Sandbox / Modo de prueba
Emitir una Factura vía Billingo
- Abre Informes → aplica el rango de fechas y filtros de proyecto
- Haz clic en Generar Factura
- En el campo Tipo de Documento, selecciona Factura — el canal de salida muestra
Billingo - (Opcional) Usa el selector de socios para elegir un cliente de tu libreta de Billingo
- Completa los datos del cliente, el tipo de IVA y la fecha de vencimiento
- Haz clic en Vista Previa → revisa las líneas y totales
- Haz clic en Emitir Factura (Billingo)
- Se crea una nueva factura y se finaliza inmediatamente (asignando el número de factura de Billingo)
- La factura se declara automáticamente a NAV Online Számla 3.0
- La factura aparece en Billingo bajo Számlák → Kimenő számlák
Selector de Socios
Cuando Billingo está configurado, el diálogo de generación muestra un selector de socios — una lista desplegable con búsqueda de tus contactos de Billingo.
Al seleccionar un contacto, se rellenan automáticamente:
- Nombre de la empresa
- Dirección (calle, código postal, ciudad, país)
- Número de identificación fiscal
- Dirección de correo electrónico
Si el cliente no existe en tu libreta de Billingo, CADENSA lo crea automáticamente. Los contactos se obtienen del endpoint /partners de Billingo (hasta 100 socios).
CADENSA compara los socios por nombre sin distinguir mayúsculas/minúsculas. Si ya existe un socio con el mismo nombre, el registro existente se actualiza con los nuevos datos de dirección proporcionados.
Tipos de IVA
| Tipo | Uso |
|---|---|
| 27% | IVA estándar húngaro (ÁFA) |
| 5% | Tipo reducido (ciertos alimentos, medicamentos) |
| 0% | Exento, suministro intracomunitario, exportación |
| AAM | Exención general de impuestos |
| TAM | Exención objetiva |
| EU | Suministro intracomunitario de bienes |
| EUK | Suministro intracomunitario (caso especial UE) |
| MAA | Compensación agrícola a tanto alzado |
| F.AFA | Inversión del sujeto pasivo (reverse charge) |
| K.AFA | IVA de caja |
| KBAUK | Exportación fuera de la UE |
Si introduces un tipo de IVA que no está en la lista anterior, CADENSA usa 27% por defecto. Usa los tipos numéricos (0, 5, 27) para casos estándar y los códigos de texto para tratamientos fiscales especiales.
Facturas en Moneda Extranjera
Billingo funciona nativamente en HUF. Para facturas en otras monedas (EUR, USD, GBP, etc.):
- CADENSA obtiene automáticamente el tipo de cambio HUF actual de la API Frankfurter (datos del BCE)
- El tipo de cambio (
conversion_rate) se incluye en la solicitud como requiere Billingo - El tipo se registra en el registro de facturas de CADENSA a efectos de auditoría
Si la API de tipo de cambio no está disponible, CADENSA usa tipos de respaldo aproximados (EUR ~400 HUF, USD ~370 HUF). Para uso en producción, asegúrate de tener conectividad saliente a api.frankfurter.app.
Enrutamiento de Documentos
| Tipo de Documento | Salida |
|---|---|
| Proforma | PDF interno (nunca se envía a Billingo) |
| Resumen de Trabajo | PDF interno (nunca se envía a Billingo) |
| Factura | Enviado a la API de Billingo → se devuelve el PDF |
Solo los documentos de tipo "Factura" se envían a Billingo. Proforma y Resumen de Trabajo siempre se generan internamente, independientemente de la configuración del proveedor.
Cancelación de Factura (Storno)
Para cancelar una factura de Billingo desde CADENSA:
- Abre Facturación → Historial de Facturas
- Busca la factura y haz clic en Cancelar Factura
- Confirma la cancelación
CADENSA llama a POST /documents/{id}/cancel. Se crea automáticamente una factura de cancelación en Billingo y se declara a NAV.
Las facturas canceladas no pueden recuperarse. Si necesitas volver a facturar, genera una nueva factura desde la página de Informes.
Historial de Facturas y Descarga de PDF
Después de crear una factura correctamente:
- La factura aparece en Facturación → Historial de Facturas en CADENSA
- La factura también aparece en tu cuenta de Billingo bajo Számlák → Kimenő számlák
- Puedes volver a descargar el PDF en cualquier momento desde cualquiera de los dos lugares
Prueba de Conexión
Usa el botón Probar Conexión después de introducir tu clave API. CADENSA llama al endpoint /utils/time de Billingo para verificar:
- Que la clave API es válida y está activa
- Que la clave tiene los permisos necesarios
Una prueba exitosa muestra:
✓ Conexión exitosa
Solución de Problemas
"Clave API inválida" / 401 No autorizado
La clave API es inválida, ha expirado o ha sido revocada.
Solución: Genera una nueva clave en Billingo (Beállítások → API → + Új API kulcs) y vuelve a introducirla en CADENSA.
"No se encontraron bloques de facturas"
No hay ningún bloque de facturas configurado en Billingo.
Solución: En Billingo, ve a Beállítások → Bizonylattömbök y crea al menos un bloque activo.
Error "INVOICE_NO_BILLABLE_ITEMS"
Todas las líneas tienen amount = 0 — no hay tarifas por hora configuradas.
Solución: Ve a Configuración → Tarifas y configura tarifas horarias para tus proyectos.
Error "Socio no encontrado"
La creación automática del socio falló — normalmente por un campo obligatorio faltante (código postal, ciudad o dirección).
Solución: Asegúrate de que el registro del cliente en CADENSA tenga al menos un código de país y una ciudad. Alternativamente, crea el socio manualmente en Billingo primero y selecciónalo mediante el selector de socios.
El PDF no tiene número de factura
La llamada a la API de Billingo tuvo éxito, pero el PDF descargado desde CADENSA no incluye el número de factura externo.
Solución: Vuelve a descargar el PDF desde Facturación → Historial de Facturas — el registro almacenado tiene el número de factura correcto de Billingo.
Límite de solicitudes excedido (429 Too Many Requests)
Billingo permite 120 solicitudes por minuto. Generar muchas facturas en rápida sucesión puede superar este límite.
Solución: Espera 60 segundos y vuelve a intentarlo. Para la generación masiva de facturas, escalona las solicitudes.
Factura no HUF: "conversion_rate required"
Billingo requiere un tipo de cambio a HUF para todas las monedas que no sean HUF.
Solución: CADENSA gestiona esto automáticamente (vía API Frankfurter). Si aparece este error, comprueba la conectividad de red a api.frankfurter.app. Si la API está bloqueada, CADENSA usa tipos de respaldo predefinidos.
Billingo vs. Lexoffice
| Función | Billingo 🇭🇺 | Lexoffice 🇩🇪 |
|---|---|---|
| Mercado | Hungría | DE / AT / CH |
| Estándar legal | NAV Online Számla 3.0 | ZUGFeRD / E-Rechnung |
| Autenticación | Clave API (v3) | Token Bearer (clave API) |
| Modo sandbox | Disponible |  No disponible |
| Selector de socios | Endpoint /partners | Endpoint /contacts |
| Generación de PDF | Síncrona | Asíncrona (sondeo hasta 30s) |
| Finalización de factura | Automática | Explícita (?finalize=true) |
| Moneda no doméstica | Tipo de cambio automático (MNB vía Frankfurter) | Soportado de forma nativa |
Páginas Relacionadas
- Configuración del Proveedor de Facturas — comparar todos los proveedores, configurar clave API y valores por defecto
- Generación de Facturas — cómo generar facturas desde entradas de tiempo
- Planes de Suscripción — qué plan de CADENSA se requiere