Changelog

0.0.1 — 2026-07-28

Primeira versão da SDK Elixir, cobrindo toda a plataforma APIBrasil — mesma arquitetura e paridade de rotas com as SDKs de Go, Node.js, PHP, Ruby, Rust e Dart/Flutter.

Novidades

• Cliente central ApiBrasil (new/1, from_env/0, login/2) devolvendo um ApiBrasil.Client imutável, com um módulo por produto: ApiBrasil.Messaging.WhatsApp, ApiBrasil.Messaging.Evolution, ApiBrasil.Messaging.WhatsMeow, ApiBrasil.Messaging.SMS, ApiBrasil.Data.Dados, ApiBrasil.Data.Vehicles, ApiBrasil.Data.Fipe, ApiBrasil.Data.Correios, ApiBrasil.Data.Cep, ApiBrasil.Data.Geolocation, ApiBrasil.Data.Geomatrix, ApiBrasil.Data.Recognize, ApiBrasil.Data.Ddd, ApiBrasil.Data.Holidays, ApiBrasil.Data.Translate, ApiBrasil.Data.Weather, ApiBrasil.Data.Loterias, ApiBrasil.Data.DatabaseIp, ApiBrasil.Data.Consulta (créditos), ApiBrasil.Data.Ura, ApiBrasil.Data.ChipVirtual, ApiBrasil.Data.Bulk, ApiBrasil.Platform.Auth (login/2FA), ApiBrasil.Platform.Devices, ApiBrasil.Platform.Catalog, ApiBrasil.Platform.Account, ApiBrasil.Platform.Payments (PIX/boleto/cartão), ApiBrasil.Platform.IpWhitelist, ApiBrasil.Platform.BearerRateLimit e ApiBrasil.Platform.Reports.
• Contrato uniforme: toda função devolve {:ok, resultado} ou {:error, %ApiBrasil.Core.Error{}} e tem a variante !, que devolve o resultado direto e levanta em caso de falha. Todas aceitam uma keyword list final com as opções da requisição.
• DSL de serviços (use ApiBrasil.Core.Service): as rotas device-based, as consultas por crédito e as rotas da plataforma são declaradas em uma tabela (action/3, credit/3, route_get/3, route_post/3, route_put/3, route_delete/3, route_empty/4), que gera as duas variantes de cada função com @doc e @spec.
• Zero dependências obrigatórias: o transporte padrão é o :httpc do Erlang/OTP (ApiBrasil.Core.Transport.Httpc, com verify_peer e checagem de hostname) e o JSON usa o JSON nativo (Elixir 1.18+) ou o :json (OTP 27+). Jason, Finch e CAStore são usados automaticamente quando estiverem no projeto.
• Transporte plugável (ApiBrasil.Core.Transport): um módulo com o behaviour, uma tupla {módulo, opções} ou uma função de aridade 1 — o atalho para testes sem rede.
• Retry com backoff exponencial e jitter (ApiBrasil.Core.Retry; padrão: HTTP 429 e falhas de conexão; nunca timeouts nem erros de negócio), com suporte a Retry-After em segundos ou data HTTP.
• Hooks de observabilidade (ApiBrasil.Core.Hooks): :request, :response e :retry, via mapa/keyword de funções ou módulo com o behaviour — falhas dentro de um hook nunca derrubam a requisição.
• Erros com categoria em %ApiBrasil.Core.Error{kind: ...} (:validation, :authentication, :insufficient_balance, :permission, :not_found, :rate_limit, :server, :network, :timeout, :api), com predicados (insufficient_balance?/1, rate_limit?/1, network?/1...), :status, :code, :response, :retry_after e :reason preservando a causa. É uma exceção: as variantes ! levantam o próprio struct.
• Envelopes com acessores: ApiBrasil.Core.DeviceResponse e ApiBrasil.Core.CreditResponse implementam Access — error?/1, message/1, response/1/data/1, balance/1, api_limit/1, to_map/1 e acesso direto por chave (envelope["response"]).
• Body flexível: mapas, keyword lists, nil e o builder ApiBrasil.Consulta (com tipo, homolog, lite, agrupados, extra e os campos do produto) são aceitos por qualquer função de serviço.
• Opções por escopo: ApiBrasil.with_options/2 fixa opções no cliente e toda chamada aceita :query, :headers, :bearer_token, :device_token, :secret_key, :timeout e :response_type.
• Configuração por ApiBrasil.Core.Config, por config :apibrasil, ... (inclusive {:system, "VAR"}) e pelas variáveis de ambiente APIBRASIL_BEARER_TOKEN, APIBRASIL_DEVICE_TOKEN, APIBRASIL_SECRET_KEY e APIBRASIL_BASE_URL — credenciais vazias contam como ausentes.
• Catálogo gerado (mix apibrasil.codegen) em ApiBrasil.Generated.Catalog: actions de WhatsApp/Evolution/WhatsMeow e os tipo de consulta com seus campos, por service_actions/1, evolution_paths/0, consulta_servicos/0 e consulta_tipos/0.
• Interface legada em ApiBrasil.Legacy (new/1, request/4, whatsapp/3, sms/3, cpf/3, cnpj/3 e as variantes !), mantendo o contrato das primeiras SDKs (credentials/body/action em uma string JSON) — inclusive devolver erros da API decodificados em {:ok, mapa} em vez de {:error, ...}.
• Documentação em português em todos os módulos, publicada no HexDocs, e exemplos executáveis em examples/ (elixir examples/basico.exs).
• Testes com transporte falso (rotas, headers, query, envelopes, erros, retry, transporte, catálogo e interface legada) — a suíte não faz nenhuma chamada de rede.
• CI no GitHub Actions em matriz Elixir/OTP (1.15/26 a 1.18/27) com mix format --check-formatted, mix compile --warnings-as-errors, mix test, mix credo --strict e mix hex.build.

Requisitos

• Elixir >= 1.14 e OTP >= 25 (:public_key.cacerts_get/0, usada na verificação de TLS do transporte padrão, exige OTP 25).
• Em Elixir < 1.18 / OTP < 27, adicione {:jason, "~> 1.4"} ao projeto para o codec JSON.