open-nfse / NfseClient

Class: NfseClient

Defined in: src/client.ts:153

Constructors

Constructor

new NfseClient(config: NfseClientConfig): NfseClient;

Defined in: src/client.ts:167

Parameters

Parameter	Type
config	NfseClientConfig

Returns

NfseClient

Methods

cancelar()

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

Defined in: src/client.ts:338

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:597

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:429

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:463

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:481

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

Parameters

Parameter	Type
codigoMunicipio	string
options?	ConsultaOptions

Returns

Promise<ConsultaConvenioResult>

---

consultarHistoricoAliquotas()

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

Defined in: src/client.ts:447

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:490

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:508

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:233

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/5xx); 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.

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:234

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/5xx); 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.

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:260

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:264

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?: EmitManyOptions): Promise<EmitLoteResult>;

Defined in: src/client.ts:292

Emissão em lote: paraleliza emitir() para uma lista de DPS (SEFIN não oferece endpoint de batch — a paralelização acontece no cliente). Cada item vira um EmitLoteItem com status: 'success' | 'failure' | 'skipped' para que o chamador decida como reagir a falhas parciais.

Parameters

Parameter	Type
dpsList	readonly DPS[]
options?	EmitManyOptions

Returns

Promise<EmitLoteResult>

---

existsDpsStatus()

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

Defined in: src/client.ts:204

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:179

Parameters

Parameter	Type
chaveAcesso	string

Returns

Promise<NfseQueryResult>

---

fetchByNsu()

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

Defined in: src/client.ts:209

Parameters

Parameter	Type
params	FetchByNsuParams

Returns

Promise<NsuQueryResult>

---

fetchDanfse()

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

Defined in: src/client.ts:586

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>>

---

fetchDpsStatus()

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

Defined in: src/client.ts:194

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:545

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:383

Re-POSTs each PendingEvent in the store. SEFIN deduplication on (chave + tipoEvento + nPedRegEvento) 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. Em falha permanente, também é removido e o erro é retornado no item.

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:364

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' — pior caso, rollback também falhou; o pendente de rollback é salvo em retryStore para replay.

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>