@engineapi/sdk

SDK TypeScript para integração com a EngineAPI — Emissão fiscal (NFe, NFCe, NFSe) e Consultas DFe.

Instalação

npm install @engineapi/sdk

Quick Start

import { EngineApiClient } from "@engineapi/sdk";

// Autenticação via API Key (recomendado para server-to-server)
const engine = new EngineApiClient({
  baseUrl: "https://api.seudominio.com.br",
  apiKey: "ek_live_sua-api-key-aqui",
});

// Ou via JWT (para painéis web)
const engineJwt = new EngineApiClient({
  baseUrl: "https://api.seudominio.com.br",
});
await engineJwt.login({ email: "[email protected]", password: "..." });

Módulos

NFe — Nota Fiscal Eletrônica

// Emitir NFe
const nfe = await engine.nfe.emitir({
  issuerId: "uuid-da-empresa", // raiz do payload — não aninhado em `emitente`
  destinatario: {
    cnpjCpf: "12345678000100",
    nome: "Cliente LTDA",
    endereco: {
      logradouro: "Rua Exemplo",
      numero: "100",
      bairro: "Centro",
      municipio: "São Paulo",
      uf: "SP",
      cep: "01000000",
      codigoMunicipio: "3550308",
    },
  },
  items: [
    {
      codigo: "PROD-1",
      descricao: "Produto Teste",
      ncm: "84713012",
      cfop: "5102",
      unidade: "UN",
      quantidade: 1,
      valorUnitario: 100.0,
    },
  ],
  pagamentos: [{ forma: "01", valor: 100.0 }], // obrigatório, mínimo 1
});

console.log(nfe.data?.accessKey); // Chave de acesso

// Download DANFE (PDF)
const pdf = await engine.nfe.downloadPdf("chave-de-acesso");
fs.writeFileSync("danfe.pdf", pdf);

// Cancelar
await engine.nfe.cancelar("chave-de-acesso", {
  justificativa: "Erro nos dados do destinatário",
});

// Listar
const notas = await engine.nfe.listar({
  page: 1,
  limit: 20,
  status: "AUTORIZADA",
});

DFe — Distribuição (Notas Recebidas)

engine.dfe.* requer JWT (token, obtido via engine.login()), NÃO API Key — DfeController no backend só aceita sessão do dashboard.

await engine.login({ email: "[email protected]", password: "..." });

// Consultar notas recebidas na SEFAZ
await engine.dfe.consultar({ issuerId: "uuid", ultimoNsu: "000000000123456" });

// Listar docs recebidos (issuerId é obrigatório)
const docs = await engine.dfe.listar({ issuerId: "uuid", page: 1 });

// Manifestar ciência (campo é `tipo`, não `operacao`)
await engine.dfe.manifestar("doc-id", {
  tipo: "CIENCIA",
  justificativa: "Confirmando ciência da operação descrita no documento.",
});

Empresas

engine.companies.* requer JWT (token, obtido via engine.login()), NÃO API Key — CompaniesController no backend só aceita sessão do dashboard (cadastro/certificado são fluxo humano, não server-to-server).

await engine.login({ email: "[email protected]", password: "..." });

// Cadastrar empresa
const empresa = await engine.companies.criar({
  cnpj: "12345678000100",
  name: "Minha Empresa LTDA",
  crt: 1, // 1=Simples Nacional, 3=Regime Normal
  address: "Rua Exemplo",
  number: "100",
  neighborhood: "Centro",
  city: "São Paulo",
  state: "SP",
  cep: "01000000",
  ibgeCode: "3550308",
});

// Upload certificado digital (multipart — Buffer do .pfx)
await engine.companies.uploadCertificado(
  empresa.data!.id,
  fs.readFileSync("certificado.pfx"),
  "senha123",
);

Tratamento de Erros

import { EngineApiError } from '@engineapi/sdk';

try {
  await engine.nfe.emitir({ ... });
} catch (error) {
  if (error instanceof EngineApiError) {
    if (error.isRateLimited) console.log('Muitas requisições, aguarde...');
    if (error.isUnauthorized) console.log('API Key inválida');
    if (error.isValidationError) console.log('Dados inválidos:', error.response);
    console.log(`Erro ${error.statusCode}: ${error.message}`);
  }
}

Health Check

const health = await engine.health();
console.log(health); // { status: 'ok', ... }

API Reference

| Módulo | Métodos | | ------------------ | ----------------------------------------------------------------------------------------------------------------- | | engine.nfe | emitir() listar() consultar() cancelar() cartaCorrecao() downloadPdf() downloadXml() status() | | engine.dfe | consultar() listar() buscar() manifestar() downloadXml() | | engine.companies | criar() listar() buscar() consultarCnpj() uploadCertificado() | | engine | login() regenerateApiKey() apiKeyInfo() health() |

Licença

MIT