Base compartilhada por todos os serviços da SDK.
Reúne duas coisas:
- helpers de runtime (
get/3,post/4,device/5,credit/4...), usados tanto pelo código gerado quanto pelos serviços escritos à mão; - uma DSL (
use ApiBrasil.Core.Service) que declara as rotas a partir de uma tabela — as rotas device-based e as consultas por crédito são perfeitamente uniformes, então descrevê-las é mais claro (e menos sujeito a divergência) do que repetir o mesmo corpo em cada função.
Declarando um serviço
defmodule ApiBrasil.Messaging.WhatsApp do
use ApiBrasil.Core.Service, device: "whatsapp"
action(:send_text, "sendText", "Envia uma mensagem de texto.")
endCada rota declarada gera duas funções: a que devolve
{:ok, resultado} | {:error, %ApiBrasil.Core.Error{}} e a variante !,
que devolve o resultado direto e levanta em caso de falha.
Opções do use
device: "whatsapp"— serviço device-based: geraservice/0,request/4(qualquer action do catálogo) equeue/4(a mesma action por fila). As rotas são declaradas comaction/3.credit: true— consultas por crédito: gerageneric/4ecredits/3. As rotas são declaradas comcredit/3.- sem opções — serviço da plataforma: apenas os helpers e as macros
route_get/3,route_post/3,route_put/3,route_delete/3eroute_empty/4.
Summary
Functions
Declara uma action device-based: POST /{servico}/{action}.
Declara uma consulta por crédito: POST /consulta/{servico}/credits.
Consulta os créditos disponíveis de um serviço: GET /consulta/{servico}/credits.
Faz um POST e embrulha a resposta no envelope das consultas por crédito —
atalho para rotas fora do padrão /consulta/{servico}/credits.
Executa uma consulta por crédito: POST /consulta/{servico}/credits.
DELETE path.
Executa uma action device-based: POST /{servico}/{action}.
Monta o caminho de uma action device-based.
Executa a action device-based por fila: POST /{servico}/{action}/queue.
Baixa os bytes crus de uma rota (PDF de boleto, imagens...).
Codifica um segmento de caminho de URL.
GET path.
GET path com a query mesclada às opções da chamada.
PATCH path.
POST path.
Executa uma requisição arbitrária no gateway.
Declara uma rota DELETE com body. Gera nome/3 e nome!/3.
Declara uma rota sem body e sem parâmetros, no verbo informado.
Declara uma rota GET sem body.
Declara uma rota POST com body.
Declara uma rota PUT com body. Gera nome/3 e nome!/3.
Desembrulha um resultado: devolve o valor de {:ok, valor} e levanta o
ApiBrasil.Core.Error de {:error, erro}.
Injeta a SecretKey do cliente nas opções quando ela não foi informada.
Types
@type result() :: {:ok, map()} | {:error, ApiBrasil.Core.Error.t()}
Functions
Declara uma action device-based: POST /{servico}/{action}.
action(:send_text, "sendText", "Envia uma mensagem de texto.")Gera send_text/3 ({:ok, envelope} | {:error, erro}) e send_text!/3.
Declara uma consulta por crédito: POST /consulta/{servico}/credits.
credit(:cpf, "cpf", "Consulta um CPF.")Gera cpf/3 ({:ok, envelope} | {:error, erro}) e cpf!/3.
@spec credit_balance(ApiBrasil.Client.t(), String.t(), keyword()) :: {:ok, ApiBrasil.Core.CreditResponse.t()} | {:error, ApiBrasil.Core.Error.t()}
Consulta os créditos disponíveis de um serviço: GET /consulta/{servico}/credits.
@spec credit_post(ApiBrasil.Client.t(), String.t(), term(), keyword()) :: {:ok, ApiBrasil.Core.CreditResponse.t()} | {:error, ApiBrasil.Core.Error.t()}
Faz um POST e embrulha a resposta no envelope das consultas por crédito —
atalho para rotas fora do padrão /consulta/{servico}/credits.
@spec credit_request(ApiBrasil.Client.t(), String.t(), term(), keyword()) :: {:ok, ApiBrasil.Core.CreditResponse.t()} | {:error, ApiBrasil.Core.Error.t()}
Executa uma consulta por crédito: POST /consulta/{servico}/credits.
Devolve o envelope ApiBrasil.Core.CreditResponse.
@spec delete(ApiBrasil.Client.t(), String.t(), term(), keyword()) :: result()
DELETE path.
@spec device(ApiBrasil.Client.t(), String.t(), String.t(), term(), keyword()) :: {:ok, ApiBrasil.Core.DeviceResponse.t()} | {:error, ApiBrasil.Core.Error.t()}
Executa uma action device-based: POST /{servico}/{action}.
Devolve o envelope ApiBrasil.Core.DeviceResponse.
Monta o caminho de uma action device-based.
@spec device_queue(ApiBrasil.Client.t(), String.t(), String.t(), term(), keyword()) :: {:ok, ApiBrasil.Core.DeviceResponse.t()} | {:error, ApiBrasil.Core.Error.t()}
Executa a action device-based por fila: POST /{servico}/{action}/queue.
@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...).
Codifica um segmento de caminho de URL.
@spec get(ApiBrasil.Client.t(), String.t(), keyword()) :: result()
GET path.
GET path com a query mesclada às opções da chamada.
@spec patch(ApiBrasil.Client.t(), String.t(), term(), keyword()) :: result()
PATCH path.
@spec post(ApiBrasil.Client.t(), String.t(), term(), keyword()) :: result()
POST path.
@spec put(ApiBrasil.Client.t(), String.t(), term(), keyword()) :: result()
PUT path.
@spec request( ApiBrasil.Client.t(), ApiBrasil.Core.Transport.method(), String.t(), term(), keyword() ) :: result()
Executa uma requisição arbitrária no gateway.
Declara uma rota DELETE com body. Gera nome/3 e nome!/3.
Declara uma rota sem body e sem parâmetros, no verbo informado.
route_empty(:token_rotate, :post, "auth/token/rotate", "Rotaciona o token.")Gera token_rotate/2 e token_rotate!/2.
Declara uma rota GET sem body.
route_get(:balance, "balance", "Saldo/créditos da conta.")Gera balance/2 e balance!/2.
Declara uma rota POST com body.
route_post(:recharge, "recharge", "Cria uma recarga.")Gera recharge/3 e recharge!/3.
Declara uma rota PUT com body. Gera nome/3 e nome!/3.
@spec unwrap!({:ok, value} | {:error, ApiBrasil.Core.Error.t()}) :: value when value: term()
Desembrulha um resultado: devolve o valor de {:ok, valor} e levanta o
ApiBrasil.Core.Error de {:error, erro}.
É o que as variantes ! usam.
@spec with_secret_key( ApiBrasil.Client.t(), keyword() ) :: keyword()
Injeta a SecretKey do cliente nas opções quando ela não foi informada.