SDK Node

O SDK oficial de Node/TypeScript (npm install @stackin-io/stackin-node-sdk) encapsula a API REST em uma única classe Invoice. Não há mais nada para instanciar: issue(), consult(), cancel() e reissue() são toda a superfície, e cada um devolve a resposta da própria API, não um modelo paralelo dela.

Ele traz as próprias declarações de tipo, então DocumentType.NFE é um membro de enum de verdade e um tipo de documento escrito errado vira erro de compilação, não um 422 da API. O mesmo vale para br.Product e Address — os campos que a NF-e exige estão no tipo, então um ncm faltando ou um endereço de destinatário incompleto é pego pelo tsc ou pela validação local antes de qualquer requisição sair.

A autenticação é uma chave de API, igual à API crua, então alternar entre o SDK e chamadas HTTP diretas não exige credencial separada. A chave resolve a empresa emitente por inteiro — CNPJ, UF, certificado e ambiente fiscal — e nada sobre o emitente é passado na chamada.

Os erros chegam como três classes distintas, em vez de uma falha genérica: ValidationError para o que o SDK recusou localmente, APIError carregando o status e o detail da própria API, e ConnectionFailedError quando a requisição não obteve resposta. As três estendem InvoiceError, então um único catch continua funcionando quando você não precisa distingui-las.

O reissue() merece destaque porque o argumento dele não é uma chave de acesso. Uma submissão que falhou nunca recebeu uma, então ele recebe o id local da nota — e consome cota exatamente como uma emissão nova, razão pela qual o SDK deliberadamente não tem laço de retry automático em volta dele.

Requer Node 18 ou superior, já que usa o fetch da plataforma em vez de embutir um cliente HTTP. Toda requisição respeita um timeout configurável, e a própria implementação de fetch é injetável, que é o mecanismo usado pela suíte de testes para rodar sem rede.

Veja a seção de SDKs da referência da API para comandos de instalação e exemplos lado a lado, ou o código no GitHub.