Magic Heidi API de factura QR suiza: preparar la integración
Define contrato, acceso de prueba, cuenta, referencias, validación y PDF antes de integrar generación de facturas QR suizas.
Fundador de Magic Heidi
Al desarrollar facturación para Suiza, separa generación del PDF, sección Swiss QR y conciliación de pagos. Son tareas distintas. Solo puedes estimar la integración después de revisar contrato técnico, modelo de datos y pruebas.
Primero confirma contrato y acceso
Estado de la fuente alemana: 1 de noviembre de 2026. Esta página es una orientación técnica, no una especificación aprobada de una API pública. Antes de integrar necesitas el contrato actualmente admitido, condiciones de acceso y una vía de prueba expresamente autorizada. Escribe a hello@magicheidi.ch indicando caso de uso y volumen previsto.
Las versiones anteriores de esta página y del artículo de blog contenían ejemplos de solicitud y respuesta incompatibles. No son una base fiable para producción. Deben confirmarse nombres de campos, formato de fecha, escala del IVA y estructura de respuesta antes de escribir un cliente.
No se promete un endpoint público gratuito, método concreto de autenticación, límites, precio, SLA ni caducidad de enlaces PDF. No envíes datos reales de clientes, pacientes o cuentas a un endpoint sin una prueba acordada.
Qué debe especificar el contrato
| Área | Qué confirmar antes de programar |
|---|---|
| Solicitud | Campos obligatorios, tipos, fecha, divisa y número de factura |
| IVA | Representación decimal o porcentual, redondeo, bruto/neto y varios tipos |
| Dirección | Componentes separados, país y validación |
| Cuenta y referencia | IBAN admitidas, QRR/SCOR/NON, controles y mensaje opcional |
| Respuesta | Ruta JSON real al PDF, estados, errores y autorización de descarga |
| Operación | Autenticación, límites, tiempos de espera, reintentos y prevención de duplicados |
| Datos | Ubicación, acceso, eliminación, vigencia de enlaces y archivo propio |
Pruebas de aceptación
- Usa solo llamadas de prueba acordadas y no facturables, con datos sintéticos.
- Comprueba éxito y errores de validación contra la respuesta real. No adivines campos, rutas JSON ni códigos de error.
- Descarga el PDF y revisa sumas, redondeos, idioma y tratamiento fiscal.
- Lee el contenido QR y compara cuenta, referencia, divisa y direcciones con las especificaciones SIX actuales.
- Prueba IBAN inválida, referencia incompatible con cuenta, dirección incompleta y divisa no admitida. Un HTTP de éxito no demuestra factura correcta.
- Antes de reintentar, acuerda cómo evitar PDF o numeración duplicados. No registres en logs los datos personales completos de facturación.
Un servicio autorizado podría incorporarse a facturación existente, gestión de socios o pedidos. Pero un PDF QR no recibe dinero ni confirma un cobro: la conciliación exige además datos bancarios y un proceso de asignación probado.
QR-IBAN y referencias
Utiliza la QR-IBAN cuando el proceso acordado use QRR, referencia QR de 27 dígitos. En una cuenta CH/LI, su identificador IID en las posiciones 5–9 está entre 30000 y 31999. Obtén los datos de tu banco; no inventes una IBAN de ejemplo ni uses una cuenta real ajena para probar. Condiciones y activación dependen del instituto.
Una IBAN ordinaria CH/LI utiliza SCOR, referencia del acreedor ISO 11649 que empieza por RF, o NON, sin referencia estructurada. También puede contribuir a la conciliación con un proceso compatible. Una QRR con IBAN ordinaria no es válida. El contrato debe especificar cómo devuelve el servicio ese error: no se publica aquí un código supuesto.
Factura internacional frente a sección QR suiza
La sección Swiss QR requiere cuenta CH/LI y CHF o EUR. Eso no impide facturar a clientes de otros países. Para otras divisas o cuentas no aptas para QR necesitas un bloque de pago distinto y adecuado.
El estándar QR sustituyó los antiguos boletines el 1 de octubre de 2022; no exige QR en todo documento de factura. Mantén direcciones estructuradas y comprueba las guías SIX y transiciones aplicables. Ningún servicio transforma automáticamente cualquier entrada en una factura legalmente correcta.
Siguiente paso: solicita contrato y prueba autorizada mediante hello@magicheidi.ch. Aclara acceso, privacidad y facturación antes de escribir un cliente en JavaScript, Python u otro lenguaje. Solo después acepta la integración con pruebas reproducibles.