API de Fatura QR Suíça: Gere Faturas Conformes em Segundos
API RESTful para geração de faturas QR suíças. Compatível com ISO 20022, suporte multi-idioma, pronto para QR-IBAN. Uma chamada de API, PDF totalmente conforme.

Desenvolvendo recursos de faturamento para o mercado suíço? Pare de lutar com especificações QR-Rechnung e padrões ISO 20022. Nossa API para desenvolvedores gera faturas QR suíças conformes com uma única chamada—sem bibliotecas complexas, sem dores de cabeça com conformidade.
Seja construindo uma plataforma SaaS, integrando faturamento ao seu ERP, ou criando uma ferramenta para freelancers, você terá faturas QR totalmente conformes funcionando em menos de 30 minutos.
Por Que Usar uma API em Vez de Desenvolver Internamente?
A geração de faturas QR suíças parece simples até você mergulhar nos detalhes. Veja o que você realmente enfrenta ao construir do zero:
Criado para Desenvolvedores Profissionais
Tudo que você precisa para gerar faturas QR suíças conformes, mantido e atualizado automaticamente.
Suporte a QR-IBAN e IBAN Regular
Ambos os métodos de pagamento funcionam perfeitamente. QR-IBAN (IID 30000-31999) para reconciliação automatizada com referências de 27 dígitos. IBAN Regular com Referência de Credor ou sem referência para faturamento simples.
- Validação automática de formato IBAN
- Cálculo de dígito verificador incluído
- Validação de número de referência por tipo de IBAN
- Sem validação manual necessária
Endereços Estruturados Prontos para 2025
Atualização crítica: A partir de 21 de novembro de 2025, faturas QR exigem endereços estruturados. Nossa API já suporta o novo formato.
- Formato de endereço estruturado (tipo S)
- Nome da rua e número do prédio separados
- Validação de código postal e cidade
- Suporte a código de país
Geração de Faturas Multi-Idioma
Gere faturas em todos os idiomas oficiais suíços mais inglês. O idioma afeta rótulos, formatação e exibição de datas.
- Alemão (Deutsch) – QR-Rechnung
- Francês (Français) – Facture QR
- Italiano (Italiano) – Fattura QR
- Inglês – QR Invoice
Tratamento Inteligente de Referências
Todos os formatos de referência suportados com validação automática e cálculo de dígito verificador.
- Referência QR (27 dígitos) com dígito verificador automático
- Referência de Credor (ISO 11649, 5-25 caracteres)
- Opção sem referência para faturamento simples
- Validação de formato contra tipo de IBAN
Gestão de IVA Integrada
IVA suíço nas taxas padrão ou taxas personalizadas. Cálculo automático e formatação no padrão suíço.
- Taxas padrão (8.1%, 2.6%, 3.8%)
- Taxas de IVA personalizadas suportadas
- Múltiplas taxas de IVA por fatura
- Cálculo automático de bruto e líquido
Opções de Marca Personalizada
Faturas profissionais com sua identidade de marca e integração de gestão de documentos.
- Integração de logotipo (PNG, máx 2MB)
- Nomes de arquivo PDF personalizados
- Controle de numeração de faturas
- Atribuição de ID interno
Teste a API Agora Mesmo
Sem autenticação necessária para testes. Copie este comando e execute no seu 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
}
]
}
}'
Você receberá uma fatura PDF completa com código QR escaneável. Sem necessidade de chave de API para testes.
Parâmetros de Requisição Explicados
Estrutura JSON simples com campos obrigatórios e opcionais.
Campos Obrigatórios
{
"user_details": {
"name": "Nome do credor (máx 70 caracteres)",
"address": "Rua e número",
"zip": "Código postal",
"city": "Nome da cidade",
"iban": "CH76 0070 0112 3456 7890 1"
},
"customer_details": {
"name": "Nome do devedor (máx 70 caracteres)",
"address": "Rua e número",
"zip": "Código postal",
"city": "Nome da cidade"
},
"invoice_items": [
{
"description": "Serviço ou produto",
"quantity": 1.0,
"unit_price": 100.00
}
]
}
Parâmetros Opcionais
{
"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"
}
Tratamento de Resposta
Sucesso (HTTP 200):
{
"result": {
"pdf_url": "https://storage.googleapis.com/...",
"invoice_id": "abc123",
"total_amount": 1275.00
}
}
Erro (HTTP 400):
{
"error": {
"code": "INVALID_IBAN",
"message": "IBAN check digit validation failed"
}
}
A URL do PDF permanece acessível por 30 dias. Baixe e armazene no seu sistema imediatamente.
Implementação na Sua Linguagem
Exemplos prontos para copiar em JavaScript, Python, PHP, Ruby, Go e 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 Comuns & Padrões de Integração
Cenários reais onde nossa API resolve desafios de faturamento suíço para desenvolvedores e empresas.
Adicione suporte ao mercado suíço. Códigos QR facilitam pagamentos via escaneamento no app bancário.
Conecte sistemas existentes à geração automática de faturas. Criação de faturas via webhook com dados do CRM.
Suporte multi-idioma, tratamento correto de IVA, PDFs profissionais. Conformidade suíça tratada automaticamente.
Ofereça método de pagamento "Fatura" para B2B. Gere faturas QR imediatamente após confirmação do pedido.
Automatize cobrança de taxas de associação. Referências QR únicas para correspondência automática de pagamentos.
Gere faturas em qualquer lugar. Integração leve de API para apps iOS e Android.
Entendendo QR-IBAN vs IBAN Regular
Isso confunde a maioria dos desenvolvedores inicialmente. Aqui está a diferença prática:
Quando Usar QR-IBAN
Use QR-IBAN quando: Você precisa de reconciliação automática de pagamentos. A referência QR de 27 dígitos conecta pagamentos recebidos a faturas específicas automaticamente. Seu banco faz a correspondência da referência e notifica qual fatura foi paga.
Como reconhecer QR-IBAN: Os caracteres 5º a 9º (IID) variam de 30000 a 31999.
- Exemplo: CH12 30123 4567 8901 2345 6 (30123 = QR-IID)
Como obter QR-IBAN: Entre em contato com seu banco suíço. Eles emitirão QR-IBANs junto com seus IBANs regulares. A maioria dos bancos suíços oferece isso gratuitamente para contas empresariais.
Quando Usar IBAN Regular
Use IBAN Regular quando: Faturamento simples é suficiente. Você faz correspondência manual de pagamentos recebidos com faturas, ou usa o campo Referência de Credor (formato ISO 11649) para correspondência semi-automatizada.
Reconhecimento de IBAN Regular: Formato padrão de IBAN suíço com IID fora do intervalo 30000-31999.
Compatibilidade de Referência
- QR-IBAN → Deve usar Referência QR (27 dígitos)
- IBAN Regular → Pode usar Referência de Credor ou sem referência
A API valida isso automaticamente. Passou uma Referência QR com IBAN regular? Você receberá um erro antes de gerar uma fatura inválida.
Implementação Pronta para Produção
Padrões profissionais para tratamento de erros, testes, desempenho e monitoramento.
Tratamento de Erros
Sempre envolva chamadas de API em blocos try-catch. Registre erros com contexto incluindo número da fatura e ID do cliente.
- INVALID_IBAN – Formato ou dígito verificador errado
- REFERENCE_MISMATCH – Referência QR com IBAN regular
- INVALID_AMOUNT – Total negativo ou zero
- MISSING_FIELD – Parâmetro obrigatório faltando
Estratégia de Testes
Abordagem de testes em três fases para integração e implantação confiáveis.
- Desenvolvimento: Endpoint de teste gratuito com dados falsos
- Staging: Formatos IBAN reais com clientes fictícios
- Produção: Lançamento suave com testes internos primeiro
- Verifique códigos QR em múltiplos apps bancários
Otimização de Desempenho
Estratégias para manter tempos de resposta rápidos e lidar com altos volumes eficientemente.
- Processamento assíncrono: Enfileire jobs, não bloqueie requisições
- Cache: Armazene URLs de PDF (válidos por 30 dias)
- Geração em lote: Requisições paralelas com limites de taxa
- Entre em contato para limites de taxa enterprise
Monitoramento
Rastreie métricas-chave e configure alertas para confiabilidade em produção.
- Taxa de sucesso: Deve ser >99,5%
- Tempo de resposta: Média <2 segundos
- Tipos de erro: Rastreie padrões e picos
- Downloads de fatura: Monitore acesso aos PDFs
Perguntas Frequentes
Por que meu IBAN não está funcionando?
Primeiro, verifique se é um IBAN suíço ou de Liechtenstein (começa com CH ou LI). Faturas QR suportam apenas esses países. Segundo, verifique se você não está misturando tipos de IBAN—Referências QR exigem QR-IBAN, não IBAN regular.
Preciso de uma conta bancária especial?
Nenhuma conta especial é necessária para faturas com IBAN regular. Para faturas QR-IBAN com correspondência automática de pagamentos, entre em contato com seu banco para ativar o serviço QR-IBAN. A maioria das contas empresariais suíças inclui isso.
Qual é o prazo de transição para endereços estruturados?
Obrigatório a partir de 21 de novembro de 2025. Conformidade total exigida até 30 de setembro de 2026. Nossa API já suporta o formato estruturado—você está coberto.
Posso usar IBANs internacionais?
Não. A especificação da fatura QR suíça aceita apenas IBANs suíços (CH) e de Liechtenstein (LI). Para faturamento internacional, considere faturas SEPA.
Como calculo o dígito verificador da Referência QR?
Você não precisa. Passe sua referência de 26 dígitos e calculamos o 27º dígito (Módulo 10, recursivo). A API trata a validação do dígito verificador tanto para IBAN quanto para referência.
E se o app bancário do meu cliente não reconhecer o código QR?
Isso indica: (1) problema de qualidade do código QR na impressão/exibição do PDF, (2) geração de código QR não conforme, ou (3) app bancário desatualizado. Nossa API gera códigos QR totalmente conformes testados com todos os principais apps bancários suíços. Garanta que os clientes escaneiem do PDF original, não de uma fotocópia de baixa qualidade.
Posso personalizar o layout da fatura?
Logotipo e cores sim, layout estrutural não. Faturas QR suíças seguem requisitos rigorosos de formatação para compatibilidade bancária. Você pode adicionar seu logotipo, mas o posicionamento do boleto de pagamento e do código QR são regulamentados.
Qual é a disponibilidade da API?
Mantemos 99,9% de uptime. São menos de 9 horas de indisponibilidade por ano. Clientes enterprise têm suporte prioritário e podem solicitar infraestrutura dedicada.
Quão rápido posso integrar isso?
A maioria dos desenvolvedores completa a integração básica em 2-4 horas. Uma implementação pronta para produção com tratamento de erros, integração de webhook e testes geralmente leva 1-2 dias.
Preços Simples e Transparentes
Pague apenas pelo que usar. Descontos por volume disponíveis para aplicações de alto volume.
Teste Gratuito
- Faturas de teste ilimitadas
- Sem autenticação necessária
- Todos os recursos disponíveis
- Perfeito para prova de conceito
Produção
- Pague por fatura gerada
- Descontos por volume disponíveis
- Todos os recursos incluídos
- Atualizações de conformidade 2025 automáticas
- Suporte por email incluído
- Documentação completa
Enterprise
- Infraestrutura dedicada
- Suporte prioritário
- SLAs personalizados
- Limites de taxa maiores
- Ideal para fornecedores de ERP
- Plataformas de alto volume
Comece a Construir Hoje
Teste imediatamente sem cadastro. Gere sua primeira fatura QR suíça conforme nos próximos 5 minutos.
Pronto para integrar faturamento QR suíço?
- Teste imediatamente: Copie o comando curl acima e execute no seu terminal
- Revise a documentação: Referência completa da API com exemplos
- Obtenha sua chave de API: Solicite acesso agora
Dúvidas sobre implementação? Nossa equipe de suporte ao desenvolvedor responde em 24 horas.
Email support@magicheidi.ch com seu caso de uso.
Criado por desenvolvedores, para desenvolvedores. Entendemos a complexidade do faturamento suíço porque resolvemos isso para nós mesmos. Agora estamos compartilhando essa solução com você.
Teste a API gratuitamente – sem cartão de crédito, sem cadastro necessário para testes.