Skip to main content

​
SDK TypeScript

SDK oficial da Engine API com tipagem completa para Node.js e TypeScript. 
npm install @engineapi/sdk
Publicado no npm como @engineapi/sdk@1.0.0. Compatível com Node.js 18+ e TypeScript 5+.

​
Configuração

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

const client = new EngineApiClient({
  baseUrl: 'https://api.engineapi.com.br',
  apiKey: 'ek_live_SEU_API_KEY',
  timeout: 30000, // opcional, padrão 30s
});

​
Parâmetros de configuração

ParâmetroTipoObrigatórioDescrição
baseUrlstringSimURL base da API (sem /v1)
apiKeystringSim*API Key para integração server-to-server
tokenstringSim*JWT para sessões de dashboard
timeoutnumberNãoTimeout em ms (padrão: 30000)
*Use apiKey para integrações ou token para sessões autenticadas via login.

​
Módulos Disponíveis

O client expõe 4 módulos tipados: 
client.nfe        // NFe — emissão, cancelamento, CC-e, download
client.boleto     // Boleto — emissão, consulta, cancelamento, PDF
client.dfe        // DFe — distribuição, manifestação, download XML
client.companies  // Empresas — CRUD, certificados

​
NFe — Nota Fiscal Eletrônica

​
Emitir NFe

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

const client = new EngineApiClient({
  baseUrl: 'https://api.engineapi.com.br',
  apiKey: 'ek_live_SEU_API_KEY',
});

const nfe = await client.nfe.emitir({
  emitente: { issuerId: 'ISSUER_UUID' },
  destinatario: {
    cnpjCpf: '99888777000155',
    razaoSocial: 'Cliente Exemplo SA',
    endereco: {
      logradouro: 'Av Brasil', numero: '500',
      bairro: 'Centro', cidade: 'São Paulo',
      uf: 'SP', cep: '01001000',
      codigoMunicipio: '3550308',
    },
  },
  itens: [{
    descricao: 'Produto Teste',
    ncm: '61091000',
    cfop: '5102',
    unidade: 'UN',
    quantidade: 1,
    valorUnitario: 100.00,
  }],
  pagamento: { forma: '01', valor: 100.00 },
});

console.log('Chave:', nfe.data.accessKey);
console.log('Status:', nfe.data.status);  // "AUTHORIZED"

​
Listar NFes

const lista = await client.nfe.listar({
  page: 1,
  limit: 20,
  issuerId: 'ISSUER_UUID',
  status: 'AUTHORIZED',
});

console.log(`Total: ${lista.total}`);
lista.data.forEach(nfe => {
  console.log(`${nfe.accessKey} — R$ ${nfe.valorTotal}`);
});

​
Cancelar NFe

await client.nfe.cancelar('35260211222333000144550010000000011000000019', {
  motivo: 'Erro nos dados do destinatário',
});

​
Carta de Correção

await client.nfe.cartaCorrecao('35260211222333000144550010000000011000000019', {
  correcao: 'Corrijo o endereço do destinatário para Av Brasil, 500',
});

​
Download PDF e XML

// PDF (DANFE)
const pdf = await client.nfe.downloadPdf('35260211...');
fs.writeFileSync('danfe.pdf', pdf);

// XML
const xml = await client.nfe.downloadXml('35260211...');
fs.writeFileSync('nfe.xml', xml);

// XML da CC-e
const cceXml = await client.nfe.downloadCceXml('35260211...');

// PDF da CC-e
const ccePdf = await client.nfe.downloadCcePdf('35260211...');

​
Status do serviço SEFAZ

const status = await client.nfe.status();
console.log(status.data.status); // "online"

​
Boleto

​
Cadastrar conta bancária

await client.boleto.criarContaBancaria('ISSUER_UUID', {
  banco: '756',
  bancoNome: 'Sicoob',
  agencia: '3303',
  conta: '123456',
  convenio: '3303001',
  carteira: '1',
  cedente: 'Empresa Exemplo Ltda',
  cnpjCedente: '11222333000144',
});

​
Emitir boleto

const boleto = await client.boleto.emitir({
  issuerId: 'ISSUER_UUID',
  bankAccountId: 'BANK_ACCOUNT_UUID',
  pagador: {
    nome: 'João da Silva',
    cpf: '12345678901',
    endereco: {
      logradouro: 'Rua Exemplo', numero: '100',
      bairro: 'Centro', cidade: 'São Paulo',
      uf: 'SP', cep: '01001000',
    },
  },
  valor: 250.00,
  vencimento: '2026-05-10',
  descricao: 'Fatura #1234',
});

console.log('Nosso Número:', boleto.data.nossoNumero);
console.log('Linha Digitável:', boleto.data.linhaDigitavel);

​
Listar, consultar e cancelar

// Listar
const boletos = await client.boleto.listar({ page: 1, limit: 20 });

// Consultar por ID
const detalhe = await client.boleto.consultar('BOLETO_ID');

// Cancelar
await client.boleto.cancelar('BOLETO_ID');

// Download PDF
const pdf = await client.boleto.downloadPdf('BOLETO_ID');
fs.writeFileSync('boleto.pdf', pdf);

​
DFe — Distribuição de Documentos

​
Consultar documentos recebidos

// Buscar documentos fiscais emitidos contra o CNPJ
await client.dfe.consultar({
  issuerId: 'ISSUER_UUID',
  ultNSU: '000000000000000', // primeira consulta
});

​
Listar documentos

const docs = await client.dfe.listar({
  issuerId: 'ISSUER_UUID',
  tipoDoc: 'NFe',
  page: 1,
  limit: 50,
});

docs.data.forEach(doc => {
  console.log(`${doc.chave} — ${doc.nomeEmitente} — R$ ${doc.valor}`);
});

​
Manifestar e download

// Manifestar confirmação
await client.dfe.manifestar('DFE_ID', {
  evento: '210200',
  descricao: 'Confirmação da operação',
});

// Download XML
const xml = await client.dfe.downloadXml('DFE_ID');

​
Companies — Empresas Emissoras

​
Criar empresa

const empresa = await client.companies.criar({
  cnpj: '11222333000144',
  razaoSocial: 'Empresa Exemplo Ltda',
  nomeFantasia: 'Exemplo',
  regime: 'SIMPLES',
  endereco: {
    logradouro: 'Rua Principal', numero: '100',
    bairro: 'Centro', cidade: 'São Paulo',
    uf: 'SP', cep: '01001000',
    codigoMunicipio: '3550308',
  },
});

console.log('Issuer ID:', empresa.data.id);

​
Upload de certificado

const certBuffer = fs.readFileSync('certificado.pfx');

await client.companies.uploadCertificado(empresa.data.id, {
  certificado: certBuffer,
  senha: 'senha-do-certificado',
});

​
Listar e consultar CNPJ

// Listar emissores do partner
const empresas = await client.companies.listar();

// Consultar dados públicos de um CNPJ
const dados = await client.companies.consultarCnpj('11222333000144');

​
Tratamento de Erros

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

try {
  await client.nfe.emitir(params);
} catch (error) {
  if (error instanceof EngineApiError) {
    console.error('Status:', error.statusCode);
    console.error('Mensagem:', error.message);
    console.error('Response:', error.response);

    // Helpers tipados
    if (error.isValidationError) {
      // 400 — dados inválidos
      console.error('Campos:', error.response?.errors);
    }
    if (error.isUnauthorized) {
      // 401 — API key inválida ou expirada
    }
    if (error.isRateLimited) {
      // 429 — retry após Retry-After
    }
    if (error.isNotFound) {
      // 404 — recurso não encontrado
    }
    if (error.isServerError) {
      // 500+ — retry com backoff
    }
  }
}

​
Login via JWT (Dashboard)

Para sessões de dashboard (não recomendado para server-to-server): 
const client = new EngineApiClient({
  baseUrl: 'https://api.engineapi.com.br',
});

// Login retorna JWT e seta automaticamente no client
const login = await client.login({
  email: 'usuario@partner.com',
  password: 'senha',
});

console.log('Token:', login.access_token);
console.log('Partner:', login.partner.name);

// Agora o client usa o JWT automaticamente
const nfes = await client.nfe.listar();

​
Integração com Frameworks

​
Next.js (App Router)

// app/api/emitir-nfe/route.ts
import { EngineApiClient } from '@engineapi/sdk';
import { NextResponse } from 'next/server';

const engine = new EngineApiClient({
  baseUrl: process.env.ENGINE_API_URL!,
  apiKey: process.env.ENGINE_API_KEY!,
});

export async function POST(request: Request) {
  const body = await request.json();

  const nfe = await engine.nfe.emitir({
    emitente: { issuerId: body.issuerId },
    destinatario: body.destinatario,
    itens: body.itens,
    pagamento: body.pagamento,
  });

  return NextResponse.json(nfe);
}

​
Express

import express from 'express';
import { EngineApiClient, EngineApiError } from '@engineapi/sdk';

const app = express();
const engine = new EngineApiClient({
  baseUrl: process.env.ENGINE_API_URL!,
  apiKey: process.env.ENGINE_API_KEY!,
});

app.post('/nfe', async (req, res) => {
  try {
    const nfe = await engine.nfe.emitir(req.body);
    res.json(nfe);
  } catch (error) {
    if (error instanceof EngineApiError) {
      res.status(error.statusCode).json({ error: error.message });
    } else {
      res.status(500).json({ error: 'Internal server error' });
    }
  }
});

​
Próximos passos

AI Integration

Como usar IA para integrar automaticamente

Webhooks

Receber eventos em tempo real