---
type: skill
name: Fiscalzen SEFAZ
description: "Integrações SEFAZ (NF-e/CT-e/MDF-e) no padrão FiscalZen: DistDFe, Manifestação e eventos — com certificados A1, SOAP, retry/backoff e persistência no produto."
skillSlug: fiscalzen-sefaz
phases: [E, V]
generated: 2026-01-28
status: filled
scaffoldVersion: "2.0.0"
---

## 🏗️ Contexto do Projeto (como o FiscalZen é estruturado)
- Monorepo com **pnpm-workspace** + **Turborepo**
- Código em **TypeScript** (ESM `"type": "module"`)
- Backend: **Fastify 4** (apps/api)
- Jobs: **BullMQ** (workers + scheduler)
- Persistência: **Drizzle ORM** + PostgreSQL
- Cache/queues: Redis
- Logging: **Pino**
- Pacote fiscal principal: `@fiscalzen/sefaz-client` (NF-e/CT-e/MDF-e)
- Parser fiscal: `@fiscalzen/xml-parser` (usado pelo sefaz-client e api)

✅ Regra: alterações de SEFAZ geralmente tocam **packages/** (cliente) e/ou **apps/api/** (orquestração + persistência).

---

## 🎯 Objetivo (o que esta skill resolve)
Aplicar mudanças relacionadas a SEFAZ mantendo consistência com a codebase:
- Preferir abstrações internas (`@fiscalzen/sefaz-client`) em vez de reimplementar SOAP/assinatura/certificado
- Validar certificado e permissões no backend antes de chamar SEFAZ
- Respeitar retry/backoff e throttling
- Persistir eventos e atualizar documentos do jeito do produto
- Garantir validação (unit/integration + homolog)

---

## 🧭 Onde mexer (mapa rápido)

### Cliente SEFAZ (packages/sefaz-client)
- `packages/sefaz-client/src/client.ts` → política de timeout/retry/backoff, `https.Agent`, `dispose()`, logging
- `packages/sefaz-client/src/soap-client.ts` + `src/soap/envelope.ts` → SOAP + envelope
- `packages/sefaz-client/src/services/*` → implementações por domínio:
  - `nfe-distdfe.ts` (DistDFe NF-e)
  - `cte-distdfe.ts`, `mdfe-distdfe.ts` (DistDFe CT-e/MDF-e)
  - `manifestacao.ts` (eventos do destinatário)
  - `event-query.ts` (consulta eventos)
  - `cte-events.ts` (eventos CT-e)
- `packages/sefaz-client/src/types.ts` → contratos + erros tipados (`SefazError`, `TimeoutError`, `CertificadoError`, etc.)
- `packages/sefaz-client/src/certificate.ts` → A1 (PFX), cache/invalidação, validações
- `packages/sefaz-client/src/signature.ts` → digest/assinatura (helpers)

### Produto (apps/api)
- `apps/api/src/modules/manifestacao/service.ts` → fluxo real de manifestação + persistência
- `apps/api/src/modules/certificates/*` → validação de certificados (gate antes de SEFAZ)
- `apps/api/src/modules/documents/*` → documento + status/manifestações
- `apps/api/src/jobs/queues.ts` → criação/agenda de jobs SEFAZ
- `apps/api/src/modules/nsu/*` + `packages/database/src/schema/nsu-control.ts` → controle de NSU/sync

---

## ✅ Regras obrigatórias (gates)

### 1) Sempre validar certificado antes de chamar SEFAZ (no produto)
Se a chamada vier do `apps/api`, **não chame SEFAZ sem passar pelo gate**:
- empresa existe
- `company.certificate` e `company.certificatePassword` existem
- certificado **não expirou**
- (se aplicável) tenantId correto (multi-tenant)

### 2) Não vazar segredo (PFX/senha)
- nunca logar senha do certificado
- nunca logar buffer do PFX
- ao logar erro, sanitize campos sensíveis

### 3) TLS estrito
- não desabilitar validação TLS (`rejectUnauthorized`)

### 4) Erros externos padronizados
No `apps/api`, problemas da SEFAZ devem virar erro de serviço externo (padrão do projeto), mantendo mensagem útil.

---

## 🔁 Retry/Backoff e Throttling (padrão FiscalZen)

### Ponto único de política: `packages/sefaz-client/src/client.ts`
✅ Regra: se você precisar mudar retry/backoff/timeout, faça **no client** (não espalhe retry pelos services).

### Throttling (ex.: cStat 656)
Recomendação de implementação consistente:
- tratar como erro recuperável
- aplicar retry com backoff exponencial + jitter
- evitar tempestade: preferir job/queue para processar em série por empresa/UF

---

## 📦 DistDFe (Golden Path) — como fazer no FiscalZen

### Cenários típicos
- Consulta por **último NSU** (sync contínuo)
- Consulta por **NSU específico**
- Consulta por **chave** (pontual)

### Padrão de implementação
1) Validar parâmetros (CNPJ, chave, nsu/ultNSU)
2) Montar request XML conforme tipo de consulta
3) Enviar via `SoapClient` / `SefazClient` (abstração interna)
4) Parsear retorno (cStat/xMotivo/ultNSU/maxNSU)
5) Extrair `docZip` e:
   - decodificar
   - detectar schema
   - derivar tipo/chave usando `@fiscalzen/xml-parser`
6) Retornar `DistDFeResponse` consistente
7) Se estiver no produto (apps/api): persistir e atualizar controle de NSU

### Regras de robustez
- `nsu` e `ultNSU` sempre como string com 15 dígitos (`padStart(15,'0')`)
- docZip inválido **não deve derrubar o lote inteiro** (registrar erro e seguir)
- ao tratar throttling, preferir política central no client

---

## 🧾 Manifestação do Destinatário (Golden Path) — padrão do produto

### Passo a passo (apps/api)
1) obter empresa com certificado (gate)
2) buscar documento por chave **com tenantId**
3) montar `CertificadoA1` no formato do `@fiscalzen/sefaz-client`
4) usar `env.SEFAZ_AMBIENTE`
5) chamar o client do pacote
6) se `sucesso=false`: lançar `ExternalServiceError('SEFAZ', xMotivo)`
7) persistir em `documentEvents` + atualizar `documents.manifestacao`

### Regras específicas
- eventos devem ser idempotentes na camada do produto (não duplicar o mesmo evento sem necessidade)
- manter rastreabilidade (documentId/chave/tipoEvento/protocolo/dataRegistro)

---

## 🧪 Validação (Fase V) — mínimo obrigatório

### Unit / pacote (sefaz-client)
- validar `validateParams` (CNPJ/chave)
- validar montagem de request por ultNSU/nsu/chave
- validar parsing de resposta (cStat e campos)
- validar docZip: sucesso e falha isolada

### Integration / produto (apps/api)
- empresa sem certificado → erro de validação
- certificado expirado → erro de validação
- documento inexistente → NotFound
- retorno `sucesso=false` da SEFAZ → ExternalServiceError
- persistência: criou event + atualizou documento

### Homologação
- testar ao menos:
  - DistDFe por ultNSU
  - Manifestação (um evento)
  - cenário de throttling (se possível reproduzir)

---

## 🧰 Prompt templates (como invocar a skill)

**Manifestação (produto)**
> “Aplique a skill `fiscalzen-sefaz` para ajustar o fluxo de manifestação em `apps/api`.  
> Preserve o gate de certificado + multi-tenant e mapeie falhas SEFAZ para erro externo padrão. Atualize persistência em `documentEvents` e `documents.manifestacao`.”

**DistDFe (pacote)**
> “Aplique a skill `fiscalzen-sefaz` para modificar `packages/sefaz-client/src/services/nfe-distdfe.ts`.  
> Preserve validações, padStart(15) e parsing docZip com `@fiscalzen/xml-parser`. Se tratar 656, preferir política central no client.”

---