@spec config(ApiBrasil.Client.t()) :: ApiBrasil.Core.Config.t()

Configuração atual do cliente.

@spec download(ApiBrasil.Client.t(), String.t(), keyword()) ::
  {:ok, binary()} | {:error, ApiBrasil.Core.Error.t()}

Baixa os bytes crus de uma rota (PDF de boleto, imagens...).

@spec execute(
  ApiBrasil.Client.t(),
  ApiBrasil.Core.Transport.method(),
  String.t(),
  term(),
  keyword()
) ::
  {:ok, term()} | {:error, ApiBrasil.Core.Error.t()}

Como request/5, mas devolve o corpo decodificado sem normalizar em objeto JSON (útil quando a rota responde uma lista, texto ou bytes).

@spec from_env() :: ApiBrasil.Client.t()

Cria o cliente apenas com as credenciais do ambiente.

@spec login(map() | keyword(), keyword() | map() | ApiBrasil.Core.Config.t()) ::
  {:ok, ApiBrasil.Client.t(), map()} | {:error, ApiBrasil.Core.Error.t()}

Autentica por email/senha e devolve um cliente já autenticado, junto da sessão retornada pela plataforma.

{:ok, client, sessao} =
  ApiBrasil.login(%{"email" => "voce@empresa.com.br", "password" => "******"})

Devolve erro quando a conta exige 2FA — nesse caso use ApiBrasil.Platform.Auth.login/3 + ApiBrasil.Platform.Auth.send_2fa/3 + ApiBrasil.Platform.Auth.verify_2fa/3.

@spec login!(map() | keyword(), keyword() | map() | ApiBrasil.Core.Config.t()) ::
  {ApiBrasil.Client.t(), map()}

Como login/2, mas levanta ApiBrasil.Core.Error em caso de falha.

@spec new(keyword() | map() | ApiBrasil.Core.Config.t()) :: ApiBrasil.Client.t()

Cria o cliente. Campos não informados vêm do ambiente e da configuração da aplicação.

ApiBrasil.new(bearer_token: "jwt", device_token: "device")

ApiBrasil.new(
  base_url: "https://gateway.apibrasil.io/api/v2",
  timeout: 60_000,
  headers: %{"X-Correlation-Id" => "abc-123"},
  retry: %ApiBrasil.Core.Retry{retries: 3},
  hooks: %{response: &IO.inspect/1}
)

Veja ApiBrasil.Core.Config para a lista completa de opções.

@spec put_bearer_token(ApiBrasil.Client.t(), String.t() | nil) :: ApiBrasil.Client.t()

Define/atualiza o Bearer Token, devolvendo um novo cliente.

@spec put_device_token(ApiBrasil.Client.t(), String.t() | nil) :: ApiBrasil.Client.t()

Define/atualiza o DeviceToken, devolvendo um novo cliente.

@spec put_secret_key(ApiBrasil.Client.t(), String.t() | nil) :: ApiBrasil.Client.t()

Define/atualiza a SecretKey, devolvendo um novo cliente.

@spec request(
  ApiBrasil.Client.t(),
  ApiBrasil.Core.Transport.method(),
  String.t(),
  term(),
  keyword()
) ::
  {:ok, map()} | {:error, ApiBrasil.Core.Error.t()}

Porta de saída genérica: chama qualquer endpoint do gateway com os headers de autenticação já configurados. Use para rotas que ainda não têm função dedicada na SDK.

ApiBrasil.request(client, :post, "/consulta/cpf/credits", %{"cpf" => "00000000000"})
ApiBrasil.request(client, :get, "/reports/quick-stats")

@spec request!(
  ApiBrasil.Client.t(),
  ApiBrasil.Core.Transport.method(),
  String.t(),
  term(),
  keyword()
) ::
  map()

Como request/5, mas levanta ApiBrasil.Core.Error em caso de falha.

@spec url(ApiBrasil.Client.t(), String.t()) :: String.t()

Monta a URL completa de um caminho do gateway.

@spec with_device(ApiBrasil.Client.t(), String.t()) :: ApiBrasil.Client.t()

Devolve um novo cliente com as mesmas credenciais, mas apontando para outro device — útil para gerenciar vários números/instâncias.

bot1 = ApiBrasil.with_device(client, "device_token_1")
bot2 = ApiBrasil.with_device(client, "device_token_2")

ApiBrasil.Messaging.WhatsApp.send_text(bot1, %{"number" => n, "text" => "do bot 1"})
ApiBrasil.Messaging.WhatsApp.send_text(bot2, %{"number" => n, "text" => "do bot 2"})

@spec with_options(
  ApiBrasil.Client.t(),
  keyword()
) :: ApiBrasil.Client.t()

Devolve um cliente que aplica opts em todas as chamadas — mesma base, mesmas credenciais.

client
|> ApiBrasil.with_options(secret_key: "SUA_SECRET_KEY")
|> ApiBrasil.Platform.Devices.store(%{"device_name" => "meu-bot"})