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.

Geração de Fatura QR Suíça

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:

📋
Complexidade de ConformidadeGuia de Implementação de 67 páginas v2.3. Padrões ISO 20022, validação QR-IBAN, dígitos verificadores, endereços estruturados.
🔄
Manutenção ContínuaPadrões bancários suíços evoluem. A atualização de 2025 introduziu endereços estruturados, conjuntos de caracteres expandidos, novas regras de validação.
🧪
Carga de TestesCada combinação de tipo de IBAN, formato de referência, moeda e idioma precisa de testes. Mais casos extremos, taxas de IVA, formatação de PDF.
⏱️
Tempo de LançamentoConstruir do zero: 2-3 meses. Usando nossa API: Gere faturas em horas.
Recursos Completos

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
Início Rápido

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

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.

Exemplos de Código

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.

Tempo de resposta de 2 segundos
🔒 Compatível com ISO 20022
🌍 Multi-idioma pronto
Endereços estruturados 2025
💼
Plataformas SaaS de Faturamento

Adicione suporte ao mercado suíço. Códigos QR facilitam pagamentos via escaneamento no app bancário.

🔄
Integração com ERP e CRM

Conecte sistemas existentes à geração automática de faturas. Criação de faturas via webhook com dados do CRM.

👨‍💼
Ferramentas para Freelancers

Suporte multi-idioma, tratamento correto de IVA, PDFs profissionais. Conformidade suíça tratada automaticamente.

🛒
Checkout de E-commerce

Ofereça método de pagamento "Fatura" para B2B. Gere faturas QR imediatamente após confirmação do pedido.

🏢
Organizações de Membros

Automatize cobrança de taxas de associação. Referências QR únicas para correspondência automática de pagamentos.

📱
Aplicativos Móveis

Gere faturas em qualquer lugar. Integração leve de API para apps iOS e Android.

Detalhes Técnicos

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.

FAQ

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

CHF0/month
Faturas de Teste Ilimitadas
  • Faturas de teste ilimitadas
  • Sem autenticação necessária
  • Todos os recursos disponíveis
  • Perfeito para prova de conceito
Começar a Testar Agora

Enterprise

CHFPersonalizado/month
Infraestrutura Dedicada
  • Infraestrutura dedicada
  • Suporte prioritário
  • SLAs personalizados
  • Limites de taxa maiores
  • Ideal para fornecedores de ERP
  • Plataformas de alto volume
Contatar Vendas
🛡️Todos os planos incluem acesso completo à API, suporte multi-idioma, compatibilidade QR-IBAN e atualizações automáticas de conformidade.

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?

  1. Teste imediatamente: Copie o comando curl acima e execute no seu terminal
  2. Revise a documentação: Referência completa da API com exemplos
  3. 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.