| name | nota-fiscal-paulistana |
| description | Faturamento NFS-e SP (Emissão e Cancelamento de Notas Fiscais em São Paulo) |
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
emitir_nfse.py - Script de emissão em produção (gera o XML SOAP, encripta e envia).cancelar_nfse.py - Script de cancelamento de notas (criptografa o cancelamento).config.json - Retenções e alíquotas da clínica (ex: ISS, IRRF, limites, etc).tomadores.json - Tabela de dados de clientes recorrentes (sua agenda).contador_rps.txt - Arquivo de controle rigoroso para a sequência do talão.Certificados.p12 - Chave criptográfica municipal (JAMAIS EXPOR)..env - Arquivo oculto onde você lerá a variável NFSE_CERT_PASSWORD=senha.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:
- 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.
- 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.
- 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.
- 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!"
- 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:
- Revise e peça confirmação: "Deseja mesmo revogar definitivamente a Nota SP Nº N?".
- Se Sim, invoque via terminal:
python cancelar_nfse.py [N] --json-out
- 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:
- Para busca retroativa em dias:
python baixar_notas.py --dias X (Padrão 30 dias se o usuário não disser outra coisa).
- 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).
- 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.
- 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,
"documento_tomador": "<Apenas_Numeros>",
"razao_social_tomador": "<Nome_Empresa>",
"email_tomador": "<Email_Cliente>",
"endereco_tomador": {
"logradouro": "RUA X", "numero": "123", "bairro": "VILA Y",
🟢 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.
