open-nfse / NfseClient

Class: NfseClient

Defined in: src/client.ts:184

Constructors

Constructor

new NfseClient(config: NfseClientConfig): NfseClient;

Defined in: src/client.ts:199

Parameters

Parameter	Type
config	NfseClientConfig

Returns

NfseClient

Methods

cancelar()

cancelar(params: CancelarParams): Promise<CancelarResult>;

Defined in: src/client.ts:395

Cancela uma NFS-e via evento 101101. Cancelamento simples — sem vínculo de substituição. Para substituição use substituir().

Retorna resultado discriminado:

• { status: 'ok', evento } — cancelamento aceito pela Sefin.
• { status: 'retry_pending', pending } — falha transiente; persistido no RetryStore configurado para replay via replayPendingEvents().

Lança ReceitaRejectionError em rejeições permanentes (prazo expirado, nota já cancelada, regra municipal, etc.) — nesses casos o cancelamento definitivamente não pode proceder sem intervenção manual (outro motivo, análise fiscal, etc.).

Parameters

Parameter	Type
params	CancelarParams

Returns

Promise<CancelarResult>

---

close()

close(): Promise<void>;

Defined in: src/client.ts:743

Libera o dispatcher mTLS (quando a lib construiu um). Idempotente: chamar duas vezes é seguro. Após close(), qualquer nova chamada de método do cliente lança ClientClosedError — reinstancie o NfseClient para voltar a emitir/consultar.

Returns

Promise<void>

---

consultarAliquota()

consultarAliquota(
   codigoMunicipio: string, 
   codigoServico: string, 
   competencia: string | Date, 
options?: ConsultaOptions): Promise<ConsultaAliquotasResult>;

Defined in: src/client.ts:575

Consulta a alíquota de ISSQN parametrizada para município + serviço + competência.

Parameters

Parameter	Type
codigoMunicipio	string
codigoServico	string
competencia	string | Date
options?	ConsultaOptions

Returns

Promise<ConsultaAliquotasResult>

---

consultarBeneficio()

consultarBeneficio(
   codigoMunicipio: string, 
   numeroBeneficio: string, 
   competencia: string | Date, 
options?: ConsultaOptions): Promise<ConsultaBeneficioResult>;

Defined in: src/client.ts:609

Parâmetros de um benefício fiscal municipal (redução, imunidade, alíquota diferenciada, etc.).

Parameters

Parameter	Type
codigoMunicipio	string
numeroBeneficio	string
competencia	string | Date
options?	ConsultaOptions

Returns

Promise<ConsultaBeneficioResult>

---

consultarConvenio()

consultarConvenio(codigoMunicipio: string, options?: ConsultaOptions): Promise<ConsultaConvenioResult>;

Defined in: src/client.ts:627

Status do convênio do município com a Sefin Nacional.

Parameters

Parameter	Type
codigoMunicipio	string
options?	ConsultaOptions

Returns

Promise<ConsultaConvenioResult>

---

consultarDanfse()

consultarDanfse(chaveAcesso: string): Promise<Buffer<ArrayBufferLike>>;

Defined in: src/client.ts:732

Baixa o DANFSe oficial do ADN (GET /danfse/{chaveAcesso}). Só retorna se o PDF veio de fato — erros de rede ou HTTP 4xx/5xx viram exceção. Para fallback automático, use gerarDanfse(nfse).

Parameters

Parameter	Type
chaveAcesso	string

Returns

Promise<Buffer<ArrayBufferLike>>

---

consultarHistoricoAliquotas()

consultarHistoricoAliquotas(
   codigoMunicipio: string, 
   codigoServico: string, 
options?: ConsultaOptions): Promise<ConsultaAliquotasResult>;

Defined in: src/client.ts:593

Histórico completo de alíquotas para município + serviço (independente de competência).

Parameters

Parameter	Type
codigoMunicipio	string
codigoServico	string
options?	ConsultaOptions

Returns

Promise<ConsultaAliquotasResult>

---

consultarRegimesEspeciais()

consultarRegimesEspeciais(
   codigoMunicipio: string, 
   codigoServico: string, 
   competencia: string | Date, 
options?: ConsultaOptions): Promise<ConsultaRegimesEspeciaisResult>;

Defined in: src/client.ts:636

Regimes especiais ativos para município + serviço + competência.

Parameters

Parameter	Type
codigoMunicipio	string
codigoServico	string
competencia	string | Date
options?	ConsultaOptions

Returns

Promise<ConsultaRegimesEspeciaisResult>

---

consultarRetencoes()

consultarRetencoes(
   codigoMunicipio: string, 
   competencia: string | Date, 
options?: ConsultaOptions): Promise<ConsultaRetencoesResult>;

Defined in: src/client.ts:654

Configuração de retenções de ISSQN do município para uma competência.

Parameters

Parameter	Type
codigoMunicipio	string
competencia	string | Date
options?	ConsultaOptions

Returns

Promise<ConsultaRetencoesResult>

---

emitir()

Call Signature

emitir(params: EmitirParams & {
  dryRun: true;
}): Promise<DpsDryRunResult>;

Defined in: src/client.ts:277

Emissão segura — fluxo primário. Recebe params de alto nível (sem nDPS); a lib consulta o DpsCounter configurado só depois de todas as validações offline (CPF/CNPJ, XSD, CEP) passarem, de forma que uma DPS quebrada não queima um número da série.

Resultado discriminado:

• { status: 'ok', nfse } — autorizada.
• { status: 'retry_pending', pending } — falha transiente (rede / timeout / 5xx / 429); salvo no RetryStore para replay via replayPendingEvents().

Lança em falhas permanentes (rejeição fiscal, validação offline). Nesses casos o nDPS foi consumido mas a nota foi definitivamente rejeitada — o caller loga e segue.

Não envolva esta chamada num retry loop próprio para 429 / 5xx. Cada emitir() consome um nDPS antes do POST; um wrapper externo que recapta e retenta queima números da série e cria buracos permanentes. A lib já persiste o pendente no RetryStore e dedupica server-side via infDPS.Id — use replayPendingEvents() (tipicamente num cron) para retomar.

Para emitir uma DPS já montada manualmente (bypass counter + retry flow), use emitirDpsPronta(dps).

Parameters

Parameter	Type
params	EmitirParams & { dryRun: true; }

Returns

Promise<DpsDryRunResult>

Call Signature

emitir(params: EmitirParams & {
  dryRun?: false;
}): Promise<EmitirResult>;

Defined in: src/client.ts:278

Emissão segura — fluxo primário. Recebe params de alto nível (sem nDPS); a lib consulta o DpsCounter configurado só depois de todas as validações offline (CPF/CNPJ, XSD, CEP) passarem, de forma que uma DPS quebrada não queima um número da série.

Resultado discriminado:

• { status: 'ok', nfse } — autorizada.
• { status: 'retry_pending', pending } — falha transiente (rede / timeout / 5xx / 429); salvo no RetryStore para replay via replayPendingEvents().

Lança em falhas permanentes (rejeição fiscal, validação offline). Nesses casos o nDPS foi consumido mas a nota foi definitivamente rejeitada — o caller loga e segue.

Não envolva esta chamada num retry loop próprio para 429 / 5xx. Cada emitir() consome um nDPS antes do POST; um wrapper externo que recapta e retenta queima números da série e cria buracos permanentes. A lib já persiste o pendente no RetryStore e dedupica server-side via infDPS.Id — use replayPendingEvents() (tipicamente num cron) para retomar.

Para emitir uma DPS já montada manualmente (bypass counter + retry flow), use emitirDpsPronta(dps).

Parameters

Parameter	Type
params	EmitirParams & { dryRun?: false; }

Returns

Promise<EmitirResult>

---

emitirDpsPronta()

Call Signature

emitirDpsPronta(dps: DPS, options?: EmitOptions & {
  dryRun?: false;
}): Promise<NfseEmitResult>;

Defined in: src/client.ts:305

Escape hatch — emite uma DPS já completamente montada. Não consulta o counter, não usa o RetryStore. Falhas viram exceção direta. Útil para replay customizado, testes com nDPS determinístico, ou quando você pré-assina o XML externamente.

Parameters

Parameter	Type
dps	DPS
options?	EmitOptions & { dryRun?: false; }

Returns

Promise<NfseEmitResult>

Call Signature

emitirDpsPronta(dps: DPS, options: EmitOptions & {
  dryRun: true;
}): Promise<DpsDryRunResult>;

Defined in: src/client.ts:309

Escape hatch — emite uma DPS já completamente montada. Não consulta o counter, não usa o RetryStore. Falhas viram exceção direta. Útil para replay customizado, testes com nDPS determinístico, ou quando você pré-assina o XML externamente.

Parameters

Parameter	Type
dps	DPS
options	EmitOptions & { dryRun: true; }

Returns

Promise<DpsDryRunResult>

---

emitirEmLote()

emitirEmLote(dpsList: readonly DPS[], options?: EmitLoteOptions): Promise<EmitLoteResult>;

Defined in: src/client.ts:349

Emissão em lote: paraleliza emitirDpsPronta() para uma lista de DPS já montadas (SEFIN não oferece endpoint de batch — a paralelização acontece no cliente, com cap de concorrência). Cada item vira um EmitLoteItem com status: 'success' | 'failure' | 'skipped'.

Não usa DpsCounter nem RetryStore. Cada DPS deve vir com nDPS já preenchido pelo caller, e falhas (incluindo 429 / 5xx) são reportadas como { status: 'failure', dps, error } sem persistência automática. Se o caller quer retry transparente do pipeline emitir(params), ele deve orquestrar emitir(...) calls manualmente. Esta API é deliberadamente mais baixa-nível para casos onde o caller já controla o sequencial.

Em 429 a falha é capturada como failure com error instanceof TooManyRequestsError; o caller pode inspecionar error.getRetryAfterMs() para decidir quando re-emitir os itens que falharam (mesmo nDPS — SEFIN deduplica via infDPS.Id).

Parameters

Parameter	Type
dpsList	readonly DPS[]
options?	EmitLoteOptions

Returns

Promise<EmitLoteResult>

---

existsDpsStatus()

existsDpsStatus(idDps: string): Promise<boolean>;

Defined in: src/client.ts:242

HEAD /dps/{id} — variante barata de fetchDpsStatus que só retorna true/false sem baixar o corpo. Para reconciliação em lote, prefere esse método e busque os detalhes via fetchDpsStatus só nos que existem.

Parameters

Parameter	Type
idDps	string

Returns

Promise<boolean>

---

fetchByChave()

fetchByChave(chaveAcesso: string): Promise<NfseQueryResult>;

Defined in: src/client.ts:217

Parameters

Parameter	Type
chaveAcesso	string

Returns

Promise<NfseQueryResult>

---

fetchByNsu()

fetchByNsu(params: FetchByNsuParams): Promise<NsuQueryResult>;

Defined in: src/client.ts:247

Parameters

Parameter	Type
params	FetchByNsuParams

Returns

Promise<NsuQueryResult>

---

fetchDpsStatus()

fetchDpsStatus(idDps: string): Promise<DpsStatusResult>;

Defined in: src/client.ts:232

GET /dps/{id} — consulta a chave de acesso da NFS-e a partir de um infDPS.Id. Uso primário: reconciliação pós-timeout. Quando um emitir() não retornou (processo morreu, timeout, crash), mas você tem o idDps persistido, essa chamada revela se a Receita chegou a gerar a NFS-e — evita reemissão duplicada.

Lança NotFoundError se nenhuma NFS-e foi gerada a partir desse idDps (resposta 404 do SEFIN).

Parameters

Parameter	Type
idDps	string

Returns

Promise<DpsStatusResult>

---

gerarDanfse()

gerarDanfse(nfse: NFSe, options?: GerarDanfseOptions & {
  strategy?: "auto" | "online" | "local";
}): Promise<Buffer<ArrayBufferLike>>;

Defined in: src/client.ts:691

Gera o DANFSe (PDF) para uma NFS-e. Por default tenta baixar o PDF oficial do ADN e, apenas em falhas transientes (rede/5xx/timeout), cai no renderer local.

Erros de autorização (ForbiddenError, UnauthorizedError), chave inválida (InvalidChaveAcessoError) ou chave inexistente (NotFoundError) não caem para local — eles sobem para o caller, que tipicamente precisa corrigir (cert expirado, CNPJ sem permissão, typo na chave).

Estratégias:

• 'auto' (default) — online-first com fallback local em erros transientes.
• 'online' — só o ADN; lança em qualquer falha.
• 'local' — só o renderer local (offline puro).

Quando cair em 'local', as opções de layout (urlConsultaPublica, observacoes, ambiente) são aplicadas. No modo online elas são ignoradas.

Parameters

Parameter	Type
nfse	NFSe
options?	GerarDanfseOptions & { strategy?: "auto" | "online" | "local"; }

Returns

Promise<Buffer<ArrayBufferLike>>

---

replayPendingEvents()

replayPendingEvents(override?: RetryStore): Promise<ReplayItem[]>;

Defined in: src/client.ts:461

Re-POSTs each PendingEvent in the store. SEFIN deduplication on infDPS.Id (emissão) ou chave + tipoEvento (eventos) garante idempotência: itens já processados retornam o mesmo resultado ou uma rejeição determinística. Em sucesso, o item é removido do store. Em falha transiente, permanece com lastAttemptAt/notBefore/attempts atualizados. Em falha permanente, também é removido e o erro é retornado no item.

Contrato: single-threaded. Esta função NÃO é segura para execução concorrente — dois processos chamando-a ao mesmo tempo veriam a mesma lista, retentariam os mesmos itens, e dobrariam o consumo de rate-limit do SEFIN. Garanta exclusão mútua no caller (e.g., um cron single-instance, lock distribuído via Redis se múltiplos workers compartilham o mesmo RetryStore).

Cuidado com rotação de certificado. O XML persistido foi assinado com o certificado A1 vigente no momento da emissão original. Se você rotacionar o certificado (renovação anual, troca de fornecedor) antes que pendentes drenem, a assinatura ainda é tecnicamente válida desde que o certificado antigo não esteja expirado ou revogado. Mas se a janela de validade do antigo passou, SEFIN rejeita a assinatura como permanente → pendente deletado, operação perdida. Drene o RetryStore via replayPendingEvents antes de instalar o novo certificado.

Consumidores tipicamente chamam isso em um cron a cada 1–5 min.

Parameters

Parameter	Type
override?	RetryStore

Returns

Promise<ReplayItem[]>

---

substituir()

substituir(params: SubstituirParams): Promise<SubstituirResult>;

Defined in: src/client.ts:424

Substitui uma NFS-e: emite a nova (com subst auto-preenchido se ausente) e cancela a original via evento 105102. Retorna um resultado discriminado sobre status:

• 'ok' — ambas as etapas completaram.
• 'retry_pending' — emit ok, cancel falhou transitoriamente; gravamos o pendente em retryStore para replay posterior.
• 'rolled_back' — emit ok, cancel falhou permanentemente; rollback cancelou a nova via evento 101101. Nota: audit trail fica fragmentado.
• 'rollback_pending' — rollback também falhou transitoriamente; o pendente de rollback é salvo em retryStore para replay.
• 'rollback_failed' — pior caso: rollback falhou permanentemente. Estado terminal, nada é persistido (RetryStore = só transientes); a nova ficou emitida e a original não-cancelada — intervenção manual.

Lança direto apenas quando a emissão (step 1) falha — nesse caso nada foi alterado no SEFIN e o caller pode retentar limpo.

Parameters

Parameter	Type
params	SubstituirParams

Returns

Promise<SubstituirResult>