API de Factura QR Suiza: Genera Facturas Conformes en Segundos
API RESTful para desarrolladores que genera facturas QR suizas. Cumple ISO 20022, soporte multiidioma, compatible QR-IBAN. Una llamada API, PDF totalmente conforme.

¿Desarrollando funciones de facturación para el mercado suizo? Deje de luchar con las especificaciones QR-Rechnung y los estándares ISO 20022. Nuestra API genera facturas QR suizas conformes con una sola llamada—sin bibliotecas complejas, sin dolores de cabeza de cumplimiento.
Ya sea que esté construyendo una plataforma SaaS, integrando facturación en su ERP o creando una herramienta para freelancers, tendrá facturas QR totalmente conformes funcionando en menos de 30 minutos.
¿Por Qué Usar una API en Lugar de Desarrollar Internamente?
La generación de facturas QR suizas parece simple hasta que profundiza en los detalles. Esto es lo que implica si lo construye usted mismo:
Diseñada para Desarrolladores Profesionales
Todo lo que necesita para generar facturas QR suizas conformes, mantenido y actualizado automáticamente.
Soporte QR-IBAN e IBAN Regular
Ambos métodos de pago funcionan perfectamente. QR-IBAN (IID 30000-31999) para conciliación automatizada con referencias de 27 dígitos. IBAN regular con Referencia de Acreedor o sin referencia para facturación simple.
- Validación automática de formato IBAN
- Cálculo de dígito de control incluido
- Validación de número de referencia por tipo de IBAN
- Sin validación manual requerida
Direcciones Estructuradas Listas para 2025
Actualización crítica: Desde el 21 de noviembre de 2025, las facturas QR requieren direcciones estructuradas. Nuestra API ya soporta el nuevo formato.
- Formato de dirección estructurada (tipo S)
- Nombre de calle y número separados
- Validación de código postal y ciudad
- Soporte de código de país
Generación de Facturas Multiidioma
Genere facturas en todos los idiomas oficiales suizos más inglés. El idioma afecta etiquetas, formato y visualización de fechas.
- Alemán (Deutsch) – QR-Rechnung
- Francés (Français) – Facture QR
- Italiano (Italiano) – Fattura QR
- Inglés – QR Invoice
Gestión Inteligente de Referencias
Todos los formatos de referencia soportados con validación automática y cálculo de dígito de control.
- Referencia QR (27 dígitos) con dígito de control automático
- Referencia de Acreedor (ISO 11649, 5-25 caracteres)
- Opción sin referencia para facturación simple
- Validación de formato contra tipo de IBAN
Gestión de IVA Integrada
IVA suizo a tasas estándar o personalizadas. Cálculo automático y formato estándar suizo.
- Tasas estándar (8.1%, 2.6%, 3.8%)
- Tasas de IVA personalizadas soportadas
- Múltiples tasas de IVA por factura
- Cálculo automático bruto y neto
Opciones de Marca Personalizada
Facturas profesionales con su identidad de marca e integración de gestión documental.
- Integración de logo (PNG, máx 2MB)
- Nombres de archivo PDF personalizados
- Control de numeración de facturas
- Asignación de ID interno
Pruebe la API Ahora Mismo
No requiere autenticación para pruebas. Copie este comando y ejecútelo en su terminal:
curl --location --request POST \
'https://europe-west6-magic-heidi.cloudfunctions.net/create_invoice_abstract_v1d' \
--header 'Content-Type: application/json' \
--data-raw '{
"data": {
"user_details": {
"name": "Your Company GmbH",
"address": "Bahnhofstrasse 1",
"zip": "8001",
"city": "Zürich",
"iban": "CH0700700112900411647"
},
"customer_details": {
"name": "Customer AG",
"address": "Rue du Rhône 1",
"zip": "1204",
"city": "Genève"
},
"invoice_items": [
{
"description": "Software Development",
"quantity": 8.5,
"unit_price": 150.00
}
]
}
}'
Recibirá una factura PDF completa con código QR escaneable. No necesita clave API para pruebas.
Parámetros de Solicitud Explicados
Estructura JSON simple con campos obligatorios y opcionales.
Campos Obligatorios
{
"user_details": {
"name": "Nombre del acreedor (máx 70 caracteres)",
"address": "Calle y número",
"zip": "Código postal",
"city": "Ciudad",
"iban": "CH76 0070 0112 3456 7890 1"
},
"customer_details": {
"name": "Nombre del deudor (máx 70 caracteres)",
"address": "Calle y número",
"zip": "Código postal",
"city": "Ciudad"
},
"invoice_items": [
{
"description": "Servicio o producto",
"quantity": 1.0,
"unit_price": 100.00
}
]
}
Parámetros Opcionales
{
"invoice_number": "INV-2024-001",
"invoice_date": "2024-01-15",
"reference": "210000000003139471430009017",
"language": "de",
"currency": "CHF",
"vat_rate": 8.1,
"filename": "invoice_customer_2024_001",
"logo_url": "https://yoursite.com/logo.png"
}
Manejo de Respuestas
Éxito (HTTP 200):
{
"result": {
"pdf_url": "https://storage.googleapis.com/...",
"invoice_id": "abc123",
"total_amount": 1275.00
}
}
Error (HTTP 400):
{
"error": {
"code": "INVALID_IBAN",
"message": "IBAN check digit validation failed"
}
}
La URL del PDF permanece accesible durante 30 días. Descárguelo y almacénelo en su sistema inmediatamente.
Implementación en Su Lenguaje
Ejemplos listos para copiar en JavaScript, Python, PHP, Ruby, Go y Java.
JavaScript / Node.js
const axios = require('axios');
async function generateInvoice() {
const response = await axios.post(
'https://europe-west6-magic-heidi.cloudfunctions.net/create_invoice_abstract_v1d',
{
data: {
user_details: {
name: "Tech Solutions AG",
address: "Technoparkstrasse 1",
zip: "8005",
city: "Zürich",
iban: "CH0700700112900411647"
},
customer_details: {
name: "Client Corp",
address: "Avenue de la Gare 10",
zip: "1003",
city: "Lausanne"
},
invoice_items: [
{
description: "API Integration Service",
quantity: 5,
unit_price: 200.00
}
]
}
}
);
return response.data.result.pdf_url;
}
Python
import requests
import json
def generate_qr_invoice():
url = "https://europe-west6-magic-heidi.cloudfunctions.net/create_invoice_abstract_v1d"
payload = {
"data": {
"user_details": {
"name": "Your Company GmbH",
"address": "Bahnhofstrasse 1",
"zip": "8001",
"city": "Zürich",
"iban": "CH0700700112900411647"
},
"customer_details": {
"name": "Customer Name",
"address": "Street Address",
"zip": "1000",
"city": "Lausanne"
},
"invoice_items": [
{
"description": "Consulting Services",
"quantity": 10,
"unit_price": 180.00
}
]
}
}
response = requests.post(url, json=payload)
return response.json()['result']['pdf_url']
PHP
<?php
$curl = curl_init();
$data = [
'data' => [
'user_details' => [
'name' => 'Swiss Services SA',
'address' => 'Route de Berne 5',
'zip' => '1010',
'city' => 'Lausanne',
'iban' => 'CH0700700112900411647'
],
'customer_details' => [
'name' => 'Client Company',
'address' => 'Via Nassa 1',
'zip' => '6900',
'city' => 'Lugano'
],
'invoice_items' => [
[
'description' => 'Web Development',
'quantity' => 20,
'unit_price' => 125.00
]
]
]
];
curl_setopt_array($curl, [
CURLOPT_URL => 'https://europe-west6-magic-heidi.cloudfunctions.net/create_invoice_abstract_v1d',
CURLOPT_RETURNTRANSFER => true,
CURLOPT_POST => true,
CURLOPT_POSTFIELDS => json_encode($data),
CURLOPT_HTTPHEADER => ['Content-Type: application/json']
]);
$response = curl_exec($curl);
$result = json_decode($response, true);
echo $result['result']['pdf_url'];
?>
Ruby
require 'net/http'
require 'json'
require 'uri'
uri = URI('https://europe-west6-magic-heidi.cloudfunctions.net/create_invoice_abstract_v1d')
payload = {
data: {
user_details: {
name: "Development Studio GmbH",
address: "Seestrasse 20",
zip: "8002",
city: "Zürich",
iban: "CH0700700112900411647"
},
customer_details: {
name: "Client Business AG",
address: "Spalenring 5",
zip: "4055",
city: "Basel"
},
invoice_items: [
{
description: "Design Services",
quantity: 15,
unit_price: 160.00
}
]
}
}
response = Net::HTTP.post(uri, payload.to_json,
'Content-Type' => 'application/json')
result = JSON.parse(response.body)
puts result['result']['pdf_url']
Go
package main
import (
"bytes"
"encoding/json"
"net/http"
)
type InvoiceRequest struct {
Data struct {
UserDetails struct {
Name string `json:"name"`
Address string `json:"address"`
Zip string `json:"zip"`
City string `json:"city"`
IBAN string `json:"iban"`
} `json:"user_details"`
CustomerDetails struct {
Name string `json:"name"`
Address string `json:"address"`
Zip string `json:"zip"`
City string `json:"city"`
} `json:"customer_details"`
InvoiceItems []struct {
Description string `json:"description"`
Quantity float64 `json:"quantity"`
UnitPrice float64 `json:"unit_price"`
} `json:"invoice_items"`
} `json:"data"`
}
func generateInvoice() (string, error) {
url := "https://europe-west6-magic-heidi.cloudfunctions.net/create_invoice_abstract_v1d"
var req InvoiceRequest
req.Data.UserDetails.Name = "Swiss Tech AG"
req.Data.UserDetails.Address = "Technoparkstrasse 1"
req.Data.UserDetails.Zip = "8005"
req.Data.UserDetails.City = "Zürich"
req.Data.UserDetails.IBAN = "CH0700700112900411647"
jsonData, _ := json.Marshal(req)
resp, err := http.Post(url, "application/json", bytes.NewBuffer(jsonData))
// Handle response...
return "pdf_url", err
}
Java
import java.net.http.*;
import java.net.URI;
import org.json.JSONObject;
public class QRInvoiceGenerator {
public static String generateInvoice() throws Exception {
String url = "https://europe-west6-magic-heidi.cloudfunctions.net/create_invoice_abstract_v1d";
JSONObject payload = new JSONObject()
.put("data", new JSONObject()
.put("user_details", new JSONObject()
.put("name", "Software GmbH")
.put("address", "Europaallee 1")
.put("zip", "8004")
.put("city", "Zürich")
.put("iban", "CH0700700112900411647"))
.put("customer_details", new JSONObject()
.put("name", "Client AG")
.put("address", "Bahnhofstrasse 10")
.put("zip", "3011")
.put("city", "Bern"))
.put("invoice_items", new JSONArray()
.put(new JSONObject()
.put("description", "Development")
.put("quantity", 40)
.put("unit_price", 150.00))));
HttpRequest request = HttpRequest.newBuilder()
.uri(URI.create(url))
.header("Content-Type", "application/json")
.POST(HttpRequest.BodyPublishers.ofString(payload.toString()))
.build();
HttpResponse<String> response = HttpClient.newHttpClient()
.send(request, HttpResponse.BodyHandlers.ofString());
JSONObject result = new JSONObject(response.body());
return result.getJSONObject("result").getString("pdf_url");
}
}
Casos de Uso Comunes y Patrones de Integración
Escenarios reales donde nuestra API resuelve los desafíos de facturación suiza para desarrolladores y empresas.
Añada soporte para el mercado suizo. Los códigos QR facilitan el pago a clientes mediante escaneo en apps bancarias.
Conecte sistemas existentes a generación automática de facturas. Creación de facturas por webhook con datos del CRM.
Soporte multiidioma, gestión correcta de IVA, PDFs profesionales. Cumplimiento suizo gestionado automáticamente.
Ofrezca método de pago "Factura" para B2B. Genere facturas QR inmediatamente tras confirmar el pedido.
Automatice el cobro de cuotas. Referencias QR únicas para conciliación automática de pagos.
Genere facturas en movimiento. Integración API ligera para apps iOS y Android.
Entendiendo QR-IBAN vs IBAN Regular
Esto confunde a la mayoría de desarrolladores al principio. Aquí está la diferencia práctica:
Cuándo Usar QR-IBAN
Use QR-IBAN cuando: Necesite conciliación de pagos automatizada. La referencia QR de 27 dígitos conecta los pagos entrantes con facturas específicas automáticamente. Su banco hace coincidir la referencia y le notifica qué factura fue pagada.
Cómo reconocer QR-IBAN: Los caracteres 5º a 9º (IID) van de 30000 a 31999.
- Ejemplo: CH12 30123 4567 8901 2345 6 (30123 = QR-IID)
Cómo obtener QR-IBAN: Contacte a su banco suizo. Le emitirán QR-IBANs junto con sus IBANs regulares. La mayoría de bancos suizos ofrecen esto gratis para cuentas empresariales.
Cuándo Usar IBAN Regular
Use IBAN Regular cuando: La facturación simple es suficiente. Usted concilia manualmente los pagos entrantes con las facturas, o usa el campo de Referencia de Acreedor (formato ISO 11649) para conciliación semiautomática.
Reconocimiento de IBAN regular: Formato IBAN suizo estándar con IID fuera del rango 30000-31999.
Compatibilidad de Referencias
- QR-IBAN → Debe usar Referencia QR (27 dígitos)
- IBAN Regular → Puede usar Referencia de Acreedor o sin referencia
La API valida esto automáticamente. ¿Pasa una Referencia QR con un IBAN regular? Recibirá un error antes de generar una factura inválida.
Implementación Lista para Producción
Patrones profesionales para manejo de errores, pruebas, rendimiento y monitoreo.
Manejo de Errores
Siempre envuelva las llamadas API en bloques try-catch. Registre errores con contexto incluyendo número de factura e ID de cliente.
- INVALID_IBAN – Formato o dígito de control incorrecto
- REFERENCE_MISMATCH – Referencia QR con IBAN regular
- INVALID_AMOUNT – Total negativo o cero
- MISSING_FIELD – Parámetro requerido faltante
Estrategia de Pruebas
Enfoque de pruebas en tres fases para integración y despliegue confiables.
- Desarrollo: Endpoint de pruebas gratis con datos ficticios
- Staging: Formatos IBAN reales con clientes de prueba
- Producción: Lanzamiento suave con pruebas internas primero
- Verifique códigos QR en múltiples apps bancarias
Optimización de Rendimiento
Estrategias para mantener tiempos de respuesta rápidos y manejar altos volúmenes eficientemente.
- Procesamiento async: Encole trabajos, no bloquee solicitudes
- Caché: Almacene URLs de PDF (válidas 30 días)
- Generación por lotes: Solicitudes paralelas con límites
- Contáctenos para límites empresariales
Monitoreo
Rastree métricas clave y configure alertas para confiabilidad en producción.
- Tasa de éxito: Debe ser >99.5%
- Tiempo de respuesta: Promedio <2 segundos
- Tipos de error: Rastree patrones y picos
- Descargas de facturas: Monitoree acceso a PDF
Preguntas Frecuentes
¿Por qué no funciona mi IBAN?
Primero, verifique que sea un IBAN suizo o de Liechtenstein (comienza con CH o LI). Las facturas QR solo soportan estos países. Segundo, compruebe si está mezclando tipos de IBAN—las Referencias QR requieren QR-IBAN, no IBAN regular.
¿Necesito una cuenta bancaria especial?
No se necesita cuenta especial para facturas con IBAN regular. Para facturas QR-IBAN con conciliación automática de pagos, contacte a su banco para activar el servicio QR-IBAN. La mayoría de cuentas empresariales suizas lo incluyen.
¿Cuál es la fecha límite para direcciones estructuradas?
Obligatorio desde el 21 de noviembre de 2025. Cumplimiento total requerido para el 30 de septiembre de 2026. Nuestra API ya soporta el formato estructurado—está cubierto.
¿Puedo usar IBANs internacionales?
No. La especificación de factura QR suiza solo acepta IBANs suizos (CH) y de Liechtenstein (LI). Para facturación internacional, considere facturas SEPA en su lugar.
¿Cómo calculo el dígito de control de la Referencia QR?
No necesita hacerlo. Pase su referencia de 26 dígitos y calculamos el 27º dígito (Módulo 10, recursivo). La API maneja la validación del dígito de control tanto para IBAN como para referencia.
¿Qué pasa si la app bancaria de mi cliente no reconoce el código QR?
Esto indica: (1) problema de calidad del código QR al imprimir/mostrar PDF, (2) generación de código QR no conforme, o (3) app bancaria desactualizada. Nuestra API genera códigos QR totalmente conformes probados con todas las principales apps bancarias suizas. Asegúrese de que los clientes escaneen desde el PDF original, no de una fotocopia de baja calidad.
¿Puedo personalizar el diseño de la factura?
Logo y colores sí, diseño estructural no. Las facturas QR suizas siguen requisitos de formato estrictos para compatibilidad bancaria. Puede añadir su logo, pero el posicionamiento del recibo de pago y código QR están regulados.
¿Cuál es su tiempo de actividad de API?
Mantenemos 99.9% de uptime. Eso es menos de 9 horas de inactividad por año. Los clientes empresariales obtienen soporte prioritario y pueden solicitar infraestructura dedicada.
¿Qué tan rápido puedo integrar esto?
La mayoría de desarrolladores completan la integración básica en 2-4 horas. Una implementación lista para producción con manejo de errores, integración webhook y pruebas típicamente toma 1-2 días.
Precios Simples y Transparentes
Pague solo por lo que usa. Descuentos por volumen disponibles para aplicaciones de alto volumen.
Pruebas Gratis
- Facturas de prueba ilimitadas
- Sin autenticación requerida
- Todas las funciones disponibles
- Perfecto para prueba de concepto
Producción
- Pago por factura generada
- Descuentos por volumen disponibles
- Todas las funciones incluidas
- Actualizaciones 2025 automáticas
- Soporte por email incluido
- Documentación completa
Empresarial
- Infraestructura dedicada
- Soporte prioritario
- SLAs personalizados
- Límites de tasa mayores
- Ideal para proveedores ERP
- Plataformas de alto volumen
Comience a Desarrollar Hoy
Pruebe inmediatamente sin registro. Genere su primera factura QR suiza conforme en los próximos 5 minutos.
¿Listo para integrar facturación QR suiza?
- Pruebe inmediatamente: Copie el comando curl de arriba y ejecútelo en su terminal
- Revise la documentación: Referencia API completa con ejemplos
- Obtenga su clave API: Solicitar acceso ahora
¿Preguntas sobre implementación? Nuestro equipo de soporte para desarrolladores responde en 24 horas.
Envíe un email a support@magicheidi.ch con su caso de uso.
Desarrollado por desarrolladores, para desarrolladores. Entendemos la complejidad de la facturación suiza porque la hemos resuelto para nosotros mismos. Ahora compartimos esa solución con usted.
Pruebe la API gratis – sin tarjeta de crédito, sin registro requerido para pruebas.