Pain001
Testar a demo ›

Referência

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

Cada flag, endpoint e comportamento do pain001 v0.0.56 — extraídos do código entregue, não de aspirações.

4 min de leitura Última revisão

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.58. 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.

Subcomando Finalidade
generate Converte um arquivo de dados em XML ISO 20022 validado contra o esquema (comando padrão).
validate Valida os dados de entrada sem gravar XML.
versions [--json] Lista todas as 11 definições de mensagem suportadas.
inspect [--json] Mostra os campos obrigatórios e opcionais de um tipo de mensagem.
init [-o DIR] Gera um modelo CSV inicial para um tipo de mensagem.
serve [--host] [--port] [--reload] Inicia o microsserviço REST FastAPI (requer o extra api).
mcp Inicia o servidor Model Context Protocol embutido (5 ferramentas; o servidor completo com 17 ferramentas é distribuído como pain001-mcp).
plugins list / show / disable Inspeciona e gerencia os plugins descobertos de loader, validador, esquema e writer.

Opções de generate

Flag Descrição
-t, --xml-message-type Definição de mensagem, por exemplo pain.001.001.09.
-d, --data Dados de entrada: .csv, .json, .jsonl, .db / .sqlite, .parquet, ou criptografados com PGP .gpg / .asc.
-o, --output-dir Diretório que recebe o XML gerado.
-m, --template / -s, --schema Substitui o template Jinja2 ou o esquema XSD incluídos.
-c, --config Carrega padrões de um perfil de configuração (--profile, --show-config).
--dry-run (alias --validate-only) Valida a entrada contra o JSON Schema, o XSD e o rulebook de esquema sem gravar saída.
--scheme Aplica um rulebook de esquema: sepa-sct, sepa-inst, sepa-sdd, sepa-b2b ou xborder-ct.
--explain --scheme-format {text,json} Relata cada regra de esquema aprovada ou reprovada, em formato legível por pessoas ou por máquinas.
--streaming / --chunk-size Processamento em blocos com memória limitada para lotes grandes (padrão de 1,000 transações por bloco; cada bloco vira seu próprio arquivo XML com NbOfTxs e CtrlSum recalculados).
--emit-metrics Emite métricas de execução legíveis por máquina para pipelines de observabilidade.

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

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):

Método e caminho Finalidade
GET /api/v1/health Sonda de liveness.
POST /api/v1/validate Valida registros; retorna erros em nível de campo.
POST /api/v1/generate Geração síncrona de XML.
POST /api/v1/generate/async Enfileira um lote grande para geração em segundo plano.
GET /api/v1/status/{job_id} Consulta um job assíncrono.
GET /api/v1/download/{job_id} Baixa o XML concluído.
DELETE /api/v1/jobs/{job_id} Remove um job concluído.
GET /metrics Métricas Prometheus.

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.