# Módulo — Emissão de NF-e (modelo 55)

**Nome no produto:** **Emissão de NF-e**
**Nome técnico / rotas:** prefixo `nfe` (emissão), reaproveitando `nf` (venda de mercadoria) e `Caixa de Entrada Fiscal` (`dfe`) para armazenamento/consulta.
**Público:** comércio/indústria com ICMS, multiempresa/multitenant (`idtenant`).
**Certificado:** A1 (PFX/P12), reaproveitando `EmpresaCertificadoSefaz` + `CertificadoA1Service`.
**Biblioteca fiscal:** `nfephp-org/sped-nfe` v5 + `sped-da` (DANFE) — **comunicação direta com SEFAZ** (sem Tecnospeed).

**Status:** **Fase 1 implementada** — fundação (DB, config, services, prévia na venda). **Fase 2 em seguida:** tributação ICMS nos cadastros + montagem XML.

**Relacionados:** `Doc_Modulo_NFSe_Emissao.md`, `Doc_Modulo_Caixa_Entrada_Fiscal.md`, `Doc_Modulo_Produto_Servico.md`, `Doc_Modulo_Financeiro.md`.

> **Diretriz estratégica:** emissão própria via NFePHP + certificado A1, espelhando o padrão arquitetural da NFS-e (`NfseEmissaoService` → Provider → SEFAZ). Sem intermediários. Regras fiscais parametrizáveis por perfil tributário, produto e natureza de operação — nunca hardcoded.

---

## 1. Diagnóstico — o que já existe e é reaproveitável

| Componente | Papel atual | Uso na emissão |
|---|---|---|
| `EmpresaCertificadoSefaz` | Certificado A1, ambiente, NSU DistDFe, numeração DPS | **Base do certificado** + **série/sequencial NF-e** (a adicionar) |
| `CertificadoA1Service` | Lê PFX, extrai PEM, valida CNPJ | **Crítico — assinatura XML NF-e** |
| `SpedNfeConfigFactory` | Monta `NFePHP\NFe\Tools` com config JSON | **Reuso direto** para envio/consulta/cancelamento SEFAZ |
| `DfeDistribuicaoService` | DistDFe via `sefazDistDFe` | Padrão de parse de retorno SEFAZ (`cStat`, `xMotivo`) |
| `DfePdfArmazenamentoService` | Gera DANFE via `NFePHP\DA\NFe\Danfe` | **Reuso** para PDF pós-autorização |
| `DfeDocumento` / `DfeStorageService` | Repositório unificado | Destino do XML/PDF autorizado (`NFE_EMITIDA`) |
| `Nf` (`nf`) | Venda de mercadoria (`tipo_documento_fiscal='NFE'`) | Documento de origem da NF-e |
| `NfItem` (`nfitem`) | Itens da venda com NCM, valores rateados | Base dos itens da NF-e |
| `NaturezaOperacao` | CFOP interno/interestadual, `tpnf` | Natureza e CFOP automático (UF empresa × cliente) |
| `NaturezaOperacaoNfService` | Aplica CFOP na venda | **Reuso** no pré-emissão |
| `ProdutoServico` (`prodserv`) | NCM, unidade, preço | **+ tributação ICMS/IPI/PIS/COFINS** (a expandir) |
| `PerfilTributario` | Padrões fiscais reutilizáveis | Hoje focado em ISS — **expandir para ICMS** |
| `Nfe` / `NfeItem` (`nfes`) | Parser de XML importado (compras) | **Não reutilizar** para emissão — criar `nfe_emissao` |
| `nfephp-org/sped-nfe` | DistDFe, Tools SEFAZ | `Make`, `sefazEnviaLote`, `sefazCancela`, `sefazCCe`, `sefazInutiliza` |
| `nfephp-org/sped-da` | DANFE | PDF pós-autorização |

### Lacunas principais (a criar)

- **Tabela `nfe_emissao`** (1:1 com `nf`) — ciclo de vida da emissão (distinto de `nfes` que é importação)
- **Tabela `nfe_emissao_logs`** — auditoria de tentativas
- **Campos ICMS em `prodserv` / `perfil_tributario`**: origem, CST/CSOSN, alíquota ICMS, redução BC, IPI, PIS/COFINS produto
- **Campos em `empresa_certificado_sefaz`**: série NF-e, próximo número homolog/prod
- **Config `config/nfe.php`**: versão leiaute, schemes, flags contingência, token IBPT
- **Serviços `app/Services/Nfe/`**: orquestração, montagem XML, tributação, validação, provider SEFAZ
- **UI na venda** (`admin/vendas`): painel emissão espelhando NFS-e (prévia, emitir, cancelar, DANFE, XML)
- **Tributação por item** na venda (override manual opcional, como NFS-e)

---

## 2. Arquitetura (espelhando NFS-e)

```
app/Services/Nfe/
  Contracts/NfeProviderInterface.php
  Dto/NfeEmissaoData.php
  Dto/NfeResultado.php
  Dto/NfeItemTributacao.php
  NfeEmissaoService.php              ← orquestra (sem regra fiscal em controller)
  NfeCancelamentoService.php
  NfePosAutorizacaoService.php       ← DANFE, e-mail, dfe_documentos
  Providers/SefazNfeProvider.php       ← único provider (NFePHP Tools)
  Xml/NfeMakeBuilder.php             ← monta XML via NFePHP\Make
  Xml/NfeAssinaturaService.php       ← assina com certificado A1
  Calculo/NfeTributacaoCalculator.php ← ICMS, IPI, PIS, COFINS por item
  Calculo/NfeCenarioFiscalResolver.php  ← resolve perfil × produto × UF × natureza
  Validators/NfeEmissaoValidator.php  ← pré-validação + validarPreCadastro (UI)
app/Enums/Nfe/NfeStatus.php
app/Models/NfeEmissao.php
app/Jobs/EmitirNfeJob.php
app/Jobs/BaixarDanfeNfeJob.php
app/Console/Commands/NfeTestarEmissaoCommand.php
app/Console/Commands/NfeAlertarCertificadosCommand.php  ← reutilizar nfse:alertar-certificados
config/nfe.php
```

### Fluxo de emissão

```mermaid
flowchart TD
    A[Venda NFE confirmada] --> B[NfeEmissaoService::previa]
    B --> C{Pré-cadastro OK?}
    C -->|Não| D[Modal com pendências]
    C -->|Sim| E[POST emitir]
    E --> F[Reservar número NF-e]
    F --> G[NfeTributacaoCalculator]
    G --> H[NfeEmissaoValidator]
    H --> I[NfeMakeBuilder → XML]
    I --> J[NfeAssinaturaService]
    J --> K[SefazNfeProvider::emitir]
    K --> L{SEFAZ cStat}
    L -->|100/150| M[Autorizado → nfe_emissao]
    L -->|Rejeição| N[REJEITADO + log]
    M --> O[BaixarDanfeNfeJob]
    M --> P[dfe_documentos NFE_EMITIDA]
    M --> Q[nf.nfe = chave]
```

Contrato do provider: `emitir`, `consultar`, `cancelar`, `cartaCorrecao`, `inutilizar`.

---

## 3. Integração SEFAZ (NFePHP)

Reaproveitar `SpedNfeConfigFactory::makeTools()`:

| Operação | Método NFePHP | Quando |
|----------|---------------|--------|
| Envio lote | `sefazEnviaLote($xml, $idLote, $indSinc=1)` | Emissão (síncrono, 1 NF) |
| Consulta recibo | `sefazConsultaRecibo($recibo)` | Se retorno assíncrono |
| Consulta chave | `sefazConsultaChave($chave)` | Resolver nota travada |
| Cancelamento | `sefazCancela($chave, $justificativa, $protocolo)` | Pós-autorização |
| Carta correção | `sefazCCe($chave, $correcao, $nSeq)` | Evento |
| Inutilização | `sefazInutiliza($serie, $nIni, $nFin, $justificativa)` | Numeração |
| Status SEFAZ | `sefazStatus($uf)` | Monitor (opcional) |

**Montagem XML:** `NFePHP\NFe\Make` — tags `infNFe`, `det`, `total`, `transp`, `pag`, etc.

**Assinatura:** NFePHP assina internamente via `Tools` ou `NFePHP\NFe\Common\Standardize` após `Make::getXML()`.

---

## 4. Modelo de dados

### `nfe_emissao` (nova tabela, 1:1 com `nf`)

| Campo | Tipo | Descrição |
|-------|------|-----------|
| `idnf` | FK | Venda origem |
| `idempresa`, `idtenant` | FK | Multiempresa |
| `status` | enum | RASCUNHO, ENVIADO, AUTORIZADO, REJEITADO, CANCELADO, ERRO |
| `ambiente` | string | homologacao \| producao |
| `chave_acesso` | string(44) | Chave NF-e |
| `numero`, `serie` | int/string | Numeração fiscal |
| `protocolo` | string | nProt autorização |
| `data_emissao`, `data_autorizacao`, `data_cancelamento` | datetime | |
| `valor_produtos`, `valor_nf`, `valor_icms`, `valor_ipi`, `valor_pis`, `valor_cofins` | decimal | Totais |
| `xml_enviado_path`, `xml_autorizado_path`, `pdf_path` | string | Storage |
| `mensagem_retorno`, `codigo_erro` | text/string | Retorno SEFAZ |
| `cenario_fiscal` | json | Snapshot do cenário resolvido |
| `idusuario` | FK | Quem emitiu |

### `empresa_certificado_sefaz` (expandir)

| Campo novo | Descrição |
|------------|-----------|
| `serie_nfe` | Série padrão (ex.: 1) |
| `proximo_numero_nfe_homolog` | Sequencial homologação |
| `proximo_numero_nfe_prod` | Sequencial produção |

### `prodserv` / `perfil_tributario` (expandir para ICMS)

| Campo | Descrição |
|-------|-----------|
| `origem_mercadoria` | 0–8 (tabela SPED) |
| `cst_icms` / `csosn` | Conforme regime (Simples vs Normal) |
| `aliquota_icms_padrao` | % ICMS |
| `reducao_bc_icms_padrao` | % redução BC |
| `cst_ipi`, `aliquota_ipi_padrao` | IPI (se aplicável) |
| `cst_pis`, `cst_cofins`, alíquotas | PIS/COFINS produto |

> **Regime tributário** já existe em `empresa.regime_tributario` — define se usa CST ou CSOSN.

---

## 5. Regras de tributação (parametrizáveis)

Resolução em cascata (como `PerfilTributarioResolver` da NFS-e):

1. Override manual na venda/item (opcional)
2. `prodserv` (produto)
3. `perfil_tributario` do produto ou empresa
4. `config/nfe.php` (defaults legais/fallback)

**Cenários a cobrir na Fase 3 (MVP):**

| Cenário | CST/CSOSN típico |
|---------|------------------|
| Simples Nacional — venda interna | CSOSN 102 |
| Lucro Presumido — venda interna tributada | CST 00 |
| Interestadual (cliente outra UF) | CFOP 6.xxx + ICMS interestadual |
| Isento/Não tributado | CST 40/41 ou CSOSN 400/500 |
| Substituição tributária | CST 10/60/70 — **Fase 6** |

**Fora do MVP:** ST, DIFAL, partilha ICMS, medicamentos, combustível, exportação, importação, IBS/CBS (Reforma).

---

## 6. UI / cadastros

Espelhar padrão NFS-e em `admin/vendas/_form.blade.php` + `edit.blade.php`:

| Tela | O que adicionar |
|------|-----------------|
| **Venda (NFE)** | Painel emissão: prévia, emitir, status badge, DANFE/XML/cancelar |
| **Empresa** | Série e numeração NF-e (ou no certificado) |
| **Produto** | Bloco "NF-e / ICMS": origem, CST/CSOSN, alíquotas |
| **Perfil tributário** | Campos ICMS/IPI (paralelo ao bloco ISS) |
| **Natureza operação** | Já existe — validar CFOPs para emissão |

Rotas previstas:

```
GET  admin/vendas/{venda}/nfe/previa
POST admin/vendas/{venda}/nfe/emitir
POST admin/vendas/{venda}/nfe/cancelar
GET  admin/vendas/{venda}/nfe/xml
GET  admin/vendas/{venda}/nfe/danfe
POST admin/vendas/{venda}/nfe/enviar-email
```

Controller: `NfeIntegracaoController` (espelho de `NfseIntegracaoController`).

---

## 7. Segurança / compliance

- Certificado/senha nunca em log ou JSON
- Logs de emissão sem XML completo (só chave, cStat, xMotivo)
- Isolamento por tenant (`TenantScope`)
- Homologação obrigatória antes de produção
- Numeração sequencial com `lockForUpdate` (padrão DPS)
- Validação de CNPJ certificado × empresa

---

## 8. Backlog por fases

### Fase 1 — Fundação (2–3 semanas)
- [x] `config/nfe.php`, Enums `NfeStatus`
- [x] Migration `nfe_emissao` + `nfe_emissao_logs`
- [x] Migration campos numeração NF-e em `empresa_certificado_sefaz`
- [x] Migration campos ICMS em `prodserv` e `perfil_tributario` *(colunas; UI Fase 2)*
- [x] Model `NfeEmissao`, relação `Nf::nfeEmissao()`
- [x] Esqueleto `NfeEmissaoService`, DTOs, `NfeProviderInterface`
- [x] `NfeIntegracaoController` (rotas previa/emitir)
- [x] UI: painel básico na venda (prévia com pendências)

### Fase 2 — Montagem XML + tributação MVP (3–4 semanas)
- [x] `NfeCenarioFiscalResolver` + `NfeTributacaoCalculator` (Simples + LP básico)
- [x] `NfeMakeBuilder` (ide, emit, dest, det, total, transp, pag) — esqueleto funcional
- [x] `NfeEmissaoValidator` — tributação ICMS (origem, CST/CSOSN por regime)
- [ ] `NfeAssinaturaService` (via NFePHP) — Fase 3
- [x] Formulários: produto + perfil tributário ICMS
- [x] `php artisan nfe:testar-emissao {idnf}` (dry-run; `--mostrar-xml`)
- [x] Prévia na venda com resumo tributário calculado

### Fase 3 — Envio SEFAZ homologação (2–3 semanas)
- [x] `SefazNfeProvider` (`sefazEnviaLote` síncrono + retry)
- [x] `NfeAssinaturaService` (NFePHP `signNFe`)
- [x] Parse retorno (`cStat` 100/150/104)
- [x] Persistência `nfe_emissao` + atualizar `nf.nfe` (chave)
- [ ] `BaixarDanfeNfeJob` + `dfe_documentos`
- [x] UI: emitir com feedback (quando `NFE_EMISSAO_HABILITADA=true`)
- [ ] Testes em homologação (ambiente 2) — validar com certificado real

### Fase 4 — Pós-emissão (2 semanas)
- [ ] Cancelamento (`sefazCancela`)
- [ ] Consulta chave (resolver travadas)
- [ ] E-mail pós-autorização (reuso template)
- [ ] Download XML/DANFE na venda

### Fase 5 — Operação (2 semanas)
- [ ] `EmitirNfeJob` (fila assíncrona para contratos/lote)
- [ ] Carta de correção (`sefazCCe`)
- [ ] Inutilização de numeração
- [ ] Monitor status SEFAZ por UF
- [ ] Dashboard emissões / alertas

### Fase 6 — Tributação avançada (contínuo)
- [ ] Substituição tributária (CST 10/60/70)
- [ ] DIFAL / partilha ICMS interestadual
- [ ] IPI, II, PIS/COFINS monofásico
- [ ] Exportação, drawback
- [ ] IBS/CBS (Reforma Tributária)
- [ ] NFC-e (modelo 65) — módulo separado, reuso de ~70% da base

---

## 9. Diferenças vs EMITTE (referência)

| Aspecto | EMITTE | NOLAPIS (este módulo) |
|---------|--------|----------------------|
| Comunicação SEFAZ | Tecnospeed (intermediário) | NFePHP direto |
| Montagem XML | `Montar/NfeService` custom (~1500 linhas) | `NFePHP\Make` + Calculator próprio |
| Pedido | Entidade `Pedidos` separada | `Nf` (venda) existente |
| Frontend | SPA React wizard | Blade modal na venda |
| Custo | Licença Tecnospeed | Apenas certificado A1 |
| Maturidade | Alta (anos) | A construir |

**Referência útil no EMITTE** (lógica de negócio, não código):
- `emitte.emissor.service/.../Montar/NfeService.php` — checklist de tags XML
- `emitte.motorfiscal.service/.../TecnospeedService.php` — fluxo de retorno SEFAZ

---

## 10. Estimativa de esforço

| Fase | Escopo | Estimativa |
|------|--------|------------|
| 1 | Fundação + DB + UI stub | 2–3 semanas |
| 2 | XML + tributação MVP | 3–4 semanas |
| 3 | SEFAZ homologação | 2–3 semanas |
| 4 | Cancelamento + PDF | 2 semanas |
| 5 | Operação (CC-e, fila) | 2 semanas |
| **MVP emissão NF-e** | Fases 1–4 | **~10–12 semanas** |
| 6 | Tributação avançada | Contínuo |

---

*Criado em 2026-07-07. Atualizar a cada subentrega (Fase 1 → 6).*