> For the complete documentation index, see [llms.txt](https://docs.smsfunnel.com.br/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://docs.smsfunnel.com.br/api/parceiros/agencias.md). # 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. {% hint style="success" %} **A URL de base de todos os endpoints é**: {% endhint %} {% hint style="warning" %} **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. {% endhint %} {% hint style="info" %} 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`. {% endhint %} **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:** ```json5 { "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:** ```json5 { "X-Effective-Account": "0190a1b2-7b31-7c4e-9a1d-2f3b4c5d6e7f" // Conta sobre a qual a requisição operou } ``` *** #### 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):** ```json5 { "per_page": 20, // Itens por página. Padrão: 20. Mínimo: 1, Máximo: 100. "page": 1 // Página desejada } ``` **Corpo de resposta — `200 OK`:** ```json5 { "current_page": 1, "data": [ { "id": "0190a1b2-7b31-7c4e-9a1d-2f3b4c5d6e7f", // user_id da conta filha (use em X-On-Behalf-Of) "name": "Cliente A", // Nome da conta "email": "clientea@exemplo.com", // E-mail da conta "active": true, // Somente contas ativas são listadas "created_at": "2026-07-01T12:00:00-03:00" // Data de criação } ], "first_page_url": "https://web.smsfunnel.com.br/api/parceiros/v1/accounts?page=1", "from": 1, "next_page_url": null, "path": "https://web.smsfunnel.com.br/api/parceiros/v1/accounts", "per_page": 20, "prev_page_url": null, "to": 1 } ``` {% hint style="info" %} 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`. {% endhint %} *** **GET**** /accounts/{id}** **Função:** Obtém os detalhes de uma conta filha específica. **Corpo de resposta — `200 OK`:** ```json5 { "id": "0190a1b2-7b31-7c4e-9a1d-2f3b4c5d6e7f", "name": "Cliente A", "email": "clientea@exemplo.com", "active": true, "created_at": "2026-07-01T12:00:00-03:00" } ``` {% hint style="warning" %} 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. {% endhint %} *** #### 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:** ```json5 // GET /lists { "Authorization": "Bearer {CHAVE_DA_AGENCIA}", "X-On-Behalf-Of": "0190a1b2-7b31-7c4e-9a1d-2f3b4c5d6e7f", "Accept": "application/json" } // Resposta: 200 OK // X-Effective-Account: 0190a1b2-7b31-7c4e-9a1d-2f3b4c5d6e7f ``` **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`. {% hint style="success" %} **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. {% endhint %} {% hint style="info" %} **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. {% endhint %} *** #### 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. {% hint style="warning" %} 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. {% endhint %} *** #### 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:** ```json5 { "error": { "code": "ON_BEHALF_NOT_ALLOWED", // Código do erro "message": "Only agency accounts can act on behalf of managed accounts." // Descrição } } ``` **Dúvidas?** Em caso de dúvidas, entre em contato com nosso suporte.