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.