Magic Heidi 
Está a desenvolver faturação para o mercado suíço? Separe geração de PDF, secção de pagamento Swiss QR e reconciliação de pagamentos. Esta página ajuda a definir requisitos e testes de aceitação de uma possível integração. O esforço só pode ser estimado depois de analisar contrato, modelo de dados e casos de teste.
Confirmar o estado da integração e o acesso
Situação em 1 de novembro de 2026: esta página é uma orientação técnica, não uma especificação aprovada de API pública. Antes de integrar, precisa do contrato atualmente suportado, das condições de acesso e de um procedimento de teste expressamente autorizado. Contacte a Magic Heidi com o caso de utilização e volume previsto.
Versões anteriores desta página e do artigo do blog continham exemplos contraditórios de pedidos e respostas. Não são uma base fiável para código de produção e não são mantidos como integração pronta a copiar. Confirme especialmente nomes de campos, formato de datas, representação do IVA e estrutura da resposta.
Não se garante um endpoint público gratuito de teste, método de autenticação, limite de pedidos, preço, SLA ou validade de ligações PDF. Sem um ambiente de teste acordado, não envie dados reais de clientes, pacientes ou contas bancárias para um endpoint.
O que o contrato aprovado deve definir
| Área | Confirmar antes de implementar |
|---|---|
| Pedido | Campos obrigatórios, tipos, formato de datas, moeda e número da fatura |
| IVA | Representação decimal ou percentual, arredondamento, modo bruto/líquido e múltiplas taxas |
| Morada | Componentes separados, país e regras de validação |
| Conta e referência | Tipos de IBAN suportados, QRR/SCOR/NON, dígitos de controlo e mensagem opcional |
| Resposta | Caminho JSON real para o PDF, estados e erros, autorização de descarga |
| Operação | Autenticação, limites, tempos de espera, repetições e proteção contra geração duplicada |
| Dados | Local de armazenamento, acesso, eliminação, validade de ligações e arquivo próprio |
Teste técnico de aceitação
- Use apenas chamadas de teste acordadas, não faturáveis, com dados sintéticos.
- Confira sucesso e erros de validação com a resposta real; não adivinhe campos ou códigos.
- Descarregue o PDF e reveja totais, arredondamento, idioma e dados fiscais.
- Leia os dados do QR e valide conta, referência, moeda e moradas segundo as regras atuais da SIX.
- Teste IBAN inválido, combinação conta/referência incompatível, morada em falta e moeda não suportada. Sucesso HTTP não prova uma fatura correta.
- Antes de repetir pedidos automaticamente, defina como evitar PDFs ou números de fatura duplicados. Não registe dados pessoais completos das faturas nos logs.
Casos de utilização
Um serviço de geração aprovado pode integrar-se num processo de faturação, gestão de associados ou processamento de encomendas. Um PDF QR não recebe pagamentos nem comprova recebimentos. A reconciliação automática exige também dados bancários adequados e um processo de associação testado.
QR-IBAN ou IBAN normal?
Quando usar QR-IBAN
Use QR-IBAN quando o processo acordado utiliza QRR. A referência QR de 27 dígitos ajuda a identificar a fatura. A reconciliação efetiva exige dados bancários e software: o PDF, por si só, não marca uma fatura como paga.
O IID, nas posições 5 a 9, situa-se entre 30000 e 31999. Verifique o QR-IBAN emitido pela instituição; não invente um IBAN para testes. Peça o QR-IBAN ao banco suíço. Condições e configuração dependem da instituição.
Quando usar IBAN normal
Pode bastar para faturação simples com associação manual dos recebimentos ou com referência de credor ISO 11649 para apoiar a reconciliação. Num IBAN suíço normal, o IID fica fora de 30000–31999.
Compatibilidade das referências
- QR-IBAN: exige referência QR de 27 dígitos.
- IBAN normal: pode utilizar referência de credor ou nenhuma referência.
Uma referência QR com IBAN normal não é uma combinação permitida. O contrato aprovado deve explicar como o serviço concreto comunica esse erro; não se pressupõe uma validação ou um código de erro específico.
Secção Swiss QR e faturação internacional
A secção de pagamento Swiss QR utiliza dados de conta CH ou LI e moedas CHF ou EUR. Isso não significa que só possa faturar a clientes desses países. Outras moedas ou contas não compatíveis exigem outra secção de pagamento adequada no documento.
A fatura QR substituiu os antigos boletins de pagamento em 1 de outubro de 2022; não é obrigatória em todos os documentos de faturação. Mantenha moradas estruturadas e confirme as instruções e transições SIX aplicáveis. Nenhum serviço transforma genericamente dados errados em faturas legalmente corretas.
Próximo passo
Solicite o contrato suportado e acesso de teste autorizado por hello@magicheidi.ch. Esclareça acesso, proteção de dados e faturação antes de escrever um cliente numa linguagem específica e de o aceitar com testes reproduzíveis. Para o processo sem integração, consulte a criação de faturas.