# Nota Fiscal Paulistana > Faturamento NFS-e SP (Emissão e Cancelamento de Notas Fiscais em São Paulo) - Skill: `dvcrn/nota-fiscal-paulistana` (Agent Skill, multi-file: 11 files) - Install (CLI): `npx skillmds@latest add dvcrn/nota-fiscal-paulistana` - Raw SKILL.md: https://api.skillmd.com/api/skills/dvcrn/nota-fiscal-paulistana/raw - Safety review: pending (external: skill-scanner PASS, skillspector PASS) - Works with: Claude Code, Claude.ai, OpenAI Codex - Category: Coding & Dev Tools - Author: dvcrn (https://skillmd.com/u/dvcrn) - Updated: 2026-09-08 - Page: https://skillmd.com/skills/dvcrn/nota-fiscal-paulistana --- # 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: ```json { "numero_rps": , "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": "", "razao_social_tomador": "", "email_tomador": "", "endereco_tomador": { "logradouro": "RUA X", "numero": "123", "bairro": "VILA Y", "cidade": "3550308", "uf": "SP", "cep": "00000000" }, "discriminacao": "" } ``` ## 🟢 4. Tratamento do Standard Output As requisições sempre retornarão um JSON formatado pelo script. Exemplo de Resposta do Emitir: ```json { "sucesso": true, "notas_geradas": [{"numero": "8952", "url_pdf": "https://..."}] } ``` Exemplo de Resposta do Cancelar: ```json { "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.