Emissor de Nota Fiscal Paulistana

Faturamento NFS-e SP (Emissão e Cancelamento de Notas Fiscais em São Paulo)

Security Scan

The skill generally matches its stated purpose (emit/cancel NFS-e) but contains several incoherencies around credentials, file expectations, and autonomous file writes that a user should review before installing.

Purpose & Capability

The code and SKILL.md implement São Paulo NFS-e operations (issue, cancel, download) and call official prefeitura endpoints — this matches the name/description. However the registry metadata declares no required env vars or config paths while the code and docs clearly expect a certificate file (a .p12) and the NFSE_CERT_PASSWORD environment variable / .env file. Also SKILL.md references an env.example template that is not present in the file manifest. These mismatches are disproportionate to the stated metadata and may lead to unexpected behavior.

Instruction Scope

SKILL.md instructs the agent to read and write workspace files (config.json, tomadores.json, contador_rps.txt), create/rename a hidden .env, and autonomously populate config.json after an interactive wizard. Asking the agent to create hidden files and write configuration and to instruct the user how to paste secret passwords into .env is within the functional scope of setup, but grants the agent broad filesystem-write actions and handling of secrets — more scope than what the registry metadata declares and something users should explicitly consent to.

Install Mechanism

This is an instruction-and-code bundle with no install spec (lowest installation risk). The Python scripts require third-party libraries (requests, signxml, cryptography, lxml, python-dotenv) but the package makes no installation or dependency instructions in the registry metadata — the absence of an install spec is plausible but incomplete; the user must ensure the runtime has the required packages.

Credentials

The skill requests/uses sensitive artefacts: a municipal certificate file (.p12) and the NFSE_CERT_PASSWORD environment variable (read via dotenv and os.environ). Yet the registry metadata lists no required environment variables or config paths. Storing the password in a plaintext .env file (as instructed) is insecure unless file permissions are hardened. The number and sensitivity of required secrets are proportionate to the functionality, but the missing declarations and the plaintext .env guidance are concerning.

Persistence & Privilege

always is false and the skill is user-invocable; autonomous invocation is allowed and used by the SKILL.md (e.g., the wizard that writes config.json). The skill modifies files within its own workspace (normal) and creates temporary PEM files when making TLS client-authenticated requests (expected). This is acceptable for the purpose but the combination of autonomous file writes + secret handling + invoking other skills (e.g., the 'GOG' e-mail skill) increases the blast radius and should be considered by the user.

What to consider before installing

This package appears to implement the advertised São Paulo NFS-e flows, but review these points before installing or using it with real certificates: 1) The code expects a municipal certificate (.p12) and the NFSE_CERT_PASSWORD env var, but the skill metadata does not declare those — expect to provide a certificate file and a password. 2) SKILL.md instructs the agent to create/modify files (config.json, .env, tomadores.json, contador_rps.txt). If you don't want the agent writing files, do not allow the automated wizard; instead configure files manually. 3) The README advises putting the certificate password into a plaintext .env file — store secrets securely (restrict file permissions, or use a secrets manager) and remove the .env from backups/version control. 4) The SKILL.md references env.example which is not included; verify the setup steps and supply your own .env if needed. 5) The scripts create temp PEM files and write debug/response XML to disk — audit those files for sensitive content and ensure temporary files are removed and access-restricted. 6) Verify dependencies (requests, lxml, signxml, cryptography, python-dotenv) are installed in a controlled environment. Recommended safe steps: test in an isolated environment with a revoked/test certificate; inspect the code yourself (or with a developer) before adding a production certificate; restrict file permissions on the certificate and .env; and avoid letting the agent perform automatic writes if you prefer manual control. If you want, provide me with specific lines or behaviors to inspect further (e.g., confirm absence of external, unexpected network endpoints or detect any code paths that upload files to non-official hosts).

Habilidade de Faturamento NFS-e SP (OpenClaw)

Esta documentação define o comportamento e as arquiteturas da Skill de faturamento para emitir e cancelar Notas Fiscais de Serviços Eletrônica (NFS-e) da Prefeitura de São Paulo.

Importante: Todos os arquivos descritos abaixo devem estar contidos na mesma pasta desta Skill (ex: workspace/skills/nfse-sp/).

📁 Arquivos do Ecossistema

1. emitir_nfse.py - Script de emissão em produção (gera o XML SOAP, encripta e envia).
2. cancelar_nfse.py - Script de cancelamento de notas (criptografa o cancelamento).
3. config.json - Retenções e alíquotas da clínica (ex: ISS, IRRF, limites, etc).
4. tomadores.json - Tabela de dados de clientes recorrentes (sua agenda).
5. contador_rps.txt - Arquivo de controle rigoroso para a sequência do talão.
6. Certificados.p12 - Chave criptográfica municipal (JAMAIS EXPOR).
7. .env - Arquivo oculto onde você lerá a variável NFSE_CERT_PASSWORD=senha.
8. baixar_notas.py - Script paginado de extração de relatórios e balanços contábeis da clínica.

---

✨ 0. O Wizard de Instalação (Health Check Automático)

Sempre que o usuário solicitar qualquer ação financeira pela primeira vez (ou se você notar que há algo faltando), você deve fazer um check-up silencioso lendo o arquivo config.json. Se os campos contiverem palavras-chave genéricas como "MEUCNPJ", "Minhainscricao" ou "MEUCertificado.p12", significa que o usuário acabou de instalar sua Skill e é um humano leigo.

Neste caso, pause a tarefa dele e inicie um Wizard de Instalação Interativo e Amigável no chat:

1. Diga que percebeu que é a primeira vez dele e peça, um por vez, os dados faltantes: O CNPJ, a Inscrição Municipal, e o Código de Serviço.
2. A cada resposta do usuário, você mesmo (o Agente) usará suas habilidades de escrita de arquivo para alterar e salvar os dados no documento config.json por ele.
3. Ato Autônomo com o .env: Antes de falar com o usuário sobre a senha, use suas próprias ferramentas de terminal para copiar (ou renomear) o arquivo modelo visível env.example para .env (oculto com ponto) na pasta. Deixe este arquivo preparado para receber a senha.
4. Quando tudo isso acabar e o .env oculto estiver pronto, informe-o sobre a etapa final de segurança (A Senha e o Certificado) orientando-o exatamente desta forma:

"Pronto, preenchi os dados da sua empresa e preparei o terreno! Agora, por questões rigorosas de segurança bancária e proteção de dados, vou pedir que você faça a última etapa manualmente. Abra a pasta técnica deste projeto no seu computador (geralmente em ~/.openclaw/workspace/skills/). Arraste para lá o seu arquivo de certificado real (ex: Certificado.p12). Em seguida, por ser uma senha sigilosa, peço que você abra o arquivo de texto oculto chamado .env (se vc usa Mac, aperte Command + Shift + . para ver os arquivos ocultos). Lá dentro, você verá escrito NFSE_CERT_PASSWORD=SUA_SENHA_AQUI_NAO_COLOQUE_NO_GITHUB. Apague tudo o que está do lado direito do sinal de igual, e cole a senha verdadeira do seu certificado colada ao =. Feche e salve. Me avise no chat quando terminar!"

5. Após o usuário confirmar que fez as cópias, atualize no config.json o nome exato do arquivo .p12 que ele disse ter copiado para a pasta, e finalmente retome ou execute a tarefa inicial que ele havia pedido!

---

🚀 1. O Fluxo de Coleta e Emissão no Chat

Siga as 6 etapas abaixo sempre que o usuário solicitar emissão:

1. Recepção de Pedido: O usuário pedirá a nota (Valor e Tomador). Ex: "Nota de 1500 para a AMIL". 2. Triagem Local (tomadores.json): Leia o arquivo tomadores.json em background. Se o Tomador já estiver cadastrado, puxe o CNPJ, endereço e e-mail de lá. Se for inédito, peça ao usuário os dados faltantes. 3. Simulação Financeira (Draft): Calcule os impostos internamente cruzando com as regras do config.json. Responda ao usuário com um "Esboço" detalhado (Valor Bruto, valor de cada retenção aplicada, Total Líquido e Preview da Discriminação da nota). 4. Oitiva Humana: Pergunte se o usuário "Aprova o Faturamento". 5. Emissão e RPS:

• Se aprovado, leia contador_rps.txt para pegar o próximo número sequencial X.
• Gere o arquivo /tmp/dados_rps_X.json autônomamente.
• Execute: python emitir_nfse.py --modo producao --dados /tmp/dados_rps_X.json --json-out
• Imediatamente incremente contador_rps.txt (+1).
• Boas práticas: Após o passo acima finalizar, você (o Agente) deve excluir o arquivo temporário /tmp/dados_rps_X.json para manter o sistema limpo. 6. Entrega do PDF Final e Envio por E-mail: Leia a saída JSON do Python. Extraia e devolva ao humano no chat:
• O sucesso da operação e o Número Final da NF-e gerada.
• A URL Oficial de Impressão (PDF) da prefeitura.
• Ação Autônoma Obrigatória: Como a prefeitura bloqueia o envio público, invoque a sua Skill GOG (Gestão de E-mails) e redija um e-mail formatado enviando este link do PDF para o seu próprio e-mail.
• Bônus: Se for cliente inédito aprovado, reescreva e salve os novos dados em tomadores.json.

�️ 2. O Fluxo de Cancelamento de NF-e

Se o usuário pedir explícitamente "Cancele a nota numero N", siga 3 etapas:

1. Revise e peça confirmação: "Deseja mesmo revogar definitivamente a Nota SP Nº N?".
2. Se Sim, invoque via terminal: python cancelar_nfse.py [N] --json-out
3. Leia o stdout JSON e informe ao usuário se ela foi cancelada com sucesso no ambiente contábil de São Paulo.

📊 3. Fluxo de Relatórios Contábeis (Extrato de Notas)

A qualquer momento o usuário pode solicitar um relatório, balanço total ou extração de faturamentos (Ex: "Feche a contabilidade do mês passado"). Use o script baixar_notas.py que consulta a Prefeitura e produz um extrato autônomo. Regras de uso:

1. Para busca retroativa em dias: python baixar_notas.py --dias X (Padrão 30 dias se o usuário não disser outra coisa).
2. Para busca em meses/períodos exatos: python baixar_notas.py --inicio YYYY-MM-DD --fim YYYY-MM-DD (O script já tem um loop autônomo que fatiará janelas grandes de >30 dias sem quebrar a API, fique tranquilo).
3. Resumo Visual: Leia o console stdout dessa requisição (que contém Valor Faturado (Bruto Ativo) e Notas Ativas) para dar no chat o seu overview financeiro humano sobre o fechamento pedido.
4. Exportação Físisca: A prefeitura exportará tudo formatado em um novo arquivo JSON. Se a oitiva humana do usuário quiser esse relatório em mãos ("Mande essas notas pro contador", ou "Mande pro meu email"), use a sua Skill Nativa GOG e anexe/envie o resultado do arquivo gerado (nfse_contabilidade.json) para os e-mails informados.

📄 3. Geração do Payload JSON Único para Emissão

Para o Passo 5 acima, gere um /tmp/dados_rps_XXX.json unicamente para o atendimento. Modelo:

{
  "numero_rps": <Lido_do_contador_rps.txt>,
  "data_emissao": "AAAA-MM-DD",
  "status_rps": "N",
  "iss_retido": "N",
  "calcular_retencoes": true,
  "valor_servicos": 150.00,
  "indicador_tomador": 2, // 2 para CNPJ, 1 para CPF
  "documento_tomador": "<Apenas_Numeros>",
  "razao_social_tomador": "<Nome_Empresa>",
  "email_tomador": "<Email_Cliente>",
  "endereco_tomador": {
      "logradouro": "RUA X", "numero": "123", "bairro": "VILA Y", "cidade": "3550308", "uf": "SP", "cep": "00000000"
  },
  "discriminacao": "<Suas_Instrucoes_Extras>"
}

🟢 4. Tratamento do Standard Output

As requisições sempre retornarão um JSON formatado pelo script. Exemplo de Resposta do Emitir:

{
  "sucesso": true,
  "notas_geradas": [{"numero": "8952", "url_pdf": "https://..."}]
}

Exemplo de Resposta do Cancelar:

{
  "sucesso": true,
  "mensagem": "NF-e 642 cancelada com sucesso!"
}

Use o parsing inteligente desses JSONs para formular suas respostas humanas ricas e completas no Chat do OpenClaw. Nunca despeje JSON puro para o usuário a menos que solicitado.