@engineapi/sdk

SDK TypeScript para integração com a EngineAPI — Emissão fiscal (NFe, NFCe, MDFe, NFSe), Boletos 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({
  emitente: { issuerId: "uuid-da-empresa" },
  destinatario: {
    cnpjCpf: "12345678000100",
    razaoSocial: "Cliente LTDA",
    endereco: {
      logradouro: "Rua Exemplo",
      numero: "100",
      bairro: "Centro",
      cidade: "São Paulo",
      uf: "SP",
      cep: "01000000",
      codigoMunicipio: "3550308",
    },
  },
  itens: [
    {
      descricao: "Produto Teste",
      ncm: "84713012",
      cfop: "5102",
      unidade: "UN",
      quantidade: 1,
      valorUnitario: 100.0,
      valorTotal: 100.0,
    },
  ],
});

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",
});

Boleto — Emissão e Consulta

// Cadastrar conta bancária
await engine.boleto.criarContaBancaria("issuer-id", {
  banco: "756",
  agencia: "3001",
  conta: "12345",
  carteira: "1",
  convenio: "123456",
});

// Emitir boleto
const boleto = await engine.boleto.emitir({
  bankAccountId: "account-id",
  pagadorNome: "João Silva",
  pagadorCpfCnpj: "12345678901",
  valor: 150.0,
  vencimento: "2026-03-15",
  descricao: "Mensalidade Março",
});

console.log(boleto.data?.linhaDigitavel);
console.log(boleto.data?.pixQrCode);

// Download PDF do boleto
const boletoPdf = await engine.boleto.downloadPdf("boleto-id");

DFe — Distribuição (Notas Recebidas)

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

// Listar docs recebidos
const docs = await engine.dfe.listar({ page: 1 });

// Manifestar ciência
await engine.dfe.manifestar("doc-id", { operacao: "CIENCIA" });

Empresas

// Cadastrar empresa
const empresa = await engine.companies.criar({
  cnpj: '12345678000100',
  razaoSocial: 'Minha Empresa LTDA',
  regime: 'SIMPLES',
  endereco: { ... },
});

// Upload certificado digital
await engine.companies.uploadCertificado('empresa-id', base64Cert, '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.boleto | emitir() listar() consultar() cancelar() downloadPdf() criarContaBancaria() listarContasBancarias() | | engine.dfe | consultar() listar() buscar() manifestar() downloadXml() | | engine.companies | criar() listar() buscar() consultarCnpj() uploadCertificado() | | engine | login() regenerateApiKey() apiKeyInfo() health() |

Licença

MIT