SDK TypeScript
SDK oficial TypeScript para Engine API. @engineapi/sdk no npm. Tipagem completa, todos os módulos fiscais.
SDK TypeScript
SDK oficial da Engine API com tipagem completa para Node.js e TypeScript.
bash
npm install @engineapi/sdk
Publicado no npm como @engineapi/sdk@1.0.0. Compatível com Node.js 18+ e TypeScript 5+.
Configuração
typescript
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âmetro | Tipo | Obrigatório | Descrição |
|-----------|------|-------------|-----------|
| baseUrl | string | Sim | URL base da API (sem /v1) |
| apiKey | string | Sim* | API Key para integração server-to-server |
| token | string | Sim* | JWT para sessões de dashboard |
| timeout | number | Não | Timeout 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:
typescript
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
typescript
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
typescript
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
typescript
await client.nfe.cancelar('35260211222333000144550010000000011000000019', {
motivo: 'Erro nos dados do destinatário',
});
Carta de Correção
typescript
await client.nfe.cartaCorrecao('35260211222333000144550010000000011000000019', {
correcao: 'Corrijo o endereço do destinatário para Av Brasil, 500',
});
Download PDF e XML
typescript
// 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
typescript
const status = await client.nfe.status();
console.log(status.data.status); // "online"
Boleto
Cadastrar conta bancária
typescript
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
typescript
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
typescript
// 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
typescript
// Buscar documentos fiscais emitidos contra o CNPJ
await client.dfe.consultar({
issuerId: 'ISSUER_UUID',
ultNSU: '000000000000000', // primeira consulta
});
Listar documentos
typescript
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
typescript
// 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
typescript
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
typescript
const certBuffer = fs.readFileSync('certificado.pfx');
await client.companies.uploadCertificado(empresa.data.id, {
certificado: certBuffer,
senha: 'senha-do-certificado',
});
Listar e consultar CNPJ
typescript
// 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
typescript
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):
typescript
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)
typescript
// 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
typescript
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' });
}
}
});