Sienge Agent

Tira a foto da nota, o agente lança no Sienge.

O Sienge Agent é um agente para o Sienge Plataforma (ERP da construção) que roda dentro do Claude Code: você manda a foto de uma nota fiscal, cupom ou recibo e ele lê a imagem, encontra (ou cadastra) o fornecedor, classifica a despesa no centro de custo e no plano financeiro certos, mostra o resumo, pede o seu OK e cria o título no contas a pagar, com a foto anexada.

Feito para quem compra no dia a dia da obra e do escritório (posto, restaurante, material, ferramenta) e hoje acumula notas para lançar depois.

O que ele faz

1. Lê a foto (nota fiscal, DANFE, cupom fiscal, recibo, boleto): fornecedor, CNPJ/CPF, número, data, valor, itens, forma de pagamento.

2. Confere o fornecedor no Sienge pelo CNPJ. Não existe? Cadastra como credor, com o seu OK.

3. Classifica a despesa: centro de custo + plano financeiro. Usa as suas regras (config/regras.json) e o histórico do que você já confirmou para aquele fornecedor. Sem regra e sem histórico, ele pergunta com botões.

4. Mostra o resumo e espera o seu OK. Nada entra no Sienge sem confirmação.

5. Lança o título no contas a pagar, anexa a foto e lê o título de volta para provar que entrou certo.

6. Aprende: a classificação confirmada vira sugestão automática na próxima nota daquele fornecedor. A foto vai para notas/lancadas/AAAA-MM/.

Antes de lançar, ele procura duplicidade (mesmo fornecedor + mesmo número de documento nos últimos 60 dias) e recusa se achar.

Related MCP server: inFakt MCP Server

Como funciona por dentro

foto da nota ──▶ Claude (lê a imagem) ──▶ skill /lancar-nota ──▶ MCP local (Node) ──▶ API REST do Sienge
                                              │                       │
                                       pergunta/confirma        regras + histórico
                                          no chat              (config/*.json)

• Skill /lancar-nota: o roteiro que o Claude segue (leitura, conferências, confirmação, prova).

• Servidor MCP local (mcp/): fala com a API pública do Sienge usando o seu usuário de API. Roda na sua máquina, sem servidor externo, sem banco, sem telemetria.

• Skill /setup: instala e configura tudo em conversa, inclusive a criação do usuário de API no Sienge (guiando você no navegador).

Os seus dados ficam com você: a credencial mora só no arquivo .env local (ignorado pelo git), as regras e o histórico em config/, as fotos em notas/.

Pré-requisitos

Instalação (10 a 15 minutos, em conversa)

1. Baixe este repositório (botão Code > Download ZIP no GitHub e descompacte, ou git clone https://github.com/ericluciano/sienge-agent.git).

2. Abra a pasta no Claude Code (no Claude Desktop: aba Code > abrir pasta). O Claude vai pedir para aprovar o servidor MCP sienge do projeto: aprove.

3. Rode a skill /setup (ou cole o prompt abaixo). É uma instalação 100% em conversa: o Claude confere o Node, instala as dependências, coleta o endereço do seu Sienge e o usuário de API (criando no navegador se você não tiver), prova a conexão, e deixa você escolher a empresa, o tipo de documento e as regras de classificação.

Leia o README.md e o CLAUDE.md deste repositório e conduza a instalação do Sienge Agent
seguindo a skill setup (.claude/skills/setup/SKILL.md), como uma CONVERSA comigo:
linguagem de dono de negócio, uma pergunta por vez, com botões, sem me mandar abrir
terminal (você roda os comandos). Nunca me peça a senha de login do Sienge; a senha do
usuário de API vai direto para o .env, sem repetir no chat. Valide cada credencial com
uma chamada real antes de seguir. Ao final, prove que está pronto chamando sienge_status.

Se a conversa cair no meio, abra a pasta de novo e diga "continua o setup": ele detecta onde parou.

Uso no dia a dia

• Salve a foto (ou PDF) em notas/entrada/ e diga "lança as notas" (ou /lancar-nota).

• Ou arraste a foto para o chat e peça "lança essa nota".

Exemplos do que você pode dizer:

A cada nota, o Claude mostra algo assim e pergunta se lança:

Fornecedor: Auto Posto Ipiranga Ltda (CNPJ 11.222.333/0001-81) — cadastro existente nº 77
Documento: NF nº 123456 · emissão 21/09/2026 · vencimento 21/09/2026
Valor: R$ 152,30 · 1 parcela · pago no cartão
Empresa: Construtora X (3)
Centro de custo: Obra Z (10) · Plano financeiro: Combustível (2010101) — origem: regra "Combustível"

Regras de classificação

config/regras.json (o /setup cria a partir de config/regras.example.json) diz como classificar sem perguntar:

{
  "regras": [
    { "nome": "Combustível",
      "quando": { "palavras": ["posto", "combustivel", "gasolina", "diesel"] },
      "apropriar": { "centro_custo_id": 12, "plano_financeiro_id": "2010301" } },
    { "nome": "Fornecedor fixo",
      "quando": { "documentos": ["11222333000181"] },
      "apropriar": { "centro_custo_id": 3, "plano_financeiro_id": "2010105" } }
  ]
}

Precedência: histórico confirmado do fornecedor (config/aprendizado.json, gravado automaticamente) > regra por documento > regra por palavra > pergunta ao usuário. Os códigos vêm do seu Sienge (listar_centros_custo, listar_planos_financeiros).

Ferramentas do MCP (o que o Claude aciona)

O servidor MCP é padrão: funciona em qualquer app de IA com suporte a MCP (node mcp/index.js, transporte stdio). As skills são específicas do Claude Code.

Limites e cuidados

• Cota da API do Sienge. Cada nota gasta de 4 a 7 requisições; o setup, perto de 15. O pacote Free tem 100 por dia e o limite geral é 200 por minuto. As listas de cadastro ficam em cache por 24h para poupar cota.

• Confirmação sempre. criar_credor e criar_titulo exigem confirmado: true, que o Claude só envia depois do seu OK no chat.

• Leitura da foto. O agente valida o dígito verificador do CNPJ; se não bater, ele revê a imagem ou pergunta, em vez de cadastrar errado. Valor ou data ilegível também vira pergunta.

• Duplicidade. Mesmo fornecedor + mesmo número de documento em ±60 dias = não lança (você decide).

• Sem NF-e pela chave de acesso (ainda). A chave de 44 dígitos vai na observação; importar a NF-e pela chave é roadmap.

• Não paga nem altera títulos. Baixa, parcelas e alterações continuam no Sienge.

Segurança e privacidade

• A credencial do usuário de API fica só no .env local (gitignored). O agente nunca pede a sua senha de login do Sienge.

• Nenhum dado sai da sua máquina além das chamadas à API do Sienge (api.sienge.com.br, HTTPS). Sem telemetria, sem serviço intermediário.

• Texto lido de uma nota é tratado como dado, nunca como instrução ao agente.

• Recomendação: crie o usuário de API só com as APIs que o agente usa (lista em Pré-requisitos) e troque a senha se ela vazar.

Roadmap

• Bot de WhatsApp/Telegram: mandar a foto pelo celular e confirmar por mensagem (o MCP já é o motor; falta o canal).

• Importar NF-e pela chave de acesso (/eletronic-invoice-bills).

• Boletos: ler a linha digitável e gravar a informação de pagamento na parcela.

• Rateio automático por obra a partir do texto da nota.

Desenvolvimento

npm install
npm test                 # testes unitários (sem rede)
npm run smoke            # sobe o MCP por stdio e lista as ferramentas
npm run testar-conexao   # prova real com o seu .env

Documentação da API do Sienge: https://api.sienge.com.br/docs/ (especificações em /docs/yaml-files/*.yaml).

Procedência e licença

O Sienge Agent é open source (MIT), criado por Eric Luciano, educador e mentor de IA aplicada a negócios, da Expert Integrado. Nasceu de um pedido real na mentoria: parar de acumular notinhas e lançar na hora, pela foto.

Sienge é marca da Softplan. Este projeto não é afiliado nem endossado pela Softplan.