Ctrlk
For the complete documentation index, see llms.txt. This page is also available as Markdown.

💡Agências

Contas Gerenciadas (Agências)

As Contas Gerenciadas permitem que uma conta agência opere as contas filhas vinculadas a ela utilizando a própria Chave de API, sem precisar de um token por cliente. Através destes endpoints você pode listar suas contas filhas, consultar os dados de uma delas e executar qualquer chamada da API no contexto de um cliente específico.

A URL de base de todos os endpoints é: https://web.smsfunnel.com.br/api/parceiros/v1

Recurso exclusivo de contas agência. Uma Chave de API comum recebe 403 ON_BEHALF_NOT_ALLOWED ao enviar o header X-On-Behalf-Of e 403 FORBIDDEN ao chamar GET /accounts. A conta filha não precisa ter a API habilitada — a agência opera com a própria chave; o único requisito é o vínculo entre as contas.

O endpoint de listagem utiliza paginação simples. A resposta traz current_page, data, per_page, next_page_url e prev_page_url — não há campos total ou last_page. Para navegar, utilize o parâmetro de query page.

Como funciona

  1. A agência chama GET /accounts com a própria Chave de API e obtém o id (UUID) de cada conta filha.

  2. Em qualquer outra chamada da API, envia o header X-On-Behalf-Of com esse id.

  3. A requisição passa a ser executada inteiramente no contexto da conta filha — listas, campanhas, sequências, leads, broadcasts e chamadas de voz. A blacklist consultada é a da filha e os créditos debitados são os da filha.

  4. A resposta devolve o header X-Effective-Account confirmando sobre qual conta a operação ocorreu.

Headers utilizados:

{
    "Authorization": "Bearer {CHAVE_DA_AGENCIA}", // Obrigatório. Sempre a chave da agência.
    "X-On-Behalf-Of": "0190a1b2-7b31-7c4e-9a1d-2f3b4c5d6e7f", // Opcional. user_id da conta filha.
    "Accept": "application/json"
}

Headers devolvidos na resposta:

Endpoints

GET /accounts

Função: Lista as contas filhas ativas da agência, em ordem alfabética. É aqui que você obtém o id utilizado no header X-On-Behalf-Of.

Parâmetros de query (opcionais):

Corpo de resposta — 200 OK:

O email é retornado completo no corpo da resposta, para que a agência consiga desambiguar clientes com nomes parecidos. Ele nunca é aceito ou exposto na URL — a identificação da conta filha é sempre feita pelo id.

GET /accounts/{id}

Função: Obtém os detalhes de uma conta filha específica.

Corpo de resposta — 200 OK:

Um id que não pertence à sua agência (ou que não existe) retorna 404 NOT_FOUND — nunca 403. Não informamos a existência de contas de outros parceiros.

Operando uma conta filha

Para executar qualquer endpoint da API no contexto de um cliente, mantenha a Authorization da agência e adicione o header X-On-Behalf-Of com o id da conta filha.

Exemplo de requisição:

Comportamento do header:

  • Sem o header — o escopo é o da própria conta do token (comportamento padrão).

  • Agência + conta filha ativa e vinculada — a requisição opera a filha e a resposta traz X-Effective-Account.

  • Agência + conta que não é filha ativa (inexistente, inativa ou de outro parceiro) — 404 NOT_FOUND.

  • Chave de API que não é de agência + header — 403 ON_BEHALF_NOT_ALLOWED.

Confirme sempre o X-Effective-Account. Ele é devolvido em toda resposta em que o X-On-Behalf-Of foi aceito. Validá-lo evita que uma operação seja executada na conta errada.

Auditoria. Toda chamada realizada em nome de uma conta filha é registrada de forma assíncrona e durável (quem operou, qual conta, qual ação e quando). Uma agência operando a própria conta não gera registro.

Limite de Requisições

  • 60 requisições por minuto por conta efetiva. Sem o header X-On-Behalf-Of, a conta efetiva é a própria agência. Com o header, cada conta filha tem seu próprio limite — operar o Cliente A não consome o limite do Cliente B.

  • 600 requisições por minuto por Chave de API, como teto global. Ao atingi-lo, a chave recebe 429 mesmo que ainda haja limite disponível na conta filha.

  • Os limites são contabilizados por conta/chave, não por endpoint — todas as chamadas competem pelo mesmo orçamento.

  • Ao exceder, a resposta traz o header Retry-After com o tempo de espera em segundos.

O limite real de uma Chave de API é sempre 600 requisições por minuto. O limite de 60/min por conta efetiva existe para garantir o isolamento entre as contas filhas, e não representa uma vazão máxima garantida por chave.

Código de Erros Comuns

  • 401 Unauthorized (UNAUTHORIZED): Não foi possível identificar o parceiro a partir da Chave de API.

  • 403 Forbidden (FORBIDDEN): GET /accounts acessado por uma chave que não pertence a uma conta agência.

  • 403 Forbidden (ON_BEHALF_NOT_ALLOWED): Header X-On-Behalf-Of enviado por uma chave que não pertence a uma conta agência.

  • 404 Not Found (NOT_FOUND): A conta informada não existe, não está ativa ou não é uma conta filha da sua agência.

  • 429 Too Many Requests (RATE_LIMIT_EXCEEDED): Limite de requisições excedido. Consulte o header Retry-After.

Corpo de resposta de erro:

Dúvidas?

Em caso de dúvidas, entre em contato com nosso suporte.

PreviousBroadcastsNextReferência

Last updated