apigratis-sdk-ruby 0.0.1

checksums.yaml

@@ -0,0 +1,7 @@
+---
+SHA256:
+  metadata.gz: 703aa78add23af99d379d95a3250e92e42d534c10d5b03bceea39f5ee35fdbff
+  data.tar.gz: 79b15e74451aae75e95a10ef9113159d4afc4554812af5e342aa2246e562ab02
+SHA512:
+  metadata.gz: c264b039bb789492b0d54a27e45b2e9d8bd1d6ff2198072a7d754b7ddb6b716844cbf221924a6277d9e6d52c939a2cc6a83c1f7dcf78ab54aa15275f24bc13ed
+  data.tar.gz: 4fb02cd917518f2fcec049cb520ab5b74dd8a6246eca12cede13c3744cf498244734ca891211f36dc5cebaf2ca3215dbf37f8f675a4e36f9334fc05e4dcbd726

data/CHANGELOG.md

@@ -0,0 +1,27 @@
+# Changelog
+
+## 0.0.1 — 2026-07-24
+
+Primeira versão do cliente `ApiBrasil` em Ruby, cobrindo toda a plataforma
+APIBrasil — mesma arquitetura, mesmos endpoints e mesmas funções das SDKs
+Node.js, PHP, Flutter, Go e Java.
+
+### Novidades
+
+- **Cliente central `ApiBrasil::Client`** (`ApiBrasil.new`) com módulos por produto: `whatsapp`, `evolution`, `whatsmeow`, `sms`, `dados`, `vehicles`, `fipe`, `correios`, `cep`, `geolocation`, `geomatrix`, `recognize`, `ddd`, `holidays`, `translate`, `weather`, `loterias`, `database_ip`, `consulta` (créditos), `ura`, `chip_virtual`, `bulk`, `auth` (login/2FA), `devices`, `catalog`, `account`, `payments` (PIX/boleto/cartão), `ip_whitelist`, `bearer_rate_limit`, `reports`.
+- **Transporte plugável** (`ApiBrasil::Core::Transport::Base`): `NetHttpTransport` (stdlib, sem dependências) por padrão, `FaradayTransport` usado automaticamente quando o Faraday já está carregado, e injeção de implementações próprias para proxies e mocks.
+- **Retry com backoff exponencial** (padrão: HTTP 429 e falhas de conexão; nunca timeouts nem erros de negócio) com suporte a `Retry-After`.
+- **Hooks de observabilidade**: `on_request`, `on_response`, `on_retry`.
+- **Hierarquia de erros**: `ValidationError`, `AuthenticationError`, `InsufficientBalanceError`, `PermissionError`, `NotFoundError`, `RateLimitError`, `ServerError`, `NetworkError`, `TimeoutError` — todas herdando de `ApiBrasilError`.
+- **Variáveis de ambiente**: `APIBRASIL_BEARER_TOKEN`, `APIBRASIL_DEVICE_TOKEN`, `APIBRASIL_SECRET_KEY`, `APIBRASIL_BASE_URL` lidas automaticamente.
+- **Catálogo gerado** (`rake codegen`): `Catalog::WHATSAPP_ACTIONS`, `EVOLUTION_PATHS`, `WHATSMEOW_ACTIONS`, `CONSULTA_SERVICOS`, `CONSULTA_TIPOS` (210 tipos) e `SERVICE_ACTIONS`.
+- **Múltiplos devices** com `with_device`, e `ApiBrasil.login` devolvendo um cliente já autenticado.
+- **Testes** unitários com transporte fake (cobrindo todas as rotas e o catálogo) e de contrato opcionais (`APIBRASIL_CONTRACT=1 rake contract`).
+- **Interface legada** `ApiBrasil::Legacy::Service` / `Apigratis::Service` com o contrato antigo das SDKs APIGratis (sempre `POST`, erros devolvidos no corpo). Deprecada — prefira `ApiBrasil.new`.
+
+### Notas
+
+- `timeout` é em **milissegundos** (paridade com as SDKs Node/PHP). A interface legada continua em segundos.
+- As respostas são `Hash` com chaves em `String`, exatamente como vêm da API.
+- A configuração aceita `snake_case` (idiomático) e `camelCase` (`bearerToken`, `baseURL`, `minDelayMs`), facilitando a migração de quem já usa as outras SDKs.
+- `api.sms.send` existe por paridade com as demais SDKs; `send_message` é o nome idiomático em Ruby.

data/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Jhon
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

data/README.md

@@ -0,0 +1,330 @@
+# SDK Ruby - APIGratis by API BRASIL 🚀
+
+SDK oficial Ruby da plataforma [APIBrasil](https://apibrasil.com.br) — WhatsApp, SMS, consultas de CPF/CNPJ, veículos, CEP, correios, pagamentos PIX/boleto e muito mais.
+
+[![CI](https://github.com/jhowbhz/apigratis-sdk-ruby/actions/workflows/ci.yml/badge.svg)](https://github.com/jhowbhz/apigratis-sdk-ruby/actions/workflows/ci.yml)
+[![license mit](https://img.shields.io/badge/license-MIT-green.svg)](LICENSE)
+[![Ruby](https://img.shields.io/badge/ruby-%3E%3D%203.0-CC342D.svg?logo=ruby)](https://www.ruby-lang.org)
+<a href="https://github.com/jhowbhz/apigratis-sdk-ruby/issues" target="_blank"><img alt="GitHub issues" src="https://img.shields.io/github/issues/jhowbhz/apigratis-sdk-ruby"></a>
+<a href="https://github.com/jhowbhz/apigratis-sdk-ruby/stargazers" target="_blank"><img alt="GitHub stars" src="https://img.shields.io/github/stars/jhowbhz/apigratis-sdk-ruby"></a>
+
+## Canais de suporte (Comunidade)
+
+[![WhatsApp Group](https://img.shields.io/badge/WhatsApp-Group-25D366?logo=whatsapp)](https://chat.whatsapp.com/EeAWALQb6Ga5oeTbG7DD2k)
+[![Telegram Group](https://img.shields.io/badge/Telegram-Group-32AFED?logo=telegram)](https://t.me/apigratisoficial)
+
+## Instalação
+
+```bash
+gem install apigratis-sdk-ruby
+```
+
+Ou no `Gemfile`:
+
+```ruby
+gem "apigratis-sdk-ruby"
+```
+
+Requer **Ruby >= 3.0**. Não tem dependências de runtime — o transporte padrão usa
+a stdlib (`net/http`) e o Faraday é usado automaticamente quando já está carregado
+no processo. A camada de transporte é plugável.
+
+Obtenha suas credenciais em https://apibrasil.com.br
+
+## Começando
+
+```ruby
+require "api_brasil"
+
+api = ApiBrasil.new(
+  bearer_token: ENV["APIBRASIL_BEARER_TOKEN"], # JWT do login
+  device_token: ENV["APIBRASIL_DEVICE_TOKEN"]  # device dos serviços device-based
+)
+
+# WhatsApp
+api.whatsapp.send_text("number" => "5511999999999", "text" => "Olá! 👋")
+
+# Consulta CNPJ (por créditos)
+empresa = api.consulta.cnpj("cnpj" => "00000000000000")
+pp empresa["data"]
+```
+
+As credenciais também podem vir só do ambiente — `ApiBrasil.new` lê automaticamente
+`APIBRASIL_BEARER_TOKEN`, `APIBRASIL_DEVICE_TOKEN`, `APIBRASIL_SECRET_KEY` e `APIBRASIL_BASE_URL`.
+
+Todas as respostas são devolvidas como **Hash** já decodificado (chaves em `String`,
+exatamente como vêm da API).
+
+Também é possível autenticar por email/senha — o token retornado fica guardado no cliente:
+
+```ruby
+api = ApiBrasil.new
+api.auth.login("email" => "voce@empresa.com.br", "password" => "******")
+
+# contas com 2FA:
+session = api.auth.login("email" => email, "password" => password)
+if session["requires_2fa"]
+  api.auth.send_2fa("challenge" => session["challenge"], "method" => "email")
+  api.auth.verify_2fa("challenge" => session["challenge"], "code" => "000000")
+end
+```
+
+## 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:
+
+```ruby
+device = api.devices.store(
+  { "device_name" => "meu-bot", "type" => "server" },
+  secret_key: "SUA_SECRET_KEY"
+)
+
+api.set_device_token(device["device"]["device_token"])
+```
+
+## Serviços disponíveis
+
+| Módulo                                                       | Descrição                                                                                         |
+| ------------------------------------------------------------ | ------------------------------------------------------------------------------------------------- |
+| `api.whatsapp`                                               | WhatsApp: `start`, `qrcode`, `send_text`, `send_file`, `send_audio`, `send_video`, fila (`queue`)  |
+| `api.evolution`                                              | Evolution API: `request(controller, action, body)`                                                 |
+| `api.whatsmeow`                                              | WhatsMeow: `request(action, body)`                                                                 |
+| `api.sms`                                                    | SMS device-based (`send_message`/`send`) e por créditos (`send_with_credits`)                      |
+| `api.dados`                                                  | Dados cadastrais device-based (`cpf`, `cnpj`)                                                      |
+| `api.vehicles`                                               | Veículos por placa (`dados`, `fipe`, `consulta_fipe`)                                              |
+| `api.fipe`                                                   | Tabela FIPE (`marcas`, `modelos`, `ano_modelo`, `valor`)                                           |
+| `api.correios`                                               | Correios (`rastreio`, `request`)                                                                   |
+| `api.cep`                                                    | CEP + geolocalização (`cep`, `cidades`, `estados`, `distancia`)                                    |
+| `api.geolocation` / `api.geomatrix`                          | Geolocalização e matriz de distâncias                                                              |
+| `api.recognize`                                              | OCR / Google Vision (`base64`, `uri`)                                                              |
+| `api.ddd` / `api.holidays` / `api.translate` / `api.weather` | DDD, feriados, tradução, clima                                                                     |
+| `api.loterias`                                               | Loterias (`resultado`, `latest`)                                                                   |
+| `api.database_ip`                                            | GeoIP (`ip`)                                                                                       |
+| `api.consulta`                                               | Consultas por créditos: `cpf`, `cnpj`, `cnh`, `cep`, `veiculos`, `telefone`, `generic(...)`        |
+| `api.ura` / `api.chip_virtual`                               | 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.ip_whitelist` / `api.bearer_rate_limit`                 | Segurança da conta                                                                                 |
+| `api.reports`                                                | Relatórios e dashboard de consumo                                                                  |
+
+### WhatsApp
+
+```ruby
+# iniciar sessão e obter QR Code
+api.whatsapp.start("webhook_wh_message" => "https://seu-webhook.com/mensagens")
+
+qr = api.whatsapp.qrcode
+puts qr["response"]["qrcode"] # data URI base64
+
+# envios
+api.whatsapp.send_text("number" => "5511999999999", "text" => "Olá!")
+api.whatsapp.send_file("number" => "5511999999999", "path" => "https://exemplo.com/nota.pdf")
+api.whatsapp.send_audio("number" => "5511999999999", "path" => "https://exemplo.com/audio.mp3")
+
+# qualquer action da documentação, inclusive via fila
+api.whatsapp.request("sendLocation", "number" => "5511999999999", "lat" => -23.5, "lng" => -46.6)
+api.whatsapp.queue("sendText", "number" => "5511999999999", "text" => "assíncrono 🚀")
+```
+
+### Consultas por créditos
+
+```ruby
+# CPF / CNPJ
+cpf = api.consulta.cpf("cpf" => "00000000000")
+socios = api.consulta.cnpj("cnpj" => "00000000000000", "tipo" => "lista-socios")
+
+# veicular
+veiculo = api.consulta.veiculos("placa" => "ABC1234")
+
+# qualquer produto do catálogo
+score = api.consulta.generic("cpf", "cpf" => "00000000000", "tipo" => "serasa-score-pf")
+
+# homologação (sandbox, sem cobrança)
+teste = api.consulta.cpf("cpf" => "00000000000", "homolog" => true)
+```
+
+### Veículos e FIPE (device-based)
+
+```ruby
+dados = api.vehicles.dados("placa" => "ABC1234")
+fipe = api.vehicles.fipe("placa" => "ABC1234")
+```
+
+### SMS
+
+```ruby
+api.sms.send_message("number" => "5511999999999", "message" => "Seu código: 123456")
+# ou debitando créditos da conta (sem device):
+api.sms.send_with_credits("number" => "5511999999999", "message" => "Olá!")
+```
+
+> `api.sms.send(...)` também funciona (paridade com as demais SDKs). `send_message`
+> é o nome idiomático em Ruby, já que `Object#send` tem outro significado na
+> linguagem — `public_send` e `__send__` continuam disponíveis normalmente.
+
+### Pagamentos e recargas
+
+```ruby
+pix = api.payments.pix_generate("inter", "amount" => 100)
+status = api.payments.pix_status("inter", pix["txId"])
+
+boleto = api.payments.boleto_generate("sicoob", "amount" => 150)
+pdf = api.payments.boleto_pdf("sicoob", boleto["id"]) # conteúdo binário
+```
+
+### Múltiplos devices
+
+```ruby
+comercial = api.with_device("DEVICE_TOKEN_COMERCIAL")
+suporte = api.with_device("DEVICE_TOKEN_SUPORTE")
+
+comercial.whatsapp.send_text("number" => "55...", "text" => "Proposta enviada!")
+suporte.whatsapp.send_text("number" => "55...", "text" => "Como posso ajudar?")
+```
+
+## Tratamento de erros
+
+Cada categoria de falha tem a sua própria classe — todas herdam de
+`ApiBrasil::ApiBrasilError` (que por sua vez herda de `StandardError`):
+
+| Classe                                     | Quando                                   |
+| ------------------------------------------ | ---------------------------------------- |
+| `ApiBrasil::ValidationError`               | 400/422 — payload inválido               |
+| `ApiBrasil::AuthenticationError`           | 401 — token ausente/expirado             |
+| `ApiBrasil::InsufficientBalanceError`      | 402 — sem saldo/créditos                 |
+| `ApiBrasil::PermissionError`               | 403 — sem permissão (ex: exige PJ)       |
+| `ApiBrasil::NotFoundError`                 | 404/410 — sem dados / rota desativada    |
+| `ApiBrasil::RateLimitError`                | 429 — limite atingido (`retry_after_ms`) |
+| `ApiBrasil::ServerError`                   | 5xx — erro do gateway/provedor           |
+| `ApiBrasil::NetworkError` / `TimeoutError` | falha antes da resposta                  |
+
+```ruby
+begin
+  api.consulta.cpf("cpf" => "00000000000")
+rescue ApiBrasil::InsufficientBalanceError
+  puts "Recarregue seus créditos"
+rescue ApiBrasil::RateLimitError => e
+  puts "Aguarde #{e.retry_after_ms}ms"
+end
+```
+
+Todo erro expõe `status` (HTTP), `error_code` (código da API) e `response`
+(corpo completo da resposta).
+
+## 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.
+
+```ruby
+api = ApiBrasil.new(
+  retry: { retries: 3, min_delay_ms: 500, retry_on_statuses: [429, 503] }, # ou retry: false
+  hooks: {
+    on_request: ->(i) { puts "→ #{i[:method]} #{i[:url]} (##{i[:attempt]})" },
+    on_response: ->(i) { puts "← #{i[:status]} em #{i[:duration_ms]}ms" },
+    on_retry: ->(i) { puts "retry em #{i[:delay_ms]}ms: #{i[:reason]}" }
+  }
+)
+```
+
+## Transporte plugável
+
+O HTTP é feito pela stdlib (`net/http`), com uso automático do Faraday quando ele já
+está carregado. A classe base `ApiBrasil::Core::Transport::Base` permite trocar a
+camada inteira (proxy corporativo, outro cliente, mocks de teste):
+
+```ruby
+# net/http com opções próprias (proxy, verificação TLS, CA...)
+api = ApiBrasil.new(
+  transport: ApiBrasil::NetHttpTransport.new(proxy_address: "proxy.local", proxy_port: 3128)
+)
+
+# ou Faraday, com middlewares e adaptador próprios
+require "faraday"
+api = ApiBrasil.new(transport: ApiBrasil::FaradayTransport.new(Faraday.new { |f| f.adapter :net_http }))
+```
+
+Ou implemente o seu:
+
+```ruby
+class MeuTransporte < ApiBrasil::Core::Transport::Base
+  def request(request)
+    # use o cliente HTTP que quiser e devolva status, headers e corpo
+    ApiBrasil::Core::Transport::Response.new(200, {}, { "ok" => true })
+  end
+end
+
+api = ApiBrasil.new(transport: MeuTransporte.new)
+```
+
+## Catálogo gerado
+
+As actions de WhatsApp/Evolution/WhatsMeow e os 210+ `tipo` de consulta estão
+disponíveis em constantes geradas do catálogo real da plataforma
+(`rake codegen` atualiza):
+
+```ruby
+ApiBrasil::Catalog::WHATSAPP_ACTIONS            # ["sendText", "sendFile", ...]
+ApiBrasil::Catalog.service_actions("whatsmeow") # actions documentadas do serviço
+ApiBrasil::Catalog.consulta_tipo("acerta-essencial")
+# => { service: "cpf", fields: ["cpf"] }
+```
+
+## 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:
+
+```ruby
+api.request("POST", "/consulta/cpf/credits", "cpf" => "00000000000")
+api.request("GET", "/reports/quick-stats")
+```
+
+Documentação completa dos endpoints: https://doc.apibrasil.io
+
+## Configuração avançada
+
+```ruby
+api = ApiBrasil.new(
+  bearer_token: "...", # ou APIBRASIL_BEARER_TOKEN
+  device_token: "...", # ou APIBRASIL_DEVICE_TOKEN
+  secret_key: "...",   # usada em devices.store (ou APIBRASIL_SECRET_KEY)
+  base_url: "https://gateway.apibrasil.io/api/v2", # padrão (ou APIBRASIL_BASE_URL)
+  timeout: 30_000,     # milissegundos
+  headers: { "X-Custom" => "valor" }, # headers extras
+  retry: { retries: 2 },              # ou false
+  hooks: { on_retry: ->(i) { warn i[:reason] } },
+  transport: nil       # transporte customizado
+)
+```
+
+As chaves em camelCase (`bearerToken`, `baseURL`, `minDelayMs`...) também são aceitas,
+para facilitar quem já usa as SDKs Node/PHP.
+
+Opções por requisição (último parâmetro de qualquer método): `query`, `headers`,
+`bearer_token`, `device_token`, `secret_key`, `timeout`, `response_type`.
+
+```ruby
+api.whatsapp.send_text(
+  { "number" => "5511999999999", "text" => "Olá!" },
+  device_token: "OUTRO_DEVICE", timeout: 60_000
+)
+```
+
+> **Atenção:** `timeout` é em **milissegundos** (igual às SDKs Node/PHP), diferente
+> da interface legada, que usa segundos.
+
+## Licença
+
+MIT — veja [LICENSE](LICENSE).

data/SECURITY.md

@@ -0,0 +1,32 @@
+# Security Policy
+
+## Versões suportadas
+
+| Versão  | Suportada          |
+| ------- | ------------------ |
+| 0.0.x   | :white_check_mark: |
+
+Ruby suportado: **3.0 ou superior**.
+
+## Reportando uma vulnerabilidade
+
+Não abra issues públicas para falhas de segurança.
+
+Envie os detalhes para **contato@apibrasil.com.br** com:
+
+- descrição da falha e impacto;
+- passos para reproduzir (ou prova de conceito);
+- versão da SDK e do Ruby.
+
+Retornamos o primeiro contato em até **72 horas** e mantemos você informado até a
+correção. Correções são publicadas como uma nova versão do gem, com o crédito ao
+reporter (quando autorizado).
+
+## Boas práticas ao usar a SDK
+
+- Nunca versione `APIBRASIL_BEARER_TOKEN`, `APIBRASIL_DEVICE_TOKEN` ou
+  `APIBRASIL_SECRET_KEY` — use variáveis de ambiente ou um cofre de segredos.
+- Restrinja os IPs que podem usar o seu Bearer Token com `api.ip_whitelist`.
+- Configure o limite por minuto do token com `api.bearer_rate_limit`.
+- Rotacione o token periodicamente (`api.auth.token_rotate`) e revogue os que
+  não estão mais em uso (`api.auth.token_revoke`).

data/lib/api_brasil/client.rb

@@ -0,0 +1,252 @@
+# frozen_string_literal: true
+
+require_relative "core/http_client"
+require_relative "services/base_service"
+require_relative "services/device_proxy_service"
+require_relative "services/data/bulk_service"
+require_relative "services/data/cep_service"
+require_relative "services/data/chip_virtual_service"
+require_relative "services/data/consulta_service"
+require_relative "services/data/correios_service"
+require_relative "services/data/dados_service"
+require_relative "services/data/database_ip_service"
+require_relative "services/data/fipe_service"
+require_relative "services/data/proxies"
+require_relative "services/data/ura_service"
+require_relative "services/data/vehicles_service"
+require_relative "services/messaging/evolution_service"
+require_relative "services/messaging/sms_service"
+require_relative "services/messaging/whats_meow_service"
+require_relative "services/messaging/whatsapp_service"
+require_relative "services/platform/account_service"
+require_relative "services/platform/auth_service"
+require_relative "services/platform/bearer_rate_limit_service"
+require_relative "services/platform/catalog_service"
+require_relative "services/platform/devices_service"
+require_relative "services/platform/ip_whitelist_service"
+require_relative "services/platform/payments_service"
+require_relative "services/platform/reports_service"
+
+module ApiBrasil
+  # Cliente oficial da plataforma APIBrasil.
+  #
+  #   api = ApiBrasil.new(
+  #     bearer_token: ENV["APIBRASIL_BEARER_TOKEN"],
+  #     device_token: ENV["APIBRASIL_DEVICE_TOKEN"]
+  #   )
+  #
+  #   api.whatsapp.send_text("number" => "5511999999999", "text" => "Ola!")
+  #   empresa = api.consulta.cnpj("cnpj" => "00000000000000")
+  #
+  # Credenciais nao informadas sao lidas das variaveis de ambiente
+  # `APIBRASIL_BEARER_TOKEN`, `APIBRASIL_DEVICE_TOKEN`,
+  # `APIBRASIL_SECRET_KEY` e `APIBRASIL_BASE_URL`.
+  class Client
+    # @return [Core::HttpClient] cliente HTTP interno (headers, retry, hooks, erros)
+    attr_reader :http
+
+    # @return [Services::Platform::AuthService] login, 2FA, cadastro, senha e perfil
+    attr_reader :auth
+
+    # @return [Services::Platform::DevicesService] gestao de devices
+    attr_reader :devices
+
+    # @return [Services::Messaging::WhatsAppService] WhatsApp device-based (`/whatsapp/{action}`)
+    attr_reader :whatsapp
+
+    # @return [Services::Messaging::EvolutionService] Evolution API (`/evolution/{controller}/{action}`)
+    attr_reader :evolution
+
+    # @return [Services::Messaging::WhatsMeowService] WhatsMeow (`/whatsmeow/{action}`)
+    attr_reader :whatsmeow
+
+    # @return [Services::Messaging::SmsService] SMS (`/sms/{action}` e `/sms/send/credits`)
+    attr_reader :sms
+
+    # @return [Services::Data::DadosService] dados cadastrais device-based
+    attr_reader :dados
+
+    # @return [Services::Data::VehiclesService] veiculos por placa
+    attr_reader :vehicles
+
+    # @return [Services::Data::FipeService] tabela FIPE
+    attr_reader :fipe
+
+    # @return [Services::Data::CorreiosService] Correios
+    attr_reader :correios
+
+    # @return [Services::Data::CepService] CEP + geolocalizacao
+    attr_reader :cep
+
+    # @return [Services::Data::GeolocationService] geolocalizacao
+    attr_reader :geolocation
+
+    # @return [Services::Data::GeomatrixService] matriz de distancias
+    attr_reader :geomatrix
+
+    # @return [Services::Data::RecognizeService] OCR / Google Vision
+    attr_reader :recognize
+
+    # @return [Services::Data::DddService] DDD
+    attr_reader :ddd
+
+    # @return [Services::Data::HolidaysService] feriados
+    attr_reader :holidays
+
+    # @return [Services::Data::TranslateService] traducao
+    attr_reader :translate
+
+    # @return [Services::Data::WeatherService] clima
+    attr_reader :weather
+
+    # @return [Services::Data::LoteriasService] loterias
+    attr_reader :loterias
+
+    # @return [Services::Data::DatabaseIpService] GeoIP (`/database/ip`)
+    attr_reader :database_ip
+
+    # @return [Services::Data::ConsultaService] consultas por credito
+    attr_reader :consulta
+
+    # @return [Services::Data::UraService] URA reversa / ligacoes
+    attr_reader :ura
+
+    # @return [Services::Data::ChipVirtualService] chip virtual
+    attr_reader :chip_virtual
+
+    # @return [Services::Data::BulkService] execucao em lote
+    attr_reader :bulk
+
+    # @return [Services::Platform::CatalogService] catalogo de APIs, planos, docs e servidores
+    attr_reader :catalog
+
+    # @return [Services::Platform::AccountService] saldo, faturas, notificacoes, tickets
+    attr_reader :account
+
+    # @return [Services::Platform::PaymentsService] recargas e pagamentos (PIX, boleto, cartao)
+    attr_reader :payments
+
+    # @return [Services::Platform::IpWhitelistService] IP whitelist da conta
+    attr_reader :ip_whitelist
+
+    # @return [Services::Platform::BearerRateLimitService] rate limit por Bearer Token
+    attr_reader :bearer_rate_limit
+
+    # @return [Services::Platform::ReportsService] relatorios e dashboard de consumo
+    attr_reader :reports
+
+    # @param config [Hash] veja `Core::HttpClient` para as chaves aceitas
+    def initialize(config = {})
+      @http = Core::HttpClient.new(config)
+
+      @auth = Services::Platform::AuthService.new(@http)
+      @devices = Services::Platform::DevicesService.new(@http)
+
+      @whatsapp = Services::Messaging::WhatsAppService.new(@http)
+      @evolution = Services::Messaging::EvolutionService.new(@http)
+      @whatsmeow = Services::Messaging::WhatsMeowService.new(@http)
+      @sms = Services::Messaging::SmsService.new(@http)
+
+      @dados = Services::Data::DadosService.new(@http)
+      @vehicles = Services::Data::VehiclesService.new(@http)
+      @fipe = Services::Data::FipeService.new(@http)
+      @correios = Services::Data::CorreiosService.new(@http)
+      @cep = Services::Data::CepService.new(@http)
+      @geolocation = Services::Data::GeolocationService.new(@http)
+      @geomatrix = Services::Data::GeomatrixService.new(@http)
+      @recognize = Services::Data::RecognizeService.new(@http)
+      @ddd = Services::Data::DddService.new(@http)
+      @holidays = Services::Data::HolidaysService.new(@http)
+      @translate = Services::Data::TranslateService.new(@http)
+      @weather = Services::Data::WeatherService.new(@http)
+      @loterias = Services::Data::LoteriasService.new(@http)
+      @database_ip = Services::Data::DatabaseIpService.new(@http)
+
+      @consulta = Services::Data::ConsultaService.new(@http)
+      @ura = Services::Data::UraService.new(@http)
+      @chip_virtual = Services::Data::ChipVirtualService.new(@http)
+      @bulk = Services::Data::BulkService.new(@http)
+
+      @catalog = Services::Platform::CatalogService.new(@http)
+      @account = Services::Platform::AccountService.new(@http)
+      @payments = Services::Platform::PaymentsService.new(@http)
+      @ip_whitelist = Services::Platform::IpWhitelistService.new(@http)
+      @bearer_rate_limit = Services::Platform::BearerRateLimitService.new(@http)
+      @reports = Services::Platform::ReportsService.new(@http)
+    end
+
+    # Faz login e retorna um cliente ja autenticado.
+    # Levanta `ApiBrasilError` se a conta exigir 2FA - nesse caso crie o
+    # cliente manualmente e use `auth.login` + `auth.verify_2fa`.
+    #
+    # @param credentials [Hash] `email` e `password`
+    # @param config [Hash]
+    # @return [Hash] `{ client: Client, session: Object }`
+    def self.login(credentials, config = {})
+      client = new(config)
+      session = client.auth.login(credentials)
+
+      if session.is_a?(Hash) && session["requires_2fa"]
+        raise Core::Errors::ApiBrasilError.new(
+          "Esta conta exige autenticacao em dois fatores. Use auth.login + auth.verify_2fa.",
+          response: session
+        )
+      end
+
+      { client: client, session: session }
+    end
+
+    # Define/atualiza o Bearer Token do cliente.
+    #
+    # @return [self]
+    def set_bearer_token(token)
+      http.bearer_token = token
+      self
+    end
+
+    # Define/atualiza o DeviceToken do cliente.
+    #
+    # @return [self]
+    def set_device_token(token)
+      http.device_token = token
+      self
+    end
+
+    # @return [String, nil]
+    def bearer_token
+      http.bearer_token
+    end
+
+    def bearer_token=(token)
+      http.bearer_token = token
+    end
+
+    # @return [String, nil]
+    def device_token
+      http.device_token
+    end
+
+    def device_token=(token)
+      http.device_token = token
+    end
+
+    # Retorna um novo cliente com as mesmas credenciais, mas apontando
+    # para outro device - util para gerenciar varios numeros/instancias.
+    #
+    # @return [Client]
+    def with_device(device_token)
+      self.class.new(http.to_config.merge(device_token: device_token))
+    end
+
+    # Porta de saida generica: chama qualquer endpoint do gateway com os
+    # headers de autenticacao ja configurados. Use para rotas que ainda
+    # nao tem metodo dedicado na SDK.
+    #
+    #   api.request("POST", "/consulta/cpf/credits", "cpf" => "...")
+    #
+    # @return [Object]
+    def request(method, path, body = nil, options = {})
+      http.request(method, path, body, options)
+    end
+  end
+end