Respostas diretas para tesoureiros, operações de pagamento, engenheiros e auditores. As perguntas estão formuladas do jeito que as pessoas realmente perguntam. Para mais detalhes técnicos, consulte a Referência técnica.
Para líderes de tesouraria e finanças#
O que é pain.001, em um parágrafo?
pain.001 é a mensagem ISO 20022 que um cliente envia ao seu banco para iniciar transferências de crédito. É o sucessor XML de formatos como o SWIFT MT101 e arquivos planos domésticos. Seu banco a valida contra um esquema e um rulebook de esquema antes de aceitá-la. O Pain001 (o software) produz esses arquivos a partir dos dados que você já tem e comprova que são válidos antes do envio.
Qual é a diferença entre pain.001 e pain.008?
A direção do fluxo. pain.001 inicia transferências de crédito: você envia dinheiro. pain.008 inicia débitos diretos: você cobra valores que lhe são devidos sob um mandato. O Pain001 gera ambos: dez versões de pain.001 (de .001.03 a .001.12) e pain.008.001.02.
Ainda enviamos arquivos MT101. Quão urgente é a migração?
Urgente. A SWIFT aposentou as mensagens MT das categorias 1, 2 e 9 para instruções de pagamento interbancárias internacionais em novembro de 2025; os canais corporativos que ainda aceitam MT o fazem a critério de cada banco e com prazo contado. O loader MT101 converte fluxos MT101 existentes em pain.001 validado sem redigitar nada.
O que a exigência de endereços estruturados significa para nós?
A Swift planejava deixar de aceitar endereços postais totalmente não estruturados em pagamentos transfronteiriços CBPR+ em novembro de 2026. Em agosto de 2026, adiou essa data e anunciará a nova até dezembro de 2026, mas a regra não mudou: os endereços devem ser estruturados ou híbridos, com elementos discretos como cidade (<TwnNm>) e país (<Ctry>) em vez de linhas de texto livre. Se seus dados mestres guardam endereços como blocos de texto, o trabalho está nos seus dados, não na sua conexão bancária. Comece por aí. O briefing de 2026 cobre o cronograma em detalhes.
Quanto custa o Pain001?
Nada. O núcleo tem licença dupla Apache-2.0 / MIT; os pacotes complementares são Apache-2.0. Uso comercial, modificação e redistribuição são todos permitidos. Como referência de escala, apenas o SDK de tradução da SWIFT é listado por €10,000–30,000 ao ano.
Para operações de pagamento#
Por que os bancos rejeitam arquivos de pagamento?
Quatro causas recorrentes: violações de esquema (elemento errado, versão errada, namespace errado), identificadores inválidos (falhas de checksum de IBAN, BICs malformados), totais de controle quebrados (NbOfTxs / CtrlSum divergentes das transações) e caracteres fora do conjunto latino ISO 20022. O Pain001 verifica os quatro antes que o arquivo exista: validação por JSON Schema em cada registro, verificações mod-97 de IBAN e ISO 9362 de BIC, totais de controle recalculados, transliteração do conjunto de caracteres e validação XSD final do XML renderizado.
Podemos validar um arquivo sem gerar nada?
Sim. Use pain001 --dry-run (ou o subcomando validate, ou POST /api/v1/validate). Código de saída 0 significa válido; 1 significa falha de validação com erros em nível de campo. Integre-o à CI ou a uma checklist de pré-envio.
Quais rulebooks SEPA são cobertos?
Cinco rulebooks de esquema vêm incluídos: SEPA Credit Transfer (sepa-sct), SEPA Instant (sepa-inst), SEPA Direct Debit Core (sepa-sdd), SEPA B2B (sepa-b2b) e transferência de crédito transfronteiriça (xborder-ct). Use --scheme <name> --explain para ver cada regra aprovada ou reprovada.
Nossos dados vivem no Excel. Qual é o problema?
O Excel converte silenciosamente strings parecidas com IBAN em números. O loader de Excel lê .xlsx/.xlsm diretamente e interrompe imediatamente se colunas de IBAN contiverem células numéricas, de modo que a corrupção é capturada no carregamento, não no banco.
Como ele lida com um lote de 500,000 linhas?
--streaming processa a entrada em blocos com memória limitada (padrão de 1,000 transações), cada um emitido como seu próprio arquivo XML com totais de controle corretamente recalculados. Pelo mesmo motivo, a API REST oferece POST /api/v1/generate/async com polling de jobs.
Para engenheiros e arquitetos#
Como integramos: biblioteca, CLI ou API?
As três superfícies existem como cidadãs de primeira classe: uma API Python tipada, uma CLI com códigos de saída amigáveis à CI e um microsserviço FastAPI (pain001 serve) com endpoints síncronos, de jobs assíncronos, de health e de métricas Prometheus. O mesmo pipeline de validação por baixo, então os resultados nunca divergem entre as superfícies.
A geração de XML é mesmo segura contra arredondamento de float?
Os valores são decimal.Decimal de ponta a ponta na geração e na validação de esquema. São analisados como decimais exatos, somados como decimais exatos e renderizados sem representação em float. Os totais de controle são recalculados a partir dos registros validados, nunca aceitos da entrada.
Qual é a postura de segurança?
Todo o parsing de XML passa pelo defusedxml (bloqueando ataques XXE e de expansão de entidades); não há lxml na árvore de dependências. As entradas passam por um validador de path traversal. A imagem Docker roda sem root. Um SBOM CycloneDX é gerado para as releases do núcleo, e a descoberta de plugins de terceiros pode ser desativada por completo com PAIN001_DISABLE_PLUGINS=1.
Como a qualidade é imposta?
Cobertura de linhas e ramificações de 100% como portão rígido de CI no núcleo (verificável: 3,828 linhas, 926 ramificações a 100%), mypy estrito, cobertura de docstrings de 100%, linting de segurança com Bandit e pip-audit, e varredura CodeQL. Os pacotes complementares seguem a mesma disciplina de cobertura de 100%.
Podemos estendê-lo para um formato proprietário?
Sim, por meio de quatro grupos de entry points de plugin (pain001.loaders, pain001.validators, pain001.schemes, pain001.writers). O loader de Excel é ele próprio um plugin que usa o protocolo público, servindo também como implementação de referência.
Para auditores e compliance#
Podemos reproduzir um arquivo gerado no trimestre passado?
Sim. Fixe a versão do pacote, reproduza a mesma entrada e a saída é determinística. Como a toolchain é de código aberto, a trilha de auditoria se estende ao próprio caminho do código, não apenas a um atestado do fornecedor.
Os dados de pagamento saem do nosso ambiente?
Não. Todo componente (CLI, biblioteca, API REST, servidor MCP, LSP) executa localmente. Não há telemetria, callback SaaS nem serviço externo de validação. O servidor MCP fala apenas stdio e todas as suas 17 ferramentas são anotadas como somente leitura e idempotentes.
Quem mantém o Pain001?
Sebastien Rousseau, líder de engenharia fintech baseado em Londres, com contribuidores da comunidade. O desenvolvimento é público no GitHub, as releases são publicadas no PyPI e o changelog é versionado a cada release.