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.

Generación de Facturas QR Suizas

¿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:

📋
Complejidad de CumplimientoGuías de implementación de 67 páginas v2.3. Estándares ISO 20022, validación QR-IBAN, dígitos de control, direcciones estructuradas.
🔄
Mantenimiento ContinuoLos estándares bancarios suizos evolucionan. Solo la actualización 2025 introdujo direcciones estructuradas, conjuntos de caracteres expandidos, nuevas reglas de validación.
🧪
Carga de PruebasCada combinación de tipo de IBAN, formato de referencia, moneda e idioma necesita pruebas. Más casos extremos, tasas de IVA, formato PDF.
⏱️
Tiempo de LanzamientoConstruir desde cero: 2-3 meses. Usando nuestra API: Genere facturas en horas.
Funcionalidades Completas

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
Inicio Rápido

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

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.

Ejemplos de Código

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.

Respuesta en 2 segundos
🔒 Conforme ISO 20022
🌍 Listo para multiidioma
Direcciones estructuradas 2025
💼
Plataformas SaaS de Facturación

Añada soporte para el mercado suizo. Los códigos QR facilitan el pago a clientes mediante escaneo en apps bancarias.

🔄
Integración ERP y CRM

Conecte sistemas existentes a generación automática de facturas. Creación de facturas por webhook con datos del CRM.

👨‍💼
Herramientas para Freelancers

Soporte multiidioma, gestión correcta de IVA, PDFs profesionales. Cumplimiento suizo gestionado automáticamente.

🛒
Checkout de E-commerce

Ofrezca método de pago "Factura" para B2B. Genere facturas QR inmediatamente tras confirmar el pedido.

🏢
Organizaciones con Membresías

Automatice el cobro de cuotas. Referencias QR únicas para conciliación automática de pagos.

📱
Aplicaciones Móviles

Genere facturas en movimiento. Integración API ligera para apps iOS y Android.

Detalles Técnicos

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.

FAQ

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

CHF0/month
Facturas de Prueba Ilimitadas
  • Facturas de prueba ilimitadas
  • Sin autenticación requerida
  • Todas las funciones disponibles
  • Perfecto para prueba de concepto
Comenzar a Probar Ahora

Empresarial

CHFPersonalizado/month
Infraestructura Dedicada
  • Infraestructura dedicada
  • Soporte prioritario
  • SLAs personalizados
  • Límites de tasa mayores
  • Ideal para proveedores ERP
  • Plataformas de alto volumen
Contactar Ventas
🛡️Todos los planes incluyen acceso completo a la API, soporte multiidioma, compatibilidad QR-IBAN y actualizaciones automáticas de cumplimiento.

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?

  1. Pruebe inmediatamente: Copie el comando curl de arriba y ejecútelo en su terminal
  2. Revise la documentación: Referencia API completa con ejemplos
  3. 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.