apigratis_sdk_flutter library

APIBrasil SDK for Dart/Flutter

Official SDK for APIBrasil platform — WhatsApp, SMS, CPF/CNPJ queries, vehicle data, CEP, Correios, PIX/boleto payments and more.

Quick Start

import 'package:apigratis_sdk_flutter/apigratis_sdk_flutter.dart';

void main() async {
  // Initialize with credentials
  final api = ApiBrasil(
    bearerToken: 'seu_bearer_token',
    deviceToken: 'seu_device_token',
  );

  // WhatsApp - send text message
  final result = await api.whatsapp.sendText({
    'number': '5511999999999',
    'text': 'Olá!'
  });

  // Consulta CPF
  final cpf = await api.consulta.cpfDados({'cpf': '00000000000'});

  // Get WhatsApp QR code
  final qr = await api.whatsapp.qrcode();
}

Services Overview

Messaging

Data & Consultas

Platform

Migração da 0.0.x

As classes legadas foram renomeadas com o prefixo Legacy para liberar os nomes aos serviços novos: WhatsAppService → LegacyWhatsAppService, CpfService → LegacyCpfService, SmsService → LegacySmsService. Todas estão @Deprecated — prefira ApiBrasil().

Configuration

Credentials can be passed directly or via environment variables:

  • APIBRASIL_BEARER_TOKEN
  • APIBRASIL_DEVICE_TOKEN
  • APIBRASIL_SECRET_KEY
  • APIBRASIL_BASE_URL

Or via --dart-define at compile time.

Classes

AccountService
Saldo, faturas, notificações, tickets (/account/{action} e /balance, /invoices, etc).
ApiBrasil
Cliente oficial da plataforma APIBrasil para Dart/Flutter.
ApiBrasilConfig
Configuração do cliente ApiBrasil.
ApiBrasilHooks
Hooks de observabilidade — logging, métricas, tracing.
ApiHttpClient
Cliente HTTP interno da SDK. Injeta os headers de autenticação da plataforma (Authorization: Bearer, DeviceToken, SecretKey), aplica retry com backoff, dispara hooks de observabilidade e converte falhas em subclasses de ApiBrasilError.
ApiRequest
Full API request envelope with credentials and body.
ApiService
Serviço legado, mantido apenas para migração da 0.0.x.
AuthService
Login, 2FA, cadastro, senha e perfil (/auth/{action}). Requer apenas Authorization: Bearer (após login).
BaseService
Base class for all API services.
BearerRateLimitService
Rate limit por Bearer Token (/bearer-rate-limit/{action}).
Body
Request body for WhatsApp/SMS messages.
BulkService
Execução em lote (/bulk/*).
Catalog
Catálogo de endpoints conhecidos da API Brasil.
CatalogService
Catálogo de APIs, planos, docs e servidores (/apis, /plan, /servers, /catalog).
CepService
CEP + geolocalização device-based (/cep/{action}). Requires DeviceToken.
ChipVirtualService
Chip Virtual (/chip/virtual/{action}).
ConsultaService
Consultas por crédito (/consulta/{service}/credits). Requires Authorization: Bearer (no DeviceToken).
CorreiosService
Correios (/correios/{action}).
Credentials
Credentials for device-based authentication.
CreditService
Service for credit-based consultations (/consulta/{service}/credits). These endpoints debit credits from the account and don't require DeviceToken.
DadosService
Dados cadastrais device-based (/dados/{action}): CPF, CNPJ, lista sócios, CNAEs, etc.
DatabaseIpService
GeoIP (/database/ip).
DddService
DDD (/ddd/{action}). Device-based (requires DeviceToken).
DeviceProxyService
Base service for device-based APIs (WhatsApp, SMS, Evolution, WhatsMeow, CEP, etc.). These endpoints require DeviceToken header and use the pattern POST /{service}/{action}.
DevicesService
Gestão de devices (/devices/{action}).
EnvVars
Variáveis de ambiente reconhecidas pela SDK.
EvolutionService
Evolution API (POST /evolution/{controller}/{action}). Uses DeviceToken for authentication.
FipeService
Tabela FIPE (/fipe/{action}).
GeolocationService
Geolocalização (/geolocation/{action}). Device-based (requires DeviceToken).
GeomatrixService
Matriz de distâncias (/geomatrix/{action}). Device-based (requires DeviceToken).
HolidaysService
Feriados (/holidays/{action}). Device-based (requires DeviceToken).
HttpTransport
Transporte padrão, baseado em package:http — funciona em Flutter (Android, iOS, web, desktop) e em Dart puro.
IpWhitelistService
IP Whitelist da conta (/ip-whitelist/{action}).
LegacyCpfService
CPF legado da 0.0.x. Use ApiBrasil.consulta.cpf / ApiBrasil.dados.cpf.
LegacySmsService
SMS legado da 0.0.x. Use ApiBrasil.sms (tipo SmsService).
LegacyWhatsAppService
WhatsApp legado da 0.0.x. Use ApiBrasil.whatsapp (tipo WhatsAppService).
LoteriasService
Loterias (/loterias/{action}). Device-based (requires DeviceToken).
PaymentsService
Recargas e pagamentos (PIX, boleto, cartão) (/recharge, /payments, /invoices/{id}/pay).
RecognizeService
OCR / Google Vision (/recognize/{action}). Device-based (requires DeviceToken).
ReportsService
Relatórios e dashboard de consumo (/reports/{action}).
RequestHookInfo
Dados da requisição entregues ao hook ApiBrasilHooks.onRequest.
RequestOptions
Opções por requisição — sobrescrevem a configuração do cliente.
ResponseHookInfo
Dados da resposta entregues ao hook ApiBrasilHooks.onResponse.
RetryConfig
Política de retry do cliente. Por padrão a SDK tenta novamente apenas em HTTP 429 (rate limit) e em falhas de conexão — nunca em timeouts ou erros de negócio, para não duplicar cobranças/envios.
RetryHookInfo
Dados do retry entregues ao hook ApiBrasilHooks.onRetry.
SmsService
SMS device-based API (POST /sms/{action} and /sms/send/credits). Requires Authorization: Bearer + DeviceToken.
TranslateService
Tradução (/translate/{action}). Device-based (requires DeviceToken).
Transport
Camada de transporte HTTP da SDK. A implementação padrão usa package:http (HttpTransport); injete a sua para usar Dio, proxies, mocks de teste etc.
TransportRequest
Requisição entregue à camada de Transport.
TransportResponse
Resposta devolvida pela camada de Transport.
UraService
URA reversa / ligações (/ura/call/*).
VehiclesService
Veículos por placa (/vehicles/{action} e /vehicles/fipe).
WeatherService
Clima (/weather/{action}). Device-based (requires DeviceToken).
WhatsAppService
WhatsApp device-based API (POST /whatsapp/{action}). Requires Authorization: Bearer + DeviceToken.
WhatsMeowService
WhatsMeow API (POST /whatsmeow/{action}). Uses DeviceToken for authentication.

Enums

HttpMethod
Métodos HTTP usados pelo gateway.
ResponseType
Como o corpo da resposta deve ser decodificado.

Extension Types

CreditServiceResponse
Envelope de resposta das consultas por crédito ({ error, message, balance, tax, valor_consulta, data... }).
DeviceServiceResponse
Envelope de resposta dos serviços device-based ({ error, message, response, api_limit... }).

Constants

defaultBaseUrl → const String
Base padrão da API.
defaultRetry → const RetryConfig
Política de retry padrão: 2 novas tentativas, backoff de 300ms a 5s, apenas em HTTP 429 e falhas de conexão.
defaultTimeout → const Duration
Timeout padrão das requisições.
sdkUserAgent → const String
User-Agent enviado pela SDK.

Functions

asJsonMap(dynamic data) → Json
Normaliza o corpo decodificado em um objeto JSON.
backoffDelay(int attempt, RetryConfig retry, {Random? random}) → Duration
Backoff exponencial com jitter: minDelay * 2^attempt, limitado a maxDelay.
buildQueryString(Map<String, Object?>? query) → String
Monta a query string a partir de um mapa, ignorando valores nulos.
configFromEnv() → ApiBrasilConfig
Lê a configuração das variáveis de ambiente (quando disponíveis) e dos --dart-define de mesmo nome. Valores passados explicitamente no construtor sempre têm prioridade.
consultaPayload({String? tipo, bool? homolog, bool? lite, List<String>? agrupados, List<String>? extra, Json? fields}) → Json
Campos comuns aceitos pelas consultas por crédito (/consulta/{service}/credits).
createApiError(int status, dynamic data, {Map<String, String>? headers, Object? cause}) → ApiBrasilError
Mapeia um status HTTP + corpo de erro para a subclasse adequada.
decodeBody(List<int> bytes, ResponseType responseType) → dynamic
Decodifica o corpo conforme o ResponseType pedido.
joinUrl(String baseUrl, String path) → String
Junta a base da API com o caminho, sem barras duplicadas.
parseRetryAfter(Map<String, String>? headers, {DateTime? now}) → Duration?
Lê o header Retry-After (segundos ou data HTTP).
resolveRetry(RetryConfig? config) → RetryConfig
Resolve a política efetiva — null usa defaultRetry.
sleep(Duration delay) → Future<void>
Aguarda delay — ponto de extensão para testes.

Typedefs

Json = Map<String, dynamic>
Objeto JSON decodificado — o formato de resposta da maioria das rotas.

Exceptions / Errors

ApiBrasilError
Erro base lançado pelo cliente ApiBrasil. Subclasses específicas permitem tratar cada categoria com is:
AuthenticationError
HTTP 401 — Bearer Token ausente, inválido ou expirado.
InsufficientBalanceError
HTTP 402 — saldo/créditos insuficientes.
NetworkError
Falha de rede — a requisição pode não ter chegado ao servidor.
NotFoundError
HTTP 404/410 — recurso não encontrado ou desativado.
PermissionError
HTTP 403 — sem permissão (ex: API exige conta PJ).
RateLimitError
HTTP 429 — rate limit atingido.
ServerError
HTTP 5xx — erro interno do gateway/provedor.
TimeoutError
Timeout — a requisição pode ter sido processada; a SDK não faz retry automático para não duplicar cobranças/envios.
ValidationError
HTTP 400/422 — payload inválido.