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óp...

# Robô de Notas Fiscais (NFS-e São Paulo) para OpenClaw

Bem-vindo! Este pacote de arquivos foi criado para dar ao seu assistente virtual (OpenClaw) o "superpoder" de emitir, cancelar e baixar relatórios de Notas Fiscais diretamente no sistema da Prefeitura de São Paulo.

Você não precisa ser um programador para usar. Siga este passo a passo simples usando palavras do dia a dia para configurar sua clínica/empresa!

---

## 🛠️ Instalação Passo a Passo (Para Leigos)

### 1. Onde colocar a pasta do projeto?
Para que o seu robô (OpenClaw) entenda e adote essas funções financeiras, você deve colocar todos estes arquivos dentro da "Central de Habilidades" (Skills) do seu Agente.
- Geralmente, fica na pasta `workspace/skills/` (por exemplo: crie uma pasta chamada `faturamento_sp` lá dentro e jogue todos os arquivos nela).

### 2. A Mágica do "Wizard Automático" (Mais Fácil! ✨)
Sabe a parte chata de configurar arquivos cheios de códigos e números? **O seu robô agora faz isso por você!**
Nós programamos um *Assistente de Instalação (Wizard)* embutido.

Se você não quer mexer em nenhum arquivo de texto, basta fazer o seguinte:
1. Abra o chat do seu OpenClaw.
2. Diga a ele algo como: *"Emita uma Nota"* ou *"Preciso testar a skill de nota fiscal"*.
3. **Imediatamente**, o robô perceberá que este é seu primeiro acesso, pausará tudo, e vai entrevistar você no próprio chat! Ele perguntará qual o seu CNPJ, qual o seu registro na Prefeitura, e etc. Você só precisa responder conversando, e ele preencherá as configurações nos bastidores para você! 

No final da conversa, o robô pedirá apenas que você faça os **Passos 3 e 4** abaixo manualmente por rigorosas razões de segurança bancária.

---

### 3. Onde coloco o meu Certificado Digital?
Você precisará do seu certificado digital (aquele arquivo `.p12` ou `.pfx` concedido pelo governo ou seu contador).
- Pegue o seu próprio arquivo e **cole-o dentro da pasta** onde estão o resto dos arquivos do projeto. Se o robô não souber o nome do...