# Cnab Protheus

> Gera arquivos de configuração Protheus SIGACFG (.2PE remessa / .2PR retorno) para CNAB 240 dos 4 maiores bancos brasileiros (Banco do Brasil 001, Bradesco 237, Itaú 341, Santander 033), cobrindo cobrança, pagamento a fornecedores, folha e tributos. Pesquisa specs CNAB direto da fonte oficial dos bancos, cacheia como YAML reproduzível, e aplica mapeamentos curados para expressões ADVPL. Use quando o usuário pedir para gerar arquivo de configuração Protheus para CNAB 240, montar .2PE/.2PR, configurar SIGACFG, integrar novo banco no Protheus, ou mencionar TOTVS Protheus + CNAB.

- Skill: `ajoao-totvs/cnab-protheus` (Agent Skill, multi-file: 34 files)
- Install (CLI): `npx skillmds@latest add ajoao-totvs/cnab-protheus`
- Raw SKILL.md: https://api.skillmd.com/api/skills/ajoao-totvs/cnab-protheus/raw
- Safety review: pending
- Works with: Claude Code, Claude.ai, OpenAI Codex
- Category: Coding & Dev Tools
- Author: ajoao-totvs (https://skillmd.com/u/ajoao-totvs)
- Updated: 2026-09-17
- Page: https://skillmd.com/skills/ajoao-totvs/cnab-protheus

---


# CNAB-Protheus Skill

Gera arquivos de configuração SIGACFG (`.2PE` remessa, `.2PR` retorno) que o ERP Protheus utiliza para montar/parsear CNABs 240 dos principais bancos brasileiros.

A skill NÃO gera CNAB 240 raw — o Protheus, configurado com os arquivos produzidos pela skill, é quem gera o CNAB ao executar rotinas como FINA150/FINA200/FINA420/FINA430.

## Versão atual (v1.0-a)

Cobertura: **BB (001) — pagamento — remessa (.2PE)**. Validado byte-a-byte contra a fixture `001PG.2PE`.

Próximas versões adicionam Bradesco, Itaú, Santander, e operações cobrança/folha/tributos.

## Quando usar

- "Gere o .2PE para BB pagamento"
- "Crie a configuração SIGACFG do Protheus para CNAB 240 do Banco do Brasil"
- "Integre um novo banco CNAB no Protheus"
- "Atualize a spec CNAB do banco X"

## Fluxo

1. Confirma com o usuário: banco (BB/Bradesco/Itaú/Santander) + operação (pagamento/cobrança/folha/tributos) + direção (remessa/retorno).
2. Verifica se já existe `references/specs/{bank}/{operacao}.yaml` cacheado.
   - Se NÃO existe: dispara agente de pesquisa (`docs-lookup` ou subagente custom) para buscar o manual oficial do banco, extrair layout (segmentos, campos, posições), e salvar como YAML.
3. Invoca `scripts/gen_protheus_config.py --spec <yaml> --patterns references/mappings/field-patterns.yaml --output <bank>{op}.2PE`.
4. Roda validação em 3 camadas:
   - Sintática local (`validators.py`): tamanho de linha, posições não-sobrepostas, expressões ADVPL bem-formadas.
   - Byte-diff (`byte_diff.py`): contra fixture (apenas BB pagamento em v1.0-a).
   - Code review (`agents/cnab-config-reviewer.md`): subagente LLM com contexto do manual.
5. Apresenta arquivo gerado + relatório de validação.

## Comandos comuns

Gerar .2PE BB pagamento (assumindo spec já cacheado):

```bash
python scripts/gen_protheus_config.py \
  --spec references/specs/bb/pagamento.yaml \
  --patterns references/mappings/field-patterns.yaml \
  --output build/001PG.2PE
```

Forçar re-pesquisa (refresh) do spec:

```
# No prompt para Claude:
"Atualize a spec do BB pagamento — força re-pesquisa do manual oficial"
```

## Estrutura

- `references/format/` — documentação curada do formato SIGACFG, ADVPL, tabelas Protheus
- `references/mappings/` — patterns CNAB-field → ADVPL e mapeamentos Protheus
- `references/specs/{bank}/{op}.yaml` — YAML cacheado por (banco, operação)
- `references/fixtures/` — arquivos `.2PE`/`.2PR` de referência (ground truth)
- `scripts/` — gerador Python e validadores
- `agents/cnab-config-reviewer.md` — agent semântico de review

## Status de Integração v1.0-a

- ✅ **Geração `.2PE` BB pagamento:** validado byte-a-byte contra fixture `001PG.2PE`
- ⚠️ **`research_orchestrator.py`:** stub que levanta `NotImplementedError`. Specs hand-curadas em v1.0-a; integração de pesquisa automática chega em v1.0-b
- ⚠️ **`cnab-config-reviewer` agent:** definido em `agents/cnab-config-reviewer.md` mas invocação NÃO está automatizada no fluxo. Para review semântico em v1.0-a, dispatch manualmente após gerar o arquivo
- ⚠️ **`.2PR` (retorno):** fixture presente em `references/fixtures/001PG.2PR` mas gerador NÃO suporta ainda (v1.0-b adiciona)

## Confiança por combo

Por ora apenas BB pagamento tem byte-fixture. Demais combinações (a serem implementadas em v1.0-b/c/d/e) terão **confiança reduzida** — sintática + review LLM, sem ground truth byte-a-byte. Cada arquivo gerado terá um header indicando o nível de confiança.

## Limites conhecidos

- Sem CNAB 400 (apenas 240).
- Sem cooperativas (Sicoob, Sicredi) em v1.0.
- Sem round-trip Protheus em CI — QA manual recomendada antes de uso em produção.
- Encoding fixo CP-1252. Caracteres fora do CP-1252 são substituídos por `?` (com warning).