SDK NODEJS - APIGratis by API BRASIL 🚀

SDK oficial Node.js/TypeScript da plataforma APIBrasil — WhatsApp, SMS, consultas de CPF/CNPJ, veículos, CEP, correios, pagamentos PIX/boleto e muito mais.

Canais de suporte (Comunidade)

Instalação

npm install apigratis-sdk-nodejs --save

Requer Node.js >= 18 (usa fetch nativo). Zero dependências de runtime, com builds ESM + CJS e tipos TypeScript inclusos. Funciona também em Bun, Deno e Cloudflare Workers.

Obtenha suas credenciais em https://apibrasil.com.br

Começando

import { ApiBrasil } from 'apigratis-sdk-nodejs';

const api = new ApiBrasil({
	bearerToken: process.env.APIBRASIL_BEARER_TOKEN, // JWT do login
	deviceToken: process.env.APIBRASIL_DEVICE_TOKEN, // device dos serviços device-based
});

// WhatsApp
await api.whatsapp.sendText({ number: '5511999999999', text: 'Olá! 👋' });

// Consulta CNPJ (por créditos)
const empresa = await api.consulta.cnpj({ cnpj: '00000000000000' });
console.log(empresa.data);

As credenciais também podem vir só do ambiente — new ApiBrasil() lê automaticamente APIBRASIL_BEARER_TOKEN, APIBRASIL_DEVICE_TOKEN, APIBRASIL_SECRET_KEY e APIBRASIL_BASE_URL.

Também é possível autenticar por email/senha — o token retornado fica guardado no cliente:

const api = new ApiBrasil();
await api.auth.login({ email: 'voce@empresa.com.br', password: '******' });

// contas com 2FA:
const session = await api.auth.login({ email, password });
if (session.requires_2fa) {
	await api.auth.send2fa({ challenge: session.challenge!, method: 'email' });
	await api.auth.verify2fa({ challenge: session.challenge!, code: '000000' });
}

Como a plataforma funciona

A API Brasil tem duas famílias de serviços:

Família	Autenticação	Exemplos
Device-based	Authorization: Bearer + header DeviceToken	WhatsApp, SMS, veículos, CEP, correios, DDD, feriados, tradução, clima, OCR
Por créditos	apenas Authorization: Bearer (debita saldo)	consulta.cpf, consulta.cnpj, consulta.veiculos, Serasa, CNH, telefone

Para os serviços device-based, crie um device com a SecretKey da API desejada (painel APIBrasil) e use o device_token retornado:

const device = await api.devices.store(
	{ device_name: 'meu-bot', type: 'server' },
	{ secretKey: 'SUA_SECRET_KEY' }
);

api.setDeviceToken(device.device.device_token);

Serviços disponíveis

Módulo	Descrição
api.whatsapp	WhatsApp: start, qrcode, sendText, sendFile, sendAudio, sendVideo, fila (queue)...
api.evolution	Evolution API: request(controller, action, body)
api.whatsmeow	WhatsMeow: request(action, body)
api.sms	SMS device-based (send) e por créditos (sendWithCredits)
api.dados	Dados cadastrais device-based (cpf, cnpj)
api.vehicles	Veículos por placa (dados, fipe, consultaFipe)
api.fipe	Tabela FIPE (request(action, body))
api.correios	Correios (rastreio, request)
api.cep	CEP + geolocalização (cep, request)
api.geolocation / api.geomatrix	Geolocalização e matriz de distâncias
api.recognize	OCR / Google Vision
api.ddd / api.holidays / api.translate / api.weather	DDD, feriados, tradução, clima
api.databaseIp	GeoIP (ip)
api.consulta	Consultas por créditos: cpf, cnpj, cnh, cep, veiculos, telefone, generic(service, body)
api.ura / api.chipVirtual	URA reversa e chip virtual
api.bulk	Execução em lote (direct, queue)
api.auth	Login, 2FA, cadastro, recuperação de senha, perfil
api.devices	CRUD de devices
api.catalog	Catálogo de APIs, planos, documentações, servidores
api.account	Saldo, faturas, notificações, tickets
api.payments	Recargas e pagamentos PIX/boleto/cartão (Santander, Inter, Mercado Pago, Sicoob)
api.ipWhitelist / api.bearerRateLimit	Segurança da conta
api.reports	Relatórios e dashboard de consumo

WhatsApp

// iniciar sessão e obter QR Code
await api.whatsapp.start({
	webhook_wh_message: 'https://seu-webhook.com/mensagens',
});
const { response } = await api.whatsapp.qrcode();
console.log(response?.qrcode); // data URI base64

// envios
await api.whatsapp.sendText({ number: '5511999999999', text: 'Olá!' });
await api.whatsapp.sendFile({
	number: '5511999999999',
	path: 'https://exemplo.com/nota.pdf',
});
await api.whatsapp.sendAudio({
	number: '5511999999999',
	path: 'https://exemplo.com/audio.mp3',
});

// qualquer action da documentação, inclusive via fila
await api.whatsapp.request('sendLocation', {
	number: '5511999999999',
	lat: -23.5,
	lng: -46.6,
});
await api.whatsapp.queue('sendText', {
	number: '5511999999999',
	text: 'assíncrono 🚀',
});

Consultas por créditos

// CPF / CNPJ
const cpf = await api.consulta.cpf({ cpf: '00000000000' });
const socios = await api.consulta.cnpj({
	cnpj: '00000000000000',
	tipo: 'lista-socios',
});

// veicular
const veiculo = await api.consulta.veiculos({ placa: 'ABC1234' });

// qualquer produto do catálogo
const score = await api.consulta.generic('serasa-score', {
	cpf: '00000000000',
	tipo: 'serasa-score-pf',
});

// homologação (sandbox, sem cobrança)
const teste = await api.consulta.cpf({ cpf: '00000000000', homolog: true });

Veículos e FIPE (device-based)

const dados = await api.vehicles.dados({ placa: 'ABC1234' });
const fipe = await api.vehicles.fipe({ placa: 'ABC1234' });

SMS

await api.sms.send({ number: '5511999999999', message: 'Seu código: 123456' });
// ou debitando créditos da conta (sem device):
await api.sms.sendWithCredits({ number: '5511999999999', message: 'Olá!' });

Pagamentos e recargas

const pix = await api.payments.pixGenerate('inter', { amount: 100 });
const status = await api.payments.pixStatus('inter', pix.txId);

const boleto = await api.payments.boletoGenerate('sicoob', { amount: 150 });
const pdf = await api.payments.boletoPdf('sicoob', boleto.id); // ArrayBuffer

Múltiplos devices

const comercial = api.withDevice('DEVICE_TOKEN_COMERCIAL');
const suporte = api.withDevice('DEVICE_TOKEN_SUPORTE');

await comercial.whatsapp.sendText({ number: '55...', text: 'Proposta enviada!' });
await suporte.whatsapp.sendText({ number: '55...', text: 'Como posso ajudar?' });

Tratamento de erros

Cada categoria de falha tem a sua própria classe — todas estendem ApiBrasilError:

Classe	Quando
ValidationError	400/422 — payload inválido
AuthenticationError	401 — token ausente/expirado
InsufficientBalanceError	402 — sem saldo/créditos
PermissionError	403 — sem permissão (ex: exige PJ)
NotFoundError	404/410 — sem dados / rota desativada
RateLimitError	429 — limite atingido (retryAfterMs)
ServerError	5xx — erro do gateway/provedor
NetworkError / TimeoutError	falha antes da resposta

import { InsufficientBalanceError, RateLimitError } from 'apigratis-sdk-nodejs';

try {
	await api.consulta.cpf({ cpf: '00000000000' });
} catch (error) {
	if (error instanceof InsufficientBalanceError)
		console.log('Recarregue seus créditos');
	if (error instanceof RateLimitError)
		console.log(`Aguarde ${error.retryAfterMs}ms`);
}

Retry e observabilidade

Por padrão a SDK refaz a chamada em HTTP 429 e em falhas de conexão (2 tentativas extras, backoff exponencial, respeitando Retry-After). Timeouts e erros de negócio nunca são refeitos — evita duplicar cobranças e envios.

const api = new ApiBrasil({
	retry: { retries: 3, minDelayMs: 500, retryOnStatuses: [429, 503] }, // ou retry: false
	hooks: {
		onRequest: ({ method, url, attempt }) =>
			console.log(`→ ${method} ${url} (#${attempt})`),
		onResponse: ({ status, durationMs }) =>
			console.log(`← ${status} em ${durationMs}ms`),
		onRetry: ({ delayMs, reason }) =>
			console.warn(`retry em ${delayMs}ms: ${reason}`),
	},
});

Transporte plugável

O HTTP é feito pelo fetch nativo, mas a interface Transport permite trocar a camada inteira (proxy corporativo, axios, mocks de teste):

import { ApiBrasil, Transport } from 'apigratis-sdk-nodejs';

const meuTransporte: Transport = {
	async request({ method, url, headers, body }) {
		// use o cliente HTTP que quiser e retorne { status, headers, data }
		const resp = await fetch(url, { method, headers, body, dispatcher: meuProxy });
		return { status: resp.status, headers: {}, data: await resp.json() };
	},
};

const api = new ApiBrasil({ transport: meuTransporte });

Imports por domínio (tree-shaking)

Além do pacote raiz, cada domínio tem o seu subpath — útil para bundles menores:

import { WhatsAppService } from 'apigratis-sdk-nodejs/messaging';
import { ConsultaService, CONSULTA_TIPOS } from 'apigratis-sdk-nodejs/data';
import { PaymentsService } from 'apigratis-sdk-nodejs/platform';
import { HttpClient, FetchTransport } from 'apigratis-sdk-nodejs/core';
import { createCpfApi } from 'apigratis-sdk-nodejs/legacy';

Tipos gerados do catálogo

As actions de WhatsApp/Evolution/WhatsMeow e os 210+ tipo de consulta têm autocomplete gerado do catálogo real da plataforma (npm run codegen atualiza). O mapa CONSULTA_TIPOS traz o serviço e os campos de exemplo de cada tipo:

import { CONSULTA_TIPOS } from 'apigratis-sdk-nodejs';

console.log(CONSULTA_TIPOS['lista-socios']);
// { service: 'cnpj', fields: ['cnpj'] }

Endpoint sem método dedicado?

Todo o gateway fica acessível pela porta de saída genérica, já com seus headers de autenticação:

await api.request('POST', '/consulta/cpf/credits', { cpf: '00000000000' });
await api.request('GET', '/reports/quick-stats');

Documentação completa dos endpoints: https://doc.apibrasil.io

Configuração avançada

const api = new ApiBrasil({
	bearerToken: '...', // ou APIBRASIL_BEARER_TOKEN
	deviceToken: '...', // ou APIBRASIL_DEVICE_TOKEN
	secretKey: '...', // usada em devices.store (ou APIBRASIL_SECRET_KEY)
	baseURL: 'https://gateway.apibrasil.io/api/v2', // padrão (ou APIBRASIL_BASE_URL)
	timeout: 30000,
	headers: { 'X-Custom': 'valor' }, // headers extras
	retry: { retries: 2 }, // ou false
	hooks: { onRetry: console.warn },
	transport: undefined, // Transport customizado (padrão: fetch nativo)
});

Interface legada (v0.1.x)

As funções createWhatsAppApi, createCpfApi, createCnpjApi, createVehiclesApi, createCorreiosApi e createCepApi continuam funcionando exatamente como antes, mas estão deprecadas — prefira o cliente ApiBrasil.

import { createCpfApi } from 'apigratis-sdk-nodejs';

const cpfApi = createCpfApi({
	BearerToken: 'bearer_token',
	DeviceToken: 'device_token',
});
cpfApi.request('/', { cpf: '__CPF__' }).then(resp => console.log(resp));