# Prompts e Comandos para Implementação

Este documento contém prompts prontos para usar com assistentes de IA (como ChatGPT, Claude, etc.) para implementar a NF-e API em outros projetos.

---

## Índice
1. [Prompts para Entendimento](#prompts-para-entendimento)
2. [Prompts para Implementação](#prompts-para-implementação)
3. [Prompts para Integração](#prompts-para-integração)
4. [Prompts para Troubleshooting](#prompts-para-troubleshooting)
5. [Comandos Shell Úteis](#comandos-shell-úteis)

---

## Prompts para Entendimento

### Prompt 1: Análise de Arquitetura

```
Analise a arquitetura da NF-e API localizada em [CAMINHO_DO_PROJETO].

Identifique e explique:
1. O padrão arquitetural utilizado (camadas, responsabilidades)
2. Como o fluxo de dados funciona desde o request HTTP até a resposta
3. Como o tratamento de erros é centralizado
4. Quais são as principais dependências e como são injetadas
5. Como o sistema mantém o princípio stateless

Forneça um diagrama de sequência para o fluxo de emissão de NF-e.
```

### Prompt 2: Entendimento do NfeParser

```
Explique em detalhes como o NfeParser converte JSON em XML de NF-e.

Foque em:
1. O mapeamento dinâmico de blocos tributários (ITEM_TAX_MAP)
2. Como funciona o fallback de tributação (item vs tributacao global)
3. Como novos impostos podem ser adicionados (ex: IBS/CBS da Reforma Tributária)
4. A conversão de arrays PHP para stdClass
5. Como o parser garante a ordem correta dos elementos XML

Forneça exemplos práticos de como adicionar suporte a um novo imposto.
```

### Prompt 3: Fluxo de Comunicação com SEFAZ

```
Descreva o fluxo completo de comunicação com a SEFAZ no EmissaoService.

Inclua:
1. Como o certificado A1 é carregado e usado
2. O processo de assinatura do XML
3. A diferença entre envio síncrono e assíncrono
4. Como os códigos cStat são interpretados
5. O que é o nfeProc e como é montado
6. Estratégias de retry em caso de falha

Forneça um diagrama de estados mostrando os possíveis caminhos de uma emissão.
```

---

## Prompts para Implementação

### Prompt 4: Criar Microserviço Docker

```
Crie uma configuração Docker completa para a NF-e API localizada em [CAMINHO].

Requisitos:
1. Dockerfile otimizado para produção (multi-stage build)
2. docker-compose.yml com serviços: api, nginx (reverse proxy)
3. Configuração Nginx para servir a API
4. Health checks configurados
5. Volumes para logs
6. Variáveis de ambiente para configuração
7. Limite de memória e CPU adequados

Inclua também:
- Script de inicialização (entrypoint.sh)
- .dockerignore otimizado
- Instruções de build e deploy
```

### Prompt 5: Integrar em Laravel

```
Integre a NF-e API em um projeto Laravel existente.

Crie:
1. Service Provider para registrar os serviços no container do Laravel
2. Controller Laravel que usa os services da NF-e API
3. Rotas API no routes/api.php
4. Form Request para validação de payloads
5. Resource para formatação de respostas
6. Middleware para autenticação e rate limiting
7. Job para emissão assíncrona de NF-e via queue
8. Migration para tabela de log de NF-e (opcional)

Mantenha a arquitetura stateless da API original.
```

### Prompt 6: Cliente JavaScript/TypeScript

```
Crie um cliente TypeScript completo para consumir a NF-e API.

Requisitos:
1. Classe NfeApiClient com métodos tipados para todos os endpoints
2. Interfaces TypeScript para todos os payloads e responses
3. Tratamento de erros com tipos específicos
4. Suporte a retry automático
5. Interceptors para logging
6. Suporte a upload de certificado (file → base64)
7. Exemplos de uso para cada endpoint
8. Testes unitários com Jest

Use axios como biblioteca HTTP.
```

### Prompt 7: Cliente Python

```
Desenvolva um cliente Python profissional para a NF-e API.

Inclua:
1. Classe NfeApiClient com type hints (Python 3.10+)
2. Dataclasses para payloads e responses
3. Exception customizadas para cada tipo de erro
4. Context manager para gerenciar sessões
5. Async support com aiohttp (opcional)
6. Retry com backoff exponencial
7. Logging estruturado
8. Testes com pytest
9. Documentação com docstrings (Google style)
10. Exemplo de uso em Jupyter Notebook

Use requests ou httpx como biblioteca HTTP.
```

### Prompt 8: Adapter para Symfony

```
Adapte a NF-e API para funcionar em um projeto Symfony.

Crie:
1. Bundle Symfony (NfeBundle)
2. Services configurados no services.yaml
3. Controller Symfony usando os services
4. Rotas em routes.yaml
5. Event Subscribers para logging de eventos
6. Validator constraints customizados para payloads
7. Serializer para normalização de responses
8. Command console para emissão via CLI
9. Testes funcionais com WebTestCase

Mantenha compatibilidade com Symfony 6.x.
```

---

## Prompts para Integração

### Prompt 9: Integração com ERP

```
Crie uma camada de integração entre um ERP genérico e a NF-e API.

Desenvolva:
1. Adapter que converte modelo de dados do ERP para payload da NF-e API
2. Mapeamento de produtos, clientes, impostos
3. Regras de negócio para determinar CFOP, CST, etc.
4. Fila de processamento para emissões em lote
5. Sistema de retry para falhas
6. Armazenamento de XMLs e DANFEs
7. Webhook para notificar ERP sobre status da NF-e
8. Dashboard de monitoramento
9. Logs estruturados

Forneça exemplos de mapeamento para cenários comuns (venda, devolução, remessa).
```

### Prompt 10: API Gateway

```
Configure um API Gateway (Kong, AWS API Gateway ou similar) na frente da NF-e API.

Implemente:
1. Autenticação via API Key ou JWT
2. Rate limiting por cliente
3. Caching de respostas quando aplicável
4. Transformação de requests/responses
5. Logging centralizado
6. Métricas e monitoramento
7. Circuit breaker para SEFAZ
8. Versionamento de API
9. Documentação OpenAPI/Swagger

Forneça configuração completa e exemplos de uso.
```

### Prompt 11: Webhook System

```
Implemente um sistema de webhooks para notificar sistemas externos sobre eventos da NF-e.

Crie:
1. Tabela de registro de webhooks (URL, eventos, secret)
2. Sistema de disparo assíncrono (queue)
3. Retry com backoff exponencial
4. Assinatura HMAC para segurança
5. Logs de tentativas e falhas
6. Interface de gerenciamento de webhooks
7. Eventos suportados: nfe.autorizada, nfe.rejeitada, nfe.cancelada, etc.
8. Payload padronizado para cada evento

Use Laravel Queue ou similar.
```

---

## Prompts para Troubleshooting

### Prompt 12: Debug de Rejeições SEFAZ

```
Crie um sistema de debug para rejeições da SEFAZ.

Desenvolva:
1. Parser de códigos cStat com descrições detalhadas
2. Sugestões automáticas de correção baseadas no cStat
3. Validador de payload antes do envio
4. Comparador de XMLs (esperado vs gerado)
5. Ferramenta de teste de certificado
6. Simulador de respostas SEFAZ para testes
7. Dashboard de rejeições mais comuns
8. Documentação de cada código de rejeição

Forneça exemplos de correções para os 20 cStats mais comuns.
```

### Prompt 13: Monitoramento e Observabilidade

```
Implemente observabilidade completa na NF-e API.

Configure:
1. Logging estruturado (JSON) com contexto
2. Métricas (Prometheus):
   - Taxa de sucesso/falha por endpoint
   - Latência de comunicação com SEFAZ
   - Distribuição de cStats
3. Tracing distribuído (Jaeger/Zipkin)
4. Alertas:
   - SEFAZ indisponível
   - Taxa de erro > threshold
   - Latência alta
5. Dashboard Grafana com painéis relevantes
6. Health checks detalhados
7. Profiling de performance

Forneça configuração completa e queries úteis.
```

### Prompt 14: Testes Automatizados

```
Crie suite completa de testes para a NF-e API.

Implemente:
1. Testes unitários para cada Service, Parser, Controller
2. Mocks para NFePHP Tools e comunicação SEFAZ
3. Testes de integração para fluxos completos
4. Testes de contrato (Pact) para clientes
5. Testes de carga (k6 ou Locust)
6. Testes de segurança (OWASP)
7. Fixtures de payloads válidos e inválidos
8. Asserções para cada cenário de erro
9. Coverage report configurado

Use PHPUnit e forneça exemplos de cada tipo de teste.
```

---

## Prompts para Extensão

### Prompt 15: Suporte a NFC-e

```
Estenda a NF-e API para suportar NFC-e (modelo 65).

Adicione:
1. Endpoint POST /nfce/emitir
2. Validações específicas de NFC-e (CSC, QR Code)
3. Geração de QR Code
4. DANFE simplificado (A4 ou bobina)
5. Contingência offline
6. Inutilização de numeração
7. Diferenças de layout vs NF-e

Mantenha compatibilidade com a arquitetura existente.
```

### Prompt 16: Suporte a CT-e

```
Adapte a arquitetura para suportar CT-e (Conhecimento de Transporte Eletrônico).

Crie:
1. CteParser (similar ao NfeParser)
2. EmissaoCteService
3. Endpoints: /cte/emitir, /cte/cancelar, /cte/cce
4. Mapeamento de modais (rodoviário, aéreo, etc.)
5. DACTE (PDF do CT-e)
6. Validações específicas de CT-e

Reutilize componentes comuns (Router, ToolsFactory, SefazComm).
```

### Prompt 17: Reforma Tributária (IBS/CBS)

```
Implemente suporte completo à Reforma Tributária (IBS/CBS/IS).

Adicione:
1. Validação de schemes PL_010_*
2. Blocos ibscbs e is no NfeParser
3. Totalizadores ibscbstot e istot
4. Exemplos de payloads com IBS/CBS
5. Documentação específica
6. Testes para cenários de Reforma Tributária
7. Migração de payloads antigos

Forneça guia de migração para usuários existentes.
```

---

## Comandos Shell Úteis

### Setup e Instalação

```bash
# Clonar projeto
git clone https://github.com/diegoliermann/nfe-api.git
cd nfe-api

# Instalar dependências
composer install

# Verificar extensões PHP
php -m | grep -E 'soap|openssl|curl|dom|simplexml|mbstring|zlib|gd'

# Iniciar servidor de desenvolvimento
composer start

# Rodar em porta específica
php -S 0.0.0.0:9000 -t public
```

### Testes e Qualidade

```bash
# Rodar todos os testes
composer test

# Rodar testes com coverage
composer test -- --coverage-html coverage

# Code sniffer (verificar PSR-12)
composer cs

# Corrigir code style automaticamente
composer cs:fix

# PHPStan (análise estática)
composer stan

# Rodar todos os checks
composer cs && composer stan && composer test
```

### Certificado Digital

```bash
# Converter PFX para Base64
base64 -w 0 certificado.pfx > certificado.txt

# Verificar informações do certificado
openssl pkcs12 -info -in certificado.pfx -nodes

# Extrair certificado público
openssl pkcs12 -in certificado.pfx -clcerts -nokeys -out cert.pem

# Extrair chave privada
openssl pkcs12 -in certificado.pfx -nocerts -nodes -out key.pem

# Verificar validade do certificado
openssl x509 -in cert.pem -noout -dates

# Verificar CNPJ do certificado
openssl x509 -in cert.pem -noout -subject
```

### Docker

```bash
# Build da imagem
docker build -t nfe-api:latest .

# Rodar container
docker run -d -p 8080:8080 --name nfe-api nfe-api:latest

# Ver logs
docker logs -f nfe-api

# Executar comando no container
docker exec -it nfe-api php -v

# Docker Compose
docker-compose up -d
docker-compose logs -f
docker-compose down
```

### Testes de API (curl)

```bash
# Health check
curl http://localhost:8080/health

# Emitir NF-e (exemplo)
curl -X POST http://localhost:8080/nfe/emitir \
  -H "Content-Type: application/json" \
  -d @payload-emissao.json \
  | jq .

# Salvar response em arquivo
curl -X POST http://localhost:8080/nfe/emitir \
  -H "Content-Type: application/json" \
  -d @payload.json \
  -o response.json

# Download DANFE (stream)
curl -X POST http://localhost:8080/nfe/danfe \
  -H "Content-Type: application/json" \
  -d '{"xml":"'$(cat nfe.xml | base64 -w 0)'","ambiente":2,"stream":true}' \
  --output danfe.pdf

# Medir tempo de resposta
curl -X POST http://localhost:8080/nfe/emitir \
  -H "Content-Type: application/json" \
  -d @payload.json \
  -w "\nTempo total: %{time_total}s\n"
```

### Debugging

```bash
# Verificar erros PHP
tail -f /var/log/php/error.log

# Habilitar debug no PHP
php -d display_errors=1 -d error_reporting=E_ALL -S 0.0.0.0:8080 -t public

# Testar conectividade com SEFAZ
curl -v https://nfe.fazenda.sp.gov.br/ws/nfeautorizacao4.asmx

# Verificar DNS
nslookup nfe.fazenda.sp.gov.br

# Testar certificado SSL da SEFAZ
openssl s_client -connect nfe.fazenda.sp.gov.br:443 -showcerts
```

### Performance

```bash
# Apache Bench - teste de carga
ab -n 100 -c 10 -p payload.json -T application/json http://localhost:8080/nfe/previa

# Verificar uso de memória
php -d memory_limit=512M -S 0.0.0.0:8080 -t public

# Profile com Xdebug
php -d xdebug.mode=profile -S 0.0.0.0:8080 -t public

# Monitorar processos PHP
watch -n 1 'ps aux | grep php'
```

### Produção

```bash
# Otimizar autoloader
composer dump-autoload --optimize --no-dev

# Limpar cache do Composer
composer clear-cache

# Verificar vulnerabilidades
composer audit

# Atualizar dependências
composer update --with-all-dependencies

# Backup de certificados
tar -czf certificados-backup-$(date +%Y%m%d).tar.gz *.pfx

# Rotação de logs
logrotate /etc/logrotate.d/nfe-api
```

---

## Scripts Úteis

### Script 1: Converter Certificado

```bash
#!/bin/bash
# convert-cert.sh

if [ -z "$1" ]; then
    echo "Uso: ./convert-cert.sh certificado.pfx"
    exit 1
fi

CERT_FILE=$1
BASE64_FILE="${CERT_FILE%.pfx}.txt"

echo "Convertendo $CERT_FILE para Base64..."
base64 -w 0 "$CERT_FILE" > "$BASE64_FILE"

echo "✓ Certificado convertido: $BASE64_FILE"
echo ""
echo "Informações do certificado:"
openssl pkcs12 -info -in "$CERT_FILE" -nodes -passin pass: 2>/dev/null | grep -E "subject|issuer|notBefore|notAfter"
```

### Script 2: Teste Rápido de Emissão

```bash
#!/bin/bash
# test-emissao.sh

API_URL="${API_URL:-http://localhost:8080}"
CERT_BASE64=$(cat certificado.txt)
SENHA="${CERT_SENHA:-senha123}"
CNPJ="${CNPJ:-99999999000191}"

echo "Testando emissão de NF-e..."

curl -X POST "$API_URL/nfe/previa" \
  -H "Content-Type: application/json" \
  -d '{
    "config": {
      "certificado": "'"$CERT_BASE64"'",
      "senha": "'"$SENHA"'",
      "cnpj": "'"$CNPJ"'",
      "ambiente": 2,
      "uf": "SP"
    },
    "payload": {
      "ide": {
        "cUF": 35,
        "natOp": "VENDA",
        "mod": 55,
        "serie": 1,
        "nNF": 1,
        "dhEmi": "'"$(date -Iseconds)"'",
        "tpNF": 1,
        "idDest": 1,
        "cMunFG": 3550308,
        "tpImp": 1,
        "tpEmis": 1,
        "tpAmb": 2,
        "finNFe": 1,
        "indFinal": 0,
        "indPres": 1,
        "procEmi": 0,
        "verProc": "1.0"
      }
    }
  }' | jq .
```

### Script 3: Monitor de Saúde

```bash
#!/bin/bash
# health-monitor.sh

API_URL="${API_URL:-http://localhost:8080}"
INTERVAL="${INTERVAL:-30}"

while true; do
    RESPONSE=$(curl -s -w "\n%{http_code}" "$API_URL/health")
    HTTP_CODE=$(echo "$RESPONSE" | tail -n 1)
    BODY=$(echo "$RESPONSE" | head -n -1)
    
    if [ "$HTTP_CODE" = "200" ]; then
        echo "[$(date '+%Y-%m-%d %H:%M:%S')] ✓ API OK - $BODY"
    else
        echo "[$(date '+%Y-%m-%d %H:%M:%S')] ✗ API DOWN - HTTP $HTTP_CODE"
    fi
    
    sleep $INTERVAL
done
```

---

## Templates de Payload

### Template: NF-e Simples

```json
{
  "config": {
    "certificado": "{{CERTIFICADO_BASE64}}",
    "senha": "{{SENHA}}",
    "cnpj": "{{CNPJ_EMITENTE}}",
    "ambiente": 2,
    "uf": "SP"
  },
  "payload": {
    "ide": {
      "cUF": 35,
      "natOp": "VENDA DE MERCADORIA",
      "mod": 55,
      "serie": 1,
      "nNF": 1,
      "dhEmi": "{{DATA_HORA_EMISSAO}}",
      "tpNF": 1,
      "idDest": 1,
      "cMunFG": 3550308,
      "tpImp": 1,
      "tpEmis": 1,
      "tpAmb": 2,
      "finNFe": 1,
      "indFinal": 0,
      "indPres": 1,
      "procEmi": 0,
      "verProc": "1.0"
    },
    "emit": {
      "CNPJ": "{{CNPJ_EMITENTE}}",
      "xNome": "{{RAZAO_SOCIAL}}",
      "IE": "{{INSCRICAO_ESTADUAL}}",
      "CRT": 3
    },
    "enderEmit": {
      "xLgr": "{{LOGRADOURO}}",
      "nro": "{{NUMERO}}",
      "xBairro": "{{BAIRRO}}",
      "cMun": 3550308,
      "xMun": "SAO PAULO",
      "UF": "SP",
      "CEP": "{{CEP}}",
      "cPais": 1058,
      "xPais": "BRASIL"
    },
    "dest": {
      "CNPJ": "{{CNPJ_DESTINATARIO}}",
      "xNome": "{{NOME_DESTINATARIO}}",
      "indIEDest": 1,
      "IE": "{{IE_DESTINATARIO}}"
    },
    "enderDest": {
      "xLgr": "{{LOGRADOURO_DEST}}",
      "nro": "{{NUMERO_DEST}}",
      "xBairro": "{{BAIRRO_DEST}}",
      "cMun": 3550308,
      "xMun": "SAO PAULO",
      "UF": "SP",
      "CEP": "{{CEP_DEST}}",
      "cPais": 1058,
      "xPais": "BRASIL"
    },
    "det": [
      {
        "prod": {
          "cProd": "{{CODIGO_PRODUTO}}",
          "cEAN": "SEM GTIN",
          "xProd": "{{DESCRICAO_PRODUTO}}",
          "NCM": "{{NCM}}",
          "CFOP": "5102",
          "uCom": "UN",
          "qCom": 1,
          "vUnCom": 100.00,
          "vProd": 100.00,
          "cEANTrib": "SEM GTIN",
          "uTrib": "UN",
          "qTrib": 1,
          "vUnTrib": 100.00,
          "indTot": 1
        },
        "imposto": {
          "vTotTrib": 15.00
        }
      }
    ],
    "total": {
      "icmstot": {
        "vBC": 100.00,
        "vICMS": 18.00,
        "vICMSDeson": 0,
        "vProd": 100.00,
        "vNF": 100.00,
        "vTotTrib": 15.00
      }
    },
    "transp": {
      "modFrete": 9
    },
    "pag": {
      "detPag": [
        {
          "indPag": 0,
          "tPag": "01",
          "vPag": 100.00
        }
      ]
    }
  },
  "tributacao": {
    "icms": {
      "orig": 0,
      "CST": "00",
      "modBC": 0,
      "vBC": 100.00,
      "pICMS": 18.00,
      "vICMS": 18.00
    },
    "pis": {
      "CST": "01",
      "vBC": 100.00,
      "pPIS": 1.65,
      "vPIS": 1.65
    },
    "cofins": {
      "CST": "01",
      "vBC": 100.00,
      "pCOFINS": 7.60,
      "vCOFINS": 7.60
    }
  }
}
```

---

## Conclusão

Use estes prompts e comandos como base para:
- Entender a arquitetura do projeto
- Implementar em diferentes tecnologias
- Integrar com sistemas existentes
- Debugar problemas
- Estender funcionalidades

Adapte conforme necessário para seu caso de uso específico!