# Documentação Completa da API NF-e

## Índice
1. [Visão Geral](#visão-geral)
2. [Configuração e Requisitos](#configuração-e-requisitos)
3. [Objeto de Configuração](#objeto-de-configuração)
4. [Endpoints da API](#endpoints-da-api)
5. [Estrutura de Payloads](#estrutura-de-payloads)
6. [Respostas e Códigos de Erro](#respostas-e-códigos-de-erro)
7. [Exemplos Práticos](#exemplos-práticos)

---

## Visão Geral

API RESTful **100% stateless** para o ciclo de vida completo da **NF-e modelo 55**, construída em PHP puro sobre as bibliotecas `nfephp-org/sped-nfe` e `nfephp-org/sped-da`.

### Características Principais
- ✅ **Stateless**: Sem banco de dados, sem estado em disco
- ✅ **Certificado A1 por requisição**: Enviado em Base64 no JSON
- ✅ **Tratamento centralizado de erros**: Respostas padronizadas
- ✅ **Suporte à Reforma Tributária**: IBS/CBS/IS (PL_010)
- ✅ **DIFAL e ICMS-ST**: Totalmente suportado

---

## Configuração e Requisitos

### Requisitos do Sistema
```json
{
  "php": ">=8.2",
  "extensões": [
    "soap", "openssl", "curl", "dom", 
    "libxml", "simplexml", "mbstring", "zlib", "gd"
  ]
}
```

### Instalação
```bash
composer install
composer start   # Servidor em http://0.0.0.0:8080
```

### Testes e Qualidade
```bash
composer test    # PHPUnit
composer cs      # PHP_CodeSniffer (PSR-12)
composer stan    # PHPStan (nível 6)
```

---

## Objeto de Configuração

Todas as requisições que envolvem assinatura ou comunicação com SEFAZ requerem o objeto `config`:

### Estrutura do Config
```json
{
  "config": {
    "certificado": "BASE64_DO_ARQUIVO_PFX_A1",
    "senha": "senha-do-certificado",
    "cnpj": "99999999000191",
    "ambiente": 2,
    "uf": "SP",
    "schemes": "PL_009_V4",
    "versao": "4.00",
    "CSC": "",
    "CSCid": ""
  }
}
```

### Parâmetros do Config

| Campo | Tipo | Obrigatório | Descrição |
|-------|------|-------------|-----------|
| `certificado` | string | ✅ | Certificado Digital A1 em Base64 (arquivo .pfx) |
| `senha` | string | ✅ | Senha do certificado digital |
| `cnpj` | string | ✅ | CNPJ do emitente (apenas números) |
| `ambiente` | integer | ✅ | `1` = Produção, `2` = Homologação |
| `uf` | string | ✅ | UF do emitente (ex: "SP", "RJ", "MG") |
| `schemes` | string | ❌ | Layout da NF-e. Use `PL_010_*` para Reforma Tributária |
| `versao` | string | ❌ | Versão do layout (padrão: "4.00") |
| `CSC` | string | ❌ | Código de Segurança do Contribuinte (NFC-e) |
| `CSCid` | string | ❌ | Identificador do CSC (NFC-e) |

---

## Endpoints da API

Todos os endpoints são **POST** e retornam **application/json** (exceto `/nfe/danfe` com `stream: true`).

### 1. GET /health

**Descrição**: Health check da API

**Request**: Nenhum payload necessário

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

---

### 2. POST /nfe/previa

**Descrição**: Monta e assina a NF-e localmente, gerando XML e DANFE de pré-visualização **sem enviar à SEFAZ**.

**Headers**:
```
Content-Type: application/json
```

**Request Body**:
```json
{
  "config": { /* objeto config */ },
  "payload": { /* dados da NF-e */ },
  "tributacao": { /* tributação padrão (opcional) */ }
}
```

**Response Success (200)**:
```json
{
  "success": true,
  "data": {
    "chave": "35240999999999000191550010000000011234567890",
    "xml": "PD94bWwgdmVyc2lvbj0iMS4wIiBlbmNvZGluZz0iVVRGLTgiPz4...",
    "danfe": "JVBERi0xLjQKJeLjz9MKMSAwIG9iago8PAovVHlwZSAvQ2F0YWxvZw...",
    "ambiente": 2
  }
}
```

**Campos da Response**:
- `chave`: Chave de acesso de 44 dígitos
- `xml`: XML assinado em Base64
- `danfe`: PDF da DANFE em Base64 (com marca d'água "PRE-VISUALIZACAO")
- `ambiente`: 1 (Produção) ou 2 (Homologação)

---

### 3. POST /nfe/emitir

**Descrição**: Fluxo completo de emissão - monta, assina, valida schema, envia à SEFAZ e retorna o XML autorizado (nfeProc).

**Headers**:
```
Content-Type: application/json
```

**Request Body**:
```json
{
  "config": { /* objeto config */ },
  "payload": { /* dados da NF-e */ },
  "tributacao": { /* tributação padrão (opcional) */ },
  "sincrono": true,
  "lote": "000000000000001"
}
```

**Parâmetros Opcionais**:
- `sincrono` (boolean): `true` = síncrono (padrão), `false` = assíncrono
- `lote` (string): Número do lote (15 dígitos). Se omitido, gera automaticamente

**Response Success (200)**:
```json
{
  "success": true,
  "data": {
    "status": "autorizado",
    "chave": "35240999999999000191550010000000011234567890",
    "protocolo": "135250000000001",
    "cStat": "100",
    "xMotivo": "Autorizado o uso da NF-e",
    "recibo": null,
    "xml": "PD94bWwgdmVyc2lvbj0iMS4wIiBlbmNvZGluZz0iVVRGLTgiPz4...",
    "ambiente": 2
  }
}
```

**Campos da Response**:
- `status`: Status da autorização ("autorizado")
- `chave`: Chave de acesso de 44 dígitos
- `protocolo`: Número do protocolo de autorização
- `cStat`: Código de status SEFAZ ("100" = autorizado)
- `xMotivo`: Mensagem da SEFAZ
- `recibo`: Número do recibo (apenas em modo assíncrono)
- `xml`: XML autorizado (nfeProc) em Base64
- `ambiente`: 1 (Produção) ou 2 (Homologação)

**cStat de Sucesso**:
- `100`: Autorizado o uso da NF-e
- `150`: Autorizado o uso da NF-e, autorização fora de prazo

---

### 4. POST /nfe/cancelar

**Descrição**: Transmite evento de cancelamento (110111) de uma NF-e já autorizada.

**Headers**:
```
Content-Type: application/json
```

**Request Body**:
```json
{
  "config": { /* objeto config */ },
  "chave": "35240999999999000191550010000000011234567890",
  "protocolo": "135250000000001",
  "justificativa": "Cancelamento por erro no cadastro do cliente"
}
```

**Parâmetros**:
- `chave` (string): Chave de acesso de 44 dígitos
- `protocolo` (string): Número do protocolo de autorização
- `justificativa` (string): Texto com mínimo 15 e máximo 255 caracteres

**Response Success (200)**:
```json
{
  "success": true,
  "data": {
    "evento": "cancelamento",
    "chave": "35240999999999000191550010000000011234567890",
    "cStat": "135",
    "xMotivo": "Evento registrado e vinculado a NF-e",
    "protocolo": "135250000000002",
    "nSeqEvento": 1,
    "xml": "PD94bWwgdmVyc2lvbj0iMS4wIiBlbmNvZGluZz0iVVRGLTgiPz4..."
  }
}
```

**Campos da Response**:
- `evento`: Tipo do evento ("cancelamento")
- `chave`: Chave de acesso
- `cStat`: Código de status ("135", "136" ou "155" = aceito)
- `xMotivo`: Mensagem da SEFAZ
- `protocolo`: Número do protocolo do evento
- `nSeqEvento`: Número sequencial do evento
- `xml`: XML do evento homologado (procEventoNFe) em Base64

---

### 5. POST /nfe/cce

**Descrição**: Transmite Carta de Correção Eletrônica (CC-e) - evento 110110.

**Headers**:
```
Content-Type: application/json
```

**Request Body**:
```json
{
  "config": { /* objeto config */ },
  "chave": "35240999999999000191550010000000011234567890",
  "correcao": "Correcao do endereco de entrega conforme solicitado pelo cliente",
  "sequencia": 1
}
```

**Parâmetros**:
- `chave` (string): Chave de acesso de 44 dígitos
- `correcao` (string): Texto da correção (mínimo 15, máximo 1000 caracteres)
- `sequencia` (integer): Número sequencial do evento (padrão: 1)

**Response Success (200)**:
```json
{
  "success": true,
  "data": {
    "evento": "cce",
    "chave": "35240999999999000191550010000000011234567890",
    "cStat": "135",
    "xMotivo": "Evento registrado e vinculado a NF-e",
    "protocolo": "135250000000003",
    "nSeqEvento": 1,
    "xml": "PD94bWwgdmVyc2lvbj0iMS4wIiBlbmNvZGluZz0iVVRGLTgiPz4..."
  }
}
```

---

### 6. POST /nfe/danfe

**Descrição**: Gera o PDF da DANFE a partir de um XML de NF-e.

**Headers**:
```
Content-Type: application/json
```

**Request Body**:
```json
{
  "xml": "<?xml version=\"1.0\" encoding=\"UTF-8\"?>...",
  "ambiente": 2,
  "stream": false
}
```

**Parâmetros**:
- `xml` (string): XML da NF-e (pode ser raw ou Base64)
- `ambiente` (integer): `1` = Produção, `2` = Homologação (opcional)
- `stream` (boolean): `true` = retorna PDF binário, `false` = retorna Base64 (padrão)

**Response Success (200) - stream: false**:
```json
{
  "success": true,
  "data": {
    "ambiente": 2,
    "danfe": "JVBERi0xLjQKJeLjz9MKMSAwIG9iago8PAovVHlwZSAvQ2F0YWxvZw..."
  }
}
```

**Response Success (200) - stream: true**:
```
Content-Type: application/pdf
Content-Disposition: inline; filename="danfe.pdf"

[PDF binário]
```

**Nota**: Em ambiente de homologação (2), a marca d'água "SEM VALOR FISCAL" é aplicada automaticamente.

---

### 7. POST /nfe/dfe

**Descrição**: Distribuição de DF-e e manifestação do destinatário.

**Headers**:
```
Content-Type: application/json
```

#### 7.1. Consulta por NSU

**Request Body**:
```json
{
  "config": { /* objeto config */ },
  "acao": "consulta",
  "ultNSU": 0,
  "numNSU": null
}
```

**Parâmetros**:
- `acao` (string): "consulta" ou "nsu"
- `ultNSU` (integer): Último NSU recebido (0 para buscar desde o início)
- `numNSU` (integer): NSU específico para consulta (opcional)

**Response Success (200)**:
```json
{
  "success": true,
  "acao": "consulta",
  "data": {
    "cStat": "138",
    "xMotivo": "Documento localizado",
    "ultNSU": "000000000000123",
    "maxNSU": "000000000000456",
    "documentos": [
      {
        "NSU": "000000000000123",
        "schema": "resNFe",
        "chave": "35240999999999000191550010000000011234567890",
        "xml": "PD94bWwgdmVyc2lvbj0iMS4wIiBlbmNvZGluZz0iVVRGLTgiPz4..."
      }
    ]
  }
}
```

#### 7.2. Manifestação do Destinatário

**Request Body**:
```json
{
  "config": { /* objeto config */ },
  "acao": "manifestacao",
  "tipo": "confirmacao",
  "chave": "35240999999999000191550010000000011234567890",
  "justificativa": "",
  "sequencia": 1
}
```

**Parâmetros**:
- `acao` (string): "manifestacao" ou "manifestar"
- `tipo` (string): "ciencia", "confirmacao", "desconhecimento", "nao_realizada"
- `chave` (string): Chave de acesso de 44 dígitos
- `justificativa` (string): Obrigatória para tipo "nao_realizada" (mín. 15 caracteres)
- `sequencia` (integer): Número sequencial do evento (padrão: 1)

**Response Success (200)**:
```json
{
  "success": true,
  "acao": "manifestacao",
  "data": {
    "evento": "manifestacao",
    "tipo": "confirmacao",
    "chave": "35240999999999000191550010000000011234567890",
    "cStat": "135",
    "xMotivo": "Evento registrado e vinculado a NF-e",
    "protocolo": "135250000000004",
    "xml": "PD94bWwgdmVyc2lvbj0iMS4wIiBlbmNvZGluZz0iVVRGLTgiPz4..."
  }
}
```

---

## Estrutura de Payloads

### Estrutura Completa do Payload da NF-e

```json
{
  "infNFe": {
    "versao": "4.00"
  },
  "ide": {
    "cUF": 35,
    "natOp": "VENDA DE MERCADORIA",
    "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 EMITENTE LTDA",
    "xFant": "EMPRESA EMITENTE",
    "IE": "123456789012",
    "CRT": 3
  },
  "enderEmit": {
    "xLgr": "RUA EXEMPLO",
    "nro": "100",
    "xBairro": "CENTRO",
    "cMun": 3550308,
    "xMun": "SAO PAULO",
    "UF": "SP",
    "CEP": "01000000",
    "cPais": 1058,
    "xPais": "BRASIL",
    "fone": "1133334444"
  },
  "dest": {
    "CNPJ": "88888888000188",
    "xNome": "CLIENTE DESTINATARIO LTDA",
    "indIEDest": 1,
    "IE": "987654321098",
    "email": "cliente@exemplo.com.br"
  },
  "enderDest": {
    "xLgr": "AVENIDA EXEMPLO",
    "nro": "200",
    "xBairro": "JARDIM EXEMPLO",
    "cMun": 3550308,
    "xMun": "SAO PAULO",
    "UF": "SP",
    "CEP": "02000000",
    "cPais": 1058,
    "xPais": "BRASIL",
    "fone": "1144445555"
  },
  "det": [
    {
      "prod": {
        "cProd": "PROD001",
        "cEAN": "SEM GTIN",
        "xProd": "PRODUTO EXEMPLO",
        "NCM": "12345678",
        "CFOP": "5102",
        "uCom": "UN",
        "qCom": 10.0,
        "vUnCom": 100.00,
        "vProd": 1000.00,
        "cEANTrib": "SEM GTIN",
        "uTrib": "UN",
        "qTrib": 10.0,
        "vUnTrib": 100.00,
        "indTot": 1
      },
      "imposto": {
        "vTotTrib": 150.00
      },
      "icms": {
        "orig": 0,
        "CST": "00",
        "modBC": 0,
        "vBC": 1000.00,
        "pICMS": 18.00,
        "vICMS": 180.00
      },
      "pis": {
        "CST": "01",
        "vBC": 1000.00,
        "pPIS": 1.65,
        "vPIS": 16.50
      },
      "cofins": {
        "CST": "01",
        "vBC": 1000.00,
        "pCOFINS": 7.60,
        "vCOFINS": 76.00
      }
    }
  ],
  "total": {
    "icmstot": {
      "vBC": 1000.00,
      "vICMS": 180.00,
      "vICMSDeson": 0.00,
      "vFCP": 0.00,
      "vBCST": 0.00,
      "vST": 0.00,
      "vFCPST": 0.00,
      "vFCPSTRet": 0.00,
      "vProd": 1000.00,
      "vFrete": 0.00,
      "vSeg": 0.00,
      "vDesc": 0.00,
      "vII": 0.00,
      "vIPI": 0.00,
      "vIPIDevol": 0.00,
      "vPIS": 16.50,
      "vCOFINS": 76.00,
      "vOutro": 0.00,
      "vNF": 1000.00,
      "vTotTrib": 150.00
    }
  },
  "transp": {
    "modFrete": 9
  },
  "pag": {
    "detPag": [
      {
        "indPag": 0,
        "tPag": "01",
        "vPag": 1000.00
      }
    ]
  },
  "infAdic": {
    "infCpl": "Informacoes complementares da nota fiscal"
  }
}
```

### Objeto Tributação (Opcional)

O objeto `tributacao` permite definir regras tributárias padrão que serão aplicadas a todos os itens que não definirem suas próprias regras:

```json
{
  "tributacao": {
    "icms": {
      "orig": 0,
      "CST": "00",
      "modBC": 0,
      "pICMS": 18.00
    },
    "pis": {
      "CST": "01",
      "pPIS": 1.65
    },
    "cofins": {
      "CST": "01",
      "pCOFINS": 7.60
    }
  }
}
```

### Blocos Tributários Suportados

| Bloco JSON | Método Make | Uso |
|------------|-------------|-----|
| `icms` | `tagICMS` | ICMS regime normal (CST) |
| `icmssn` | `tagICMSSN` | ICMS Simples Nacional (CSOSN) |
| `icmspart` | `tagICMSPart` | ICMS Partilha |
| `icmsst` | `tagICMSST` | ICMS Substituição Tributária |
| `icmsufdest` | `tagICMSUFDest` | DIFAL (ICMS interestadual) |
| `ipi` | `tagIPI` | IPI |
| `ii` | `tagII` | Imposto de Importação |
| `pis` | `tagPIS` | PIS |
| `pisst` | `tagPISST` | PIS ST |
| `cofins` | `tagCOFINS` | COFINS |
| `cofinsst` | `tagCOFINSST` | COFINS ST |
| `issqn` | `tagISSQN` | ISS |
| `is` | `tagIS` | Imposto Seletivo (Reforma Tributária) |
| `ibscbs` | `tagIBSCBS` | IBS/CBS (Reforma Tributária) |

---

## Respostas e Códigos de Erro

### Estrutura de Resposta de Sucesso

```json
{
  "success": true,
  "data": { /* dados específicos do endpoint */ }
}
```

### Estrutura de Resposta de Erro

```json
{
  "success": false,
  "error": {
    "code": "validation_error",
    "message": "Mensagem de erro descritiva",
    "details": { /* detalhes adicionais */ }
  }
}
```

### Códigos de Status HTTP

| Status | Significado | Quando Ocorre |
|--------|-------------|---------------|
| 200 | OK | Requisição processada com sucesso |
| 400 | Bad Request | Payload inválido, JSON malformado |
| 404 | Not Found | Rota não encontrada |
| 422 | Unprocessable Entity | Rejeição de negócio da SEFAZ (cStat ≠ 100) |
| 500 | Internal Server Error | Erro inesperado no servidor |
| 502 | Bad Gateway | SEFAZ fora do ar ou falha de comunicação |

### Códigos de Erro da API

| Código | HTTP | Descrição |
|--------|------|-----------|
| `validation_error` | 400 | Erro de validação do payload |
| `not_found` | 404 | Rota não encontrada |
| `sefaz_rejection` | 422 | NF-e ou evento rejeitado pela SEFAZ |
| `sefaz_unavailable` | 502 | SEFAZ indisponível ou timeout |
| `internal_error` | 500 | Erro interno não tratado |
| `bootstrap_error` | 500 | Falha ao inicializar a aplicação |

### Códigos cStat da SEFAZ (Principais)

#### Autorização de NF-e
- `100`: Autorizado o uso da NF-e
- `150`: Autorizado o uso da NF-e, autorização fora de prazo
- `539`: Rejeição: Duplicidade de NF-e
- `204`: Rejeição: Duplicidade de NF-e
- `301`: Uso Denegado: Irregularidade fiscal do emitente

#### Eventos
- `128`: Lote de evento processado
- `135`: Evento registrado e vinculado a NF-e
- `136`: Evento registrado, mas não vinculado a NF-e
- `155`: Cancelamento homologado fora de prazo

#### Lote Assíncrono
- `103`: Lote recebido com sucesso
- `104`: Lote processado
- `105`: Lote em processamento

---

## Exemplos Práticos

### Exemplo 1: Emissão Completa de NF-e

```bash
curl -X POST http://localhost:8080/nfe/emitir \
  -H "Content-Type: application/json" \
  -d '{
    "config": {
      "certificado": "MIIJqQIBAzCCCW8GCSqGSIb3DQEHAaCCCWAEgglcMIIJWDCCA...",
      "senha": "senha123",
      "cnpj": "99999999000191",
      "ambiente": 2,
      "uf": "SP",
      "schemes": "PL_009_V4",
      "versao": "4.00"
    },
    "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",
        "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",
        "indIEDest": 1,
        "IE": "987654321098"
      },
      "enderDest": {
        "xLgr": "AV TESTE",
        "nro": "200",
        "xBairro": "JARDIM",
        "cMun": 3550308,
        "xMun": "SAO PAULO",
        "UF": "SP",
        "CEP": "02000000",
        "cPais": 1058,
        "xPais": "BRASIL"
      },
      "det": [
        {
          "prod": {
            "cProd": "001",
            "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
      }
    },
    "sincrono": true
  }'
```

### Exemplo 2: Pré-visualização

```bash
curl -X POST http://localhost:8080/nfe/previa \
  -H "Content-Type: application/json" \
  -d '{
    "config": { /* mesmo config do exemplo 1 */ },
    "payload": { /* mesmo payload do exemplo 1 */ },
    "tributacao": { /* mesma tributação do exemplo 1 */ }
  }'
```

### Exemplo 3: Cancelamento

```bash
curl -X POST http://localhost:8080/nfe/cancelar \
  -H "Content-Type: application/json" \
  -d '{
    "config": {
      "certificado": "MIIJqQIBAzCCCW8GCSqGSIb3DQEHAaCCCWAEgglcMIIJWDCCA...",
      "senha": "senha123",
      "cnpj": "99999999000191",
      "ambiente": 2,
      "uf": "SP"
    },
    "chave": "35240999999999000191550010000000011234567890",
    "protocolo": "135250000000001",
    "justificativa": "Cancelamento solicitado pelo cliente devido a erro no pedido"
  }'
```

### Exemplo 4: Carta de Correção

```bash
curl -X POST http://localhost:8080/nfe/cce \
  -H "Content-Type: application/json" \
  -d '{
    "config": {
      "certificado": "MIIJqQIBAzCCCW8GCSqGSIb3DQEHAaCCCWAEgglcMIIJWDCCA...",
      "senha": "senha123",
      "cnpj": "99999999000191",
      "ambiente": 2,
      "uf": "SP"
    },
    "chave": "35240999999999000191550010000000011234567890",
    "correcao": "Correcao do endereco de entrega: Rua Corrigida, 300",
    "sequencia": 1
  }'
```

### Exemplo 5: Gerar DANFE

```bash
# Retornar Base64
curl -X POST http://localhost:8080/nfe/danfe \
  -H "Content-Type: application/json" \
  -d '{
    "xml": "<?xml version=\"1.0\" encoding=\"UTF-8\"?><nfeProc>...</nfeProc>",
    "ambiente": 2,
    "stream": false
  }'

# Retornar PDF binário
curl -X POST http://localhost:8080/nfe/danfe \
  -H "Content-Type: application/json" \
  -d '{
    "xml": "<?xml version=\"1.0\" encoding=\"UTF-8\"?><nfeProc>...</nfeProc>",
    "ambiente": 2,
    "stream": true
  }' --output danfe.pdf
```

### Exemplo 6: Consulta DFe

```bash
curl -X POST http://localhost:8080/nfe/dfe \
  -H "Content-Type: application/json" \
  -d '{
    "config": {
      "certificado": "MIIJqQIBAzCCCW8GCSqGSIb3DQEHAaCCCWAEgglcMIIJWDCCA...",
      "senha": "senha123",
      "cnpj": "99999999000191",
      "ambiente": 2,
      "uf": "SP"
    },
    "acao": "consulta",
    "ultNSU": 0
  }'
```

### Exemplo 7: Manifestação do Destinatário

```bash
curl -X POST http://localhost:8080/nfe/dfe \
  -H "Content-Type: application/json" \
  -d '{
    "config": {
      "certificado": "MIIJqQIBAzCCCW8GCSqGSIb3DQEHAaCCCWAEgglcMIIJWDCCA...",
      "senha": "senha123",
      "cnpj": "99999999000191",
      "ambiente": 2,
      "uf": "SP"
    },
    "acao": "manifestacao",
    "tipo": "confirmacao",
    "chave": "35240999999999000191550010000000011234567890"
  }'
```

---

## Notas Importantes

### Certificado Digital
- Deve ser do tipo **A1** (arquivo .pfx)
- Converter para Base64: `base64 certificado.pfx`
- Manter a senha segura (não versionar)

### Ambientes
- **Homologação (2)**: Para testes, sem validade fiscal
- **Produção (1)**: Notas com validade fiscal

### Reforma Tributária
- Para habilitar IBS/CBS/IS, use `"schemes": "PL_010_V1.30"` (ou versão superior)
- Adicione os blocos `ibscbs` e `is` nos itens
- Inclua `ibscbstot` e `istot` nos totais

### Validações
- Chave de acesso: 44 dígitos numéricos
- Justificativa de cancelamento: 15-255 caracteres
- Texto de CC-e: 15-1000 caracteres
- CNPJ: apenas números

### Performance
- API stateless: cada requisição é independente
- Sem cache: certificado é carregado a cada chamada
- Para alto volume, considere pool de conexões no cliente

---

## Suporte e Contribuições

Para dúvidas, issues ou contribuições, consulte o repositório oficial do projeto.