> 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/requisicoes.md). # Requisições Utilização de cada endpoint e padrões de requisição Contamos atualmente com 4 endpoints de consulta e 3 de blacklist em nossa API de Parceiros, aprenda a seguir como utilizá-los da maneira correta e a função de cada um. {% hint style="success" %} **A URL de base de todos os endpoints é**: {% endhint %} #### Padrão de corpo e regras das requisições 1. **A conta consultada é opcional.** Se você não enviar `email` nem `user_id`, a consulta retorna os dados da **própria conta dona do token**. É o caminho natural para contas do tipo Cliente, que não gerenciam contas filhas e portanto não têm um e-mail de terceiro a informar. 2. **Se você informar a conta**, ela precisa ser o próprio dono do token ou uma **conta filha ativa** dele. Qualquer outra conta responde `404`. Use `user_id` (ID do usuário) **ou** `email` — não envie as duas chaves na mesma requisição; se ambas vierem, o `user_id` prevalece e o `email` é ignorado. 3. **Chave presente e vazia é erro.** Enviar `"email": ""` ou `"user_id": ""` responde `422`. Quem manda a chave quis nomear uma conta — cair silenciosamente na própria conta devolveria dados da conta errada. Para consultar a si mesmo, **omita a chave**. 4. Você só terá acesso às informações da sua conta e dos seus usuários afiliados. 5. As requisições não poderão constar headers como `set-cookie` e afins. 6. Os parâmetros podem ser enviados na **query string** (`?email=...&from_date=...`) ou no **corpo JSON** da requisição — inclusive nos verbos `GET`. 7. O payload não aceita campos além dos documentados em cada endpoint; campos desconhecidos respondem `422`. {% hint style="info" %} **O que mudou:** antes o campo `email` era obrigatório em todas as consultas. Agora ele é opcional. **Quem já envia `email` ou `user_id` não precisa alterar nada** — o comportamento é idêntico ao de antes. A novidade serve para quem consulta a própria conta e não tinha um e-mail de terceiro para informar. {% endhint %} #### Autenticação Todas as requisições exigem o header: ``` Authorization: Bearer SUA_CHAVE_DE_API ``` #### Código de Erros Comuns * `400 Bad Request`: A requisição não pôde ser processada devido a um erro genérico. * `401 Unauthorized`: Sua Chave de API é inválida ou o header `Authorization` está ausente/malformado. * `403 Forbidden`: Seu usuário não tem a API de Parceiros habilitada, está inativo ou sua chave expirou. * `404 Not Found`: O usuário solicitado não foi encontrado, está inativo ou não pertence aos seus afiliados. * `422 Unprocessable Entity`: O payload tem algum problema — campo obrigatório ausente, campo vazio, valor inválido, campo não permitido ou intervalo de datas maior que 90 dias. * `500 Internal Server Error`: Ocorreu um erro interno ao processar a requisição. #### Corpo de Resposta de Erros Comuns ```json { "error": "The error message here" } ``` *** ### Endpoints #### GET /recharges **Função:** Obter dados de recargas do usuário. **Parâmetros:** | Campo | Obrigatório | Descrição | | ----------- | ----------- | -------------------------------------------------------------------------------------------------------- | | `email` | Não | E-mail da conta a consultar. Omita para consultar a própria conta do token. | | `user_id` | Não | ID da conta a consultar. Alternativa ao `email`. | | `from_date` | Não | Data inicial. Se enviada, `to_date` passa a ser obrigatória. | | `to_date` | Não | Data final. Máximo de 90 dias de diferença para `from_date`. Sem datas, o padrão são os últimos 90 dias. | **Corpo de envio — consultando a própria conta:** ```json5 { // Nenhum campo obrigatório: sem email/user_id, a consulta é da própria conta do token. "from_date": "2026-01-01", // Data inicial (Opcional) "to_date": "2026-02-01" // Data final (Opcional) } ``` **Corpo de envio — consultando uma conta filha:** ```json5 { "email": "meu_usuario@example.com", // ou "user_id": "9fe358e0-5ffa-4aee-90f4-c010eef2aede" "from_date": "2026-01-01", "to_date": "2026-02-01" } ``` **Corpo de resposta:** ```json { "recharges": [ { "created_at": "2026-11-21 00:00:00", // Data da recarga "description": "Recarga Direta", // Descrição "service": "SMS", // Serviço "credits": 0, // Quantidade de créditos recarregados "price": 0, // Preço "total": 0, // Valor "situation": "APPROVED" // Situação }, ... ] } ``` *** #### GET /sent-messages **Função:** Obter mensagens enviadas do usuário. **Parâmetros:** os mesmos de `/recharges`. **Corpo de envio — consultando a própria conta:** ```json5 { "from_date": "2026-01-01", // Opcional "to_date": "2026-02-01" // Opcional } ``` Uma requisição **sem nenhum parâmetro** também é válida e retorna os últimos 90 dias da própria conta. **Corpo de envio — consultando uma conta filha:** ```json5 { "email": "meu_usuario@example.com", "from_date": "2026-01-01", "to_date": "2026-02-01" } ``` **Corpo de resposta:** ```json { "sms": 123, // Quantidade de SMS enviados no período "whatsapp": 321, // Quantidade de mensagens WhatsApp enviadas no período "clicks": 10 // Quantidade de clicks nos links no período } ``` *** #### GET /credits **Função:** Obter dados de créditos gerais do usuário. Não aceita filtro de datas — devolve sempre a posição atual. **Parâmetros:** | Campo | Obrigatório | Descrição | | --------- | ----------- | --------------------------------------------------------------------------- | | `email` | Não | E-mail da conta a consultar. Omita para consultar a própria conta do token. | | `user_id` | Não | ID da conta a consultar. Alternativa ao `email`. | **Corpo de envio — consultando a própria conta:** ```json5 { // Corpo vazio, ou nenhum parâmetro na query string. } ``` **Corpo de envio — consultando uma conta filha:** ```json { "email": "meu_usuario@example.com" } ``` **Corpo de resposta:** ```json { "sms": { "contracted": 0, // SMS Contratados "sent": 0, // SMS Enviados "available": 0 // SMS Disponíveis }, "whatsapp": { "contracted": 0, // WhatsApp Contratados "sent": 0, // WhatsApp Enviados "available": 0 // WhatsApp Disponíveis }, "call": { "contracted": 0, // Ligações Contratadas "sent": 0, // Ligações Enviadas "available": 0 // Ligações Disponíveis } } ``` *** #### GET /clicks **Função:** Obter o número de clicks nos envios do usuário. **Parâmetros:** | Campo | Obrigatório | Descrição | | ----------------- | ----------- | ------------------------------------------------------------------------------------- | | `from_date` | **Sim** | Data inicial. | | `to_date` | **Sim** | Data final. Máximo de 90 dias de diferença para `from_date`. | | `email` | Não | E-mail da conta a consultar. Omita para consultar a própria conta do token. | | `user_id` | Não | ID da conta a consultar. Alternativa ao `email`. | | `id` | Não | ID da automação ou do broadcast. Se preenchido, retorna dados apenas do ID informado. | | `include_message` | Não | `true` para incluir o texto das mensagens na resposta. | {% hint style="warning" %} Diferente dos demais endpoints, `from_date` e `to_date` são **obrigatórios** em `/clicks`. Sem eles a resposta é `422`. {% endhint %} {% hint style="info" %} As listas `campaigns` e `broadcasts` só aparecem na resposta quando existem campanhas ou broadcasts no período consultado. Os textos das mensagens (`messages` nas campanhas e `message`, `url`, `short_url` nos broadcasts) só são retornados quando você envia `"include_message": true`. {% endhint %} **Corpo de envio — consultando a própria conta:** {% code fullWidth="false" %} ```json5 { "from_date": "2026-01-01", // Obrigatório "to_date": "2026-02-01" // Obrigatório } ``` {% endcode %} **Corpo de envio — consultando uma conta filha:** ```json5 { "email": "meu_usuario@example.com", // Opcional — omita para consultar a própria conta "id": "id da automação ou id do broadcast", // Opcional "from_date": "2026-01-01", // Obrigatório "to_date": "2026-02-01" // Obrigatório } ``` **Corpo de resposta:** ```json { "sms": 123, // quantidade total de envios de SMS "whatsapp": 321, // quantidade total de envios de mensagem WhatsApp "clicks": 10, // quantidade total de clicks "campaigns": [ { "id": "9fe358e0-5ffa-4aee-90f4-c010eef2aede", // ID da campanha "name": "pix gerado", // nome da campanha de automação "sms": 23, // quantidade de SMS disparados na automação "clicks": 2, // quantidade de clicks da campanha em específico da automação "messages": [ { "text": "Ola {first_name}, seu pix foi gerado. Clique no link para efetuar o pagamento: {url_pix}", "interval": 0, "interval_type": "Minuto(s)", "url": "https://meupix.com/019c7116-3c27-797d-91b3-aa49a5bea42a" }, { "text": "Ola {first_name}, ainda nao identificamos o seu pagamento. Clique no link para o pagamento: {url_pix}", "interval": 5, "interval_type": "Minuto(s)", "url": "https://meupix.com/019c7116-3c27-797d-91b3-aa49a5bea42a" } ] }, { "id": "019c7114-3b02-7d1d-83b9-a8a23052aa37", "name": "cartao pago", "sms": 10, "clicks": 2, "messages": [ { "text": "Ola {first_name}, seu pagamento foi confirmado. Em breve voce recebera o codigo de rastreio", "interval": 0, "interval_type": "Minuto(s)", "url": "https://minhaloja.com/ck=019c7116-3c27-797d-91b3-aa49a5bea42a" } ] } ], "broadcasts": [ { "id": "019c7114-7c4b-77b6-8deb-12cb5c885ea5", // ID do broadcast "name": "promoção Carnaval", // nome da campanha do broadcast "total_leads": 100, // quantidade de leads "sent": 92, // quantidade de envios (subtraindo inválidos - cancelados) "cancelled": 8, // quantidade de envios cancelados (números inválidos) "sent_date": "2026-01-30 15:06:54", // Data/hora do envio "clicks": 54, // quantidade de clicks da campanha em específico do broadcast "message": "Ola {first_name}, aproveite nossa promocao de carnaval. Faca uma compra no link {meu_link} e ganhe 10% OFF", // mensagem enviada, "url": "https://minhaloja.com/ck=019c7116-3c27&c=10OFF", "short_url": "https://gosite.cc/3c2710of" }, { "id": "019c7114-abab-7da9-9a46-4da50bd49147", "name": "aposta tbt", "total_leads": 5800, "sent": 5671, "cancelled": 129, "clicks": 4684, "message": "MINHASORTE: aproveite nossa promocao aposta TBT e faca uma aposta no link {meu_link} e ganhe 10% de cashback", // mensagem enviada, "url": "https://minhaloja.com/?source=sms&p=cash10", "short_url": "https://gosite.cc/3c4810of" } ] } ``` *** #### GET /phones-blacklist Recupera todos os números da blacklist da conta informada — ou **da própria conta do token**, se você não informar `email` nem `user_id`. A paginação é de 1.000 registros por vez. **Parâmetros:** | Campo | Obrigatório | Descrição | | ---------- | ----------- | ------------------------------------------------------------ | | `email` | Não | E-mail da conta. Omita para operar a própria conta do token. | | `user_id` | Não | ID da conta. Alternativa ao `email`. | | `page` | Não | Página desejada. Padrão `1`. | | `per_page` | Não | Registros por página. Padrão `1000`, máximo `5000`. | **Corpo de envio — própria conta:** ```json5 { // Campos opcionais de paginação "page": 1, "per_page": 1000 } ``` **Corpo de envio — conta filha:** ```json { "email": "johndoe@email.com", "page": 1, "per_page": 1000 } ``` **Corpo de resposta:** ```json { "phones": [ "51989261101", "51989261102", "51989261103" ], "total": 6000, "page": 1, "per_page": 3, "total_pages": 2000 } ``` *** #### POST /phones-blacklist Inclusão de telefones na blacklist da conta informada — ou **da própria conta do token**, se você não informar `email` nem `user_id`. Caso o número seja inválido, ele será descartado, não sendo incluído na blacklist. **Parâmetros:** | Campo | Obrigatório | Descrição | | --------- | ----------- | ------------------------------------------------------------ | | `phones` | **Sim** | Array de telefones. | | `email` | Não | E-mail da conta. Omita para operar a própria conta do token. | | `user_id` | Não | ID da conta. Alternativa ao `email`. | **Corpo de envio — própria conta:** ```json { "phones": [ 51989261101, "51989261103" ] } ``` **Corpo de envio — conta filha:** ```json { "email": "johndoe@email.com", "phones": [ 51989261101, "51989261103" ] } ``` **Corpo de resposta:** ```json { "message": "Blacklist atualizada com sucesso", "phones_count": 2 } ``` *** #### DELETE /phones-blacklist Exclusão de telefones da blacklist da conta informada — ou **da própria conta do token**, se você não informar `email` nem `user_id`. **Parâmetros:** os mesmos do `POST /phones-blacklist`. **Corpo de envio — própria conta:** ```json { "phones": [ 51989261101, "51989261103" ] } ``` **Corpo de envio — conta filha:** ```json { "email": "johndoe@email.com", "phones": [ 51989261101, "51989261103" ] } ``` **Corpo de resposta:** ```json { "message": "Números removidos da blacklist com sucesso", "phones_removed": 2 } ``` *** #### Perguntas frequentes **Já uso `email` em todas as chamadas. Preciso mudar alguma coisa?**\ Não. O comportamento de quem envia `email` ou `user_id` é exatamente o mesmo de antes. **Sou uma conta que não gerencia outras contas. O que faço?**\ Simplesmente não envie `email` nem `user_id`. A consulta será da sua própria conta. **Enviei `"email": ""` e recebi `422`. Por quê?**\ Uma chave presente e vazia é tratada como erro, não como "consulta a mim mesmo" — assim uma variável não preenchida na sua integração não vira, sem aviso, uma consulta de outra conta. Para consultar a própria conta, remova a chave do payload. **Posso consultar qualquer conta pelo `email`?**\ Não. A conta indicada precisa ser a sua própria ou uma conta filha ativa sua. Qualquer outra responde `404`. #### Dúvidas? Em caso de dúvidas, entre em contato com nosso suporte. ***