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.
npxskills add majiayu000/claude-skill-registry--skill "Fiscalzen SEFAZ"Loading…
"type": "module")@fiscalzen/sefaz-client (NF-e/CT-e/MDF-e)@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).
Aplicar mudanças relacionadas a SEFAZ mantendo consistência com a codebase:
@fiscalzen/sefaz-client) em vez de reimplementar SOAP/assinatura/certificadopackages/sefaz-client/src/client.ts → política de timeout/retry/backoff, https.Agent, dispose(), loggingpackages/sefaz-client/src/soap-client.ts + src/soap/envelope.ts → SOAP + envelopepackages/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)apps/api/src/modules/manifestacao/service.ts → fluxo real de manifestação + persistênciaapps/api/src/modules/certificates/* → validação de certificados (gate antes de SEFAZ)apps/api/src/modules/documents/* → documento + status/manifestaçõesapps/api/src/jobs/queues.ts → criação/agenda de jobs SEFAZapps/api/src/modules/nsu/* + packages/database/src/schema/nsu-control.ts → controle de NSU/syncSe a chamada vier do apps/api, não chame SEFAZ sem passar pelo gate:
company.certificate e company.certificatePassword existemrejectUnauthorized)No apps/api, problemas da SEFAZ devem virar erro de serviço externo (padrão do projeto), mantendo mensagem útil.
packages/sefaz-client/src/client.ts✅ Regra: se você precisar mudar retry/backoff/timeout, faça no client (não espalhe retry pelos services).
Recomendação de implementação consistente:
SoapClient / SefazClient (abstração interna)docZip e:
@fiscalzen/xml-parserDistDFeResponse consistentensu e ultNSU sempre como string com 15 dígitos (padStart(15,'0'))CertificadoA1 no formato do @fiscalzen/sefaz-clientenv.SEFAZ_AMBIENTEsucesso=false: lançar ExternalServiceError('SEFAZ', xMotivo)documentEvents + atualizar documents.manifestacaovalidateParams (CNPJ/chave)sucesso=false da SEFAZ → ExternalServiceErrorManifestação (produto)
“Aplique a skill
fiscalzen-sefazpara ajustar o fluxo de manifestação emapps/api.
Preserve o gate de certificado + multi-tenant e mapeie falhas SEFAZ para erro externo padrão. Atualize persistência emdocumentEventsedocuments.manifestacao.”
DistDFe (pacote)
“Aplique a skill
fiscalzen-sefazpara modificarpackages/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.”
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çõespackages/sefaz-client/src/signature.ts → digest/assinatura (helpers)
Create or update AgentSkills. Use when designing, structuring, or packaging skills with scripts, references, and assets.
Create or update AgentSkills. Use when designing, structuring, or packaging skills with scripts, references, and assets.
Set up and use 1Password CLI (op). Use when installing the CLI, enabling desktop app integration, signing in (single or multi-account), or reading/injecting/running secrets via op.
CLI to manage emails via IMAP/SMTP. Use `himalaya` to list, read, write, reply, forward, search, and organize emails from the terminal. Supports multiple accounts and message composition with MML (MIME Meta Language).
Create or update AgentSkills. Use when designing, structuring, or packaging skills with scripts, references, and assets.
Create or update AgentSkills. Use when designing, structuring, or packaging skills with scripts, references, and assets.
Set up and use 1Password CLI (op). Use when installing the CLI, enabling desktop app integration, signing in (single or multi-account), or reading/injecting/running secrets via op.
CLI to manage emails via IMAP/SMTP. Use `himalaya` to list, read, write, reply, forward, search, and organize emails from the terminal. Supports multiple accounts and message composition with MML (MIME Meta Language).