Referência técnica do Pain001: CLI, API Python e REST

Esta referência documenta a interface de linha de comando, a API Python, o microsserviço REST e o pipeline de validação do pain001 v0.0.71. Cada flag, endpoint e comportamento listado aqui foi extraído do código entregue, não de aspirações.

O Pain001 suporta 12 definições de mensagem ISO 20022: de pain.001.001.03 a pain.001.001.13 (Customer Credit Transfer Initiation, onze versões) e pain.008.001.02 (Customer Direct Debit Initiation).

---

1. Interface de linha de comando#

O executável pain001 agrupa suas funcionalidades em subcomandos. Executá-lo apenas com flags de geração invoca generate implicitamente, de modo que a automação existente continua funcionando.

Opções de generate

Os códigos de saída são amigáveis à CI: 0 sucesso, 1 falha de validação, 2 erro de uso.

In the next release

These features are in development for the next pain001 release. They are not in pain001 0.0.71, the version this reference documents, and their names may change before they ship.

The Python API gains the matching process_files parameters: envelop_bah, xml_sign_key and xml_sign_cert.

Input normalisation gains formula injection shielding: cells starting with a formula trigger (=, +, -, @, tab, carriage return or line feed) are escaped with a leading single quote, preventing CSV injection (CWE-1236) when a file is opened in a spreadsheet.

---

2. API Python#

from pain001.core.core import process_files

# Generate a validated pain.001.001.09 file from CSV
process_files(
    xml_message_type="pain.001.001.09",
    xml_template_file_path="template.xml",
    xsd_schema_file_path="schema.xsd",
    data_file_path="payments.csv",
    output_dir="out",
)

Todo documento gerado passa por três camadas antes de ser gravado:

1. Validação de entrada: cada registro é verificado contra o JSON Schema do tipo de mensagem, com normalização de aliases de campo e verificações sintáticas de IBAN e BIC.
2. Rulebook de esquema (opcional): regras de SEPA SCT, SEPA Instant, SEPA SDD Core, SEPA B2B ou transferência de crédito transfronteiriça.
3. Validação XSD: o XML renderizado é validado contra o esquema oficial ISO 20022 via xmlschema antes que um único byte seja gravado em disco.

Os valores monetários são tratados como decimal.Decimal durante a geração do XML e a validação de esquema (nunca como floats IEEE 754), e os totais de controle NbOfTxs / CtrlSum são recalculados a partir dos registros validados, em vez de aceitos da entrada.

Além da geração de pain.001, a biblioteca principal também traz um parser e gerador de relatórios de status pain.002 (para que você possa ler a resposta de aceite/rejeição do banco) e um parser e gerador de extratos camt.053 para a conciliação de fim de dia, além de um VersionMapper que migra registros entre versões de mensagem.

---

3. Microsserviço REST#

pip install "pain001[api]"
pain001 serve --host 0.0.0.0 --port 8000

Todos os endpoints são montados em /api/v1 (com um alias sem versão /api):

A documentação interativa é servida em /api/docs (Swagger UI), /api/redoc e /api/reference (Scalar), com o documento OpenAPI em /openapi.json.

---

4. Normalização de entrada#

O Pain001 converte exportações do mundo real em registros válidos antes da validação:

• Aliases de campo: nomes de coluna comuns de ERP são mapeados para campos canônicos (por exemplo, amount → payment_amount).
• Normalização de IBAN / BIC: espaços removidos, caixa normalizada e, em seguida, verificação (mod-97 da ISO 13616 para IBANs, estrutura da ISO 9362 para BICs).
• Datas: parsing ISO 8601 YYYY-MM-DD para datas de execução.
• Valores: encaminhados por decimal.Decimal; valores malformados reprovam na validação em vez de serem arredondados silenciosamente.
• Conjunto de caracteres: auxiliares de transliteração reduzem o conteúdo ao conjunto de caracteres latinos ISO 20022 aceito por SWIFT e SEPA.

---

5. Arquitetura de plugins#

A suíte é extensível por meio de quatro grupos de entry points: pain001.loaders, pain001.validators, pain001.schemes e pain001.writers. O pain001-loader-xlsx registra-se por esse mecanismo e é descoberto automaticamente na instalação; o pain001-loader-mt101 é uma biblioteca de parsing autônoma consumida diretamente (e pela ferramenta convert_mt101 do servidor MCP). Um interruptor de emergência, PAIN001_DISABLE_PLUGINS=1, desativa por completo a descoberta de plugins de terceiros em ambientes restritos.

---

6. Portões de qualidade#

A biblioteca principal é desenvolvida sob portões rígidos e verificáveis: cobertura de linhas e de ramificações de 100% imposta na CI (--cov-fail-under=100), tipagem mypy estrita, cobertura de docstrings de 100% e linting de segurança (Bandit, pip-audit). Um SBOM CycloneDX é gerado para cada build de release.

Continue com o Guia de instalação, o servidor MCP para agentes de IA ou o glossário de pagamentos.