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!"

1. 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.