# Quick Start - NF-e API

Guia rápido para começar a usar a NF-e API em 5 minutos.

---

## Pré-requisitos

- PHP 8.2+
- Composer
- Certificado Digital A1 (.pfx)
- Extensões PHP: soap, openssl, curl, dom, libxml, simplexml, mbstring, zlib, gd

---

## Instalação

```bash
# 1. Clonar o repositório
git clone https://github.com/diegoliermann/nfe-api.git
cd nfe-api

# 2. Instalar dependências
composer install

# 3. Iniciar servidor
composer start
```

A API estará disponível em: `http://localhost:8080`

---

## Teste Rápido

### 1. Health Check

```bash
curl http://localhost:8080/health
```

**Resposta esperada:**
```json
{
  "success": true,
  "status": "ok",
  "service": "nfe-api"
}
```

---

## Primeiro Uso: Pré-visualização de NF-e

### 1. Preparar Certificado

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

### 2. Criar arquivo de teste

Crie um arquivo `test-previa.json`:

```json
{
  "config": {
    "certificado": "COLE_AQUI_O_CONTEUDO_DO_certificado.txt",
    "senha": "senha-do-certificado",
    "cnpj": "99999999000191",
    "ambiente": 2,
    "uf": "SP"
  },
  "payload": {
    "ide": {
      "cUF": 35,
      "natOp": "VENDA",
      "mod": 55,
      "serie": 1,
      "nNF": 1,
      "dhEmi": "2024-06-05T10:00:00-03:00",
      "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": "99999999000191",
      "xNome": "EMPRESA TESTE LTDA",
      "IE": "123456789012",
      "CRT": 3
    },
    "enderEmit": {
      "xLgr": "RUA TESTE",
      "nro": "100",
      "xBairro": "CENTRO",
      "cMun": 3550308,
      "xMun": "SAO PAULO",
      "UF": "SP",
      "CEP": "01000000",
      "cPais": 1058,
      "xPais": "BRASIL"
    },
    "dest": {
      "CNPJ": "88888888000188",
      "xNome": "CLIENTE TESTE LTDA",
      "indIEDest": 1,
      "IE": "987654321098"
    },
    "enderDest": {
      "xLgr": "AVENIDA TESTE",
      "nro": "200",
      "xBairro": "JARDIM",
      "cMun": 3550308,
      "xMun": "SAO PAULO",
      "UF": "SP",
      "CEP": "02000000",
      "cPais": 1058,
      "xPais": "BRASIL"
    },
    "det": [
      {
        "prod": {
          "cProd": "PROD001",
          "cEAN": "SEM GTIN",
          "xProd": "PRODUTO TESTE",
          "NCM": "12345678",
          "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
    }
  }
}
```

### 3. Testar Pré-visualização

```bash
curl -X POST http://localhost:8080/nfe/previa \
  -H "Content-Type: application/json" \
  -d @test-previa.json \
  | jq . > resultado.json
```

### 4. Salvar DANFE

```bash
# Extrair o PDF da resposta
cat resultado.json | jq -r '.data.danfe' | base64 -d > danfe-preview.pdf

# Abrir o PDF
xdg-open danfe-preview.pdf  # Linux
open danfe-preview.pdf      # macOS
start danfe-preview.pdf     # Windows
```

---

## Emitir NF-e em Homologação

**⚠️ IMPORTANTE**: Use sempre `"ambiente": 2` para testes!

```bash
# Usar o mesmo arquivo test-previa.json, mas mudar o endpoint
curl -X POST http://localhost:8080/nfe/emitir \
  -H "Content-Type: application/json" \
  -d @test-previa.json \
  | jq . > nfe-autorizada.json
```

**Resposta de sucesso:**
```json
{
  "success": true,
  "data": {
    "status": "autorizado",
    "chave": "35240999999999000191550010000000011234567890",
    "protocolo": "135250000000001",
    "cStat": "100",
    "xMotivo": "Autorizado o uso da NF-e",
    "xml": "PD94bWwgdmVyc2lvbj0iMS4wIi...",
    "ambiente": 2
  }
}
```

### Salvar XML Autorizado

```bash
cat nfe-autorizada.json | jq -r '.data.xml' | base64 -d > nfe-autorizada.xml
```

---

## Gerar DANFE do XML Autorizado

```bash
# Ler o XML e enviar para gerar DANFE
XML_BASE64=$(base64 -w 0 nfe-autorizada.xml)

curl -X POST http://localhost:8080/nfe/danfe \
  -H "Content-Type: application/json" \
  -d '{
    "xml": "'"$XML_BASE64"'",
    "ambiente": 2,
    "stream": true
  }' \
  --output danfe-final.pdf
```

---

## Cancelar NF-e

```bash
# Extrair chave e protocolo da NF-e autorizada
CHAVE=$(cat nfe-autorizada.json | jq -r '.data.chave')
PROTOCOLO=$(cat nfe-autorizada.json | jq -r '.data.protocolo')

# Cancelar
curl -X POST http://localhost:8080/nfe/cancelar \
  -H "Content-Type: application/json" \
  -d '{
    "config": {
      "certificado": "COLE_AQUI_O_CONTEUDO_DO_certificado.txt",
      "senha": "senha-do-certificado",
      "cnpj": "99999999000191",
      "ambiente": 2,
      "uf": "SP"
    },
    "chave": "'"$CHAVE"'",
    "protocolo": "'"$PROTOCOLO"'",
    "justificativa": "Cancelamento de teste em ambiente de homologacao"
  }' | jq .
```

---

## Carta de Correção

```bash
curl -X POST http://localhost:8080/nfe/cce \
  -H "Content-Type: application/json" \
  -d '{
    "config": {
      "certificado": "COLE_AQUI_O_CONTEUDO_DO_certificado.txt",
      "senha": "senha-do-certificado",
      "cnpj": "99999999000191",
      "ambiente": 2,
      "uf": "SP"
    },
    "chave": "'"$CHAVE"'",
    "correcao": "Correcao de teste: ajuste no endereco de entrega conforme solicitado",
    "sequencia": 1
  }' | jq .
```

---

## Próximos Passos

1. **Leia a documentação completa**: `docs/API_DOCUMENTATION.md`
2. **Entenda a arquitetura**: `docs/IMPLEMENTATION_GUIDE.md`
3. **Use os prompts**: `docs/PROMPT_COMMANDS.md`
4. **Configure para produção**:
   - Altere `"ambiente": 2` para `"ambiente": 1`
   - Use certificado de produção
   - Implemente logging e monitoramento
   - Configure backup de XMLs

---

## Troubleshooting Rápido

### Erro: "Extensão soap não encontrada"

```bash
# Ubuntu/Debian
sudo apt-get install php8.2-soap

# CentOS/RHEL
sudo yum install php-soap

# macOS (Homebrew)
brew install php@8.2
```

### Erro: "Falha ao assinar o XML"

- Verifique se o certificado está em Base64 correto
- Confirme a senha do certificado
- Certifique-se que o certificado não está expirado

```bash
# Verificar validade
openssl pkcs12 -info -in certificado.pfx -nodes
```

### Erro: "SEFAZ indisponível"

- Verifique conectividade com a internet
- Teste acesso direto à SEFAZ:

```bash
curl -v https://nfe.fazenda.sp.gov.br/ws/nfeautorizacao4.asmx
```

### Erro: "Rejeição 539 - Duplicidade"

- Incremente o número da NF-e (`nNF`)
- Ou use timestamp para testes:

```json
{
  "ide": {
    "nNF": 123456  // Usar número único
  }
}
```

---

## Scripts Úteis

### Script: Teste Completo

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

echo "=== Teste Completo NF-e API ==="

# 1. Health check
echo -e "\n1. Health Check..."
curl -s http://localhost:8080/health | jq .

# 2. Pré-visualização
echo -e "\n2. Pré-visualização..."
curl -s -X POST http://localhost:8080/nfe/previa \
  -H "Content-Type: application/json" \
  -d @test-previa.json \
  | jq '.success'

# 3. Emissão
echo -e "\n3. Emissão..."
RESULT=$(curl -s -X POST http://localhost:8080/nfe/emitir \
  -H "Content-Type: application/json" \
  -d @test-previa.json)

echo "$RESULT" | jq '.success'

if [ "$(echo "$RESULT" | jq -r '.success')" = "true" ]; then
    CHAVE=$(echo "$RESULT" | jq -r '.data.chave')
    echo "✓ NF-e autorizada: $CHAVE"
else
    echo "✗ Erro na emissão"
    echo "$RESULT" | jq '.error'
fi
```

### Script: Converter e Testar Certificado

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

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

CERT_FILE=$1
SENHA=${2:-""}

# Converter para Base64
echo "Convertendo certificado..."
base64 -w 0 "$CERT_FILE" > certificado.txt

# Verificar informações
echo -e "\nInformações do certificado:"
openssl pkcs12 -info -in "$CERT_FILE" -nodes -passin pass:$SENHA 2>/dev/null | \
  grep -E "subject|issuer|notBefore|notAfter"

echo -e "\n✓ Certificado convertido: certificado.txt"
echo "Use o conteúdo deste arquivo no campo 'certificado' do JSON"
```

---

## Checklist de Primeiro Uso

- [ ] PHP 8.2+ instalado
- [ ] Extensões PHP verificadas
- [ ] Composer instalado
- [ ] Dependências instaladas (`composer install`)
- [ ] Servidor iniciado (`composer start`)
- [ ] Health check OK
- [ ] Certificado convertido para Base64
- [ ] Arquivo de teste criado
- [ ] Pré-visualização funcionando
- [ ] DANFE gerado com sucesso
- [ ] Emissão em homologação OK

---

## Recursos

- **Documentação Completa**: `docs/API_DOCUMENTATION.md`
- **Guia de Implementação**: `docs/IMPLEMENTATION_GUIDE.md`
- **Prompts e Comandos**: `docs/PROMPT_COMMANDS.md`
- **README**: `README.md`

---

## Suporte

Para dúvidas ou problemas:
1. Consulte a documentação em `docs/`
2. Verifique os logs de erro
3. Teste em ambiente de homologação primeiro
4. Abra uma issue no repositório

---

**Pronto!** Você já pode começar a usar a NF-e API. 🚀