# Integração fiscal NF-e/NFC-e

## Arquitetura

A operação é a fonte das decisões fiscais: se emite, modelo 55/65, finalidade, CFOP estadual/interestadual, consumidor final, destinatário e emissão automática. Empresa define emitente, ambiente, CRT, séries, números e CSC. Produto, cliente e pagamento fornecem os dados do payload.

`FiscalEmissionService` faz pré-validação, monta somente campos documentados, persiste a tentativa, chama o `emissor-api` e grava o retorno. Estoque, caixa e financeiro são finalizados uma única vez pelo fluxo comercial existente; reprocessar a parte fiscal não os executa novamente.

Estados persistidos: `PENDENTE`, `PROCESSANDO`, `AUTORIZADO`, `REJEITADO`, `DENEGADO`, `AGUARDANDO_CONSULTA` e `CANCELADO`. Toda transição vai para `fiscal_documentos_historico`; cancelamento e carta de correção ficam em `fiscal_eventos` e não sobrescrevem o XML original. Alterações sensíveis de configuração são registradas em `fiscal_auditoria`, sem PFX, senha, CSC ou token.

Idempotência é garantida por chave determinística e restrições únicas por conta/origem/modelo, por chave idempotente e pela chave de acesso. Após timeout, o documento fica `AGUARDANDO_CONSULTA` e não oferece reenvio automático.

## Configuração

1. Aplique `database/2026-07-16-008-fluxo-documentos-fiscais.sql`.
2. Defina `API_URL`, `API_TOKEN` e `FISCAL_API_TIMEOUT` no backend.
3. Cadastre a empresa, selecione o ambiente, preencha CRT/séries/CSC e teste o A1.
4. Cadastre os campos fiscais dos produtos e o código SEFAZ das formas de pagamento.
5. Na operação, habilite emissão, escolha 55/65 e preencha os CFOPs.
6. Valide tudo em homologação antes de ativar produção.

O PFX e a senha são enviados ao cofre do `emissor-api`. Depois de uma sincronização aceita, novos cadastros não mantêm esses valores no banco principal. As listagens nunca retornam PFX, senha ou CSC. O endpoint documentado de certificado retorna CNPJ e validade; emissor, serial e cadeia do titular não podem ser exibidos sem ampliar o contrato da API.

## Endpoints internos

- `POST /private/fiscal/documentos/listar`
- `GET /private/fiscal/documentos/{id}`
- `GET /private/fiscal/documentos/{id}/xml`
- `GET /private/fiscal/documentos/{id}/pdf`
- `POST /private/fiscal/documentos/{id}/cancelar`
- `POST /private/fiscal/documentos/{id}/carta-correcao`
- `POST /private/fiscal/vendas/{id}/pre-validar`
- `POST /private/fiscal/vendas/{id}/preview`
- `POST /private/fiscal/vendas/{id}/emitir`
- `POST /private/fiscal/compras/{id}/pre-validar`
- `POST /private/fiscal/compras/{id}/preview`
- `POST /private/fiscal/compras/{id}/emitir`

As rotas legadas de NF-e/NFC-e foram preservadas, mas agora respeitam o modelo configurado na operação.

## Limites confirmados da API fiscal

- A API administra a numeração. A documentação registra como pendência do próprio emissor tornar o incremento transacional; o Muirasoft não envia um número inventado.
- Não existe endpoint documentado de consulta por identificador de processamento/idempotência. Respostas 202 e timeout exigem reconciliação futura no emissor; reenvio fica bloqueado para evitar nota duplicada.
- `indicador_presenca` é armazenado na operação, mas o contrato atual fixa `indPres` na NFC-e e não aceita esse campo na NF-e. Ele não é enviado como campo não documentado.
- Consulta de situação, inutilização e manifestação não possuem rotas documentadas e não foram simuladas.
- Preview fiscal remoto existe somente para NF-e 55 em `POST /fiscal/nfe/preview`. Para NFC-e 65, o Muirasoft oferece apenas pré-validação e resumo local, sem DANFE e sem simular rota externa.
- O contrato permite criar/atualizar empresa e substituir/testar certificado, mas não documenta remoção do A1 no cofre do emissor. A interface não oferece uma remoção local enganosa; essa ação depende de endpoint oficial.
- Compra configurada para emissão gera somente NF-e própria de entrada (modelo 55). O emissor define `tpNF=0` a partir de CFOP iniciado por 1, 2 ou 3; o fornecedor ocupa o objeto `cliente` exigido pelo contrato de `NFeRequest`. NFC-e em compra é bloqueada porque o emissor fixa o modelo 65 como operação de varejo/saída.
- A emissão de entrada não substitui importação, manifestação ou escrituração de uma NF-e já emitida pelo fornecedor; esses fluxos continuam dependendo de contrato adicional.

## Testes sem efeito fiscal

```powershell
cd back
php tests/FiscalApiContractTest.php
php tests/FiscalSchemaTest.php

cd ../front
npm run type-check
npm run build
```

Os testes usam respostas HTTP simuladas e inspeção do schema. Eles não emitem nem cancelam documentos reais.