> 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

Nesta página estão os endpoints de **consulta da conta** (`/me`, `/recharges`, `/sent-messages`, `/credits` e `/clicks`) e de **blacklist** (`/phones-blacklist`). 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 é**: <https://web.smsfunnel.com.br/api/parceiros/v1>
{% 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, para chaves de **conta agência**, uma **conta filha ativa** vinculada a ela. 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. O `email` precisa ser um endereço válido com domínio existente, e o `user_id` precisa ser um UUID. Caso contrário, a resposta é `422`.
7. Agências também podem usar o header `X-On-Behalf-Of` (veja Agências) em vez de `email`/`user_id`. Se o header e o corpo apontarem para contas diferentes, a resposta é `400`.
8. Os parâmetros podem ser enviados na **query string** (`?email=...&from_date=...`) ou no **corpo JSON** da requisição — inclusive nos verbos `GET`.
9. 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, ou o header `X-On-Behalf-Of` e o corpo apontam para contas diferentes.
* `401 Unauthorized`: O header `Authorization` está ausente ou malformado (deve ser `Bearer SUA_CHAVE_DE_API`).
* `403 Forbidden`: Sua Chave de API é inválida ou expirou, seu usuário está inativo ou não tem a API de Parceiros habilitada.
* `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" 
}
```

{% hint style="info" %}
Os erros de autenticação têm formato próprio: o `401` responde `{"status": "Authorization header is missing or malformed"}` e o `403` responde apenas o texto `Forbidden` (sem JSON).
{% endhint %}

***

#### Endpoints

<mark style="color:green;">**GET**</mark>**&#x20;/me**

**Função:** Retorna os dados da conta autenticada e o seu saldo. Útil para validar a Chave de API e exibir "Minha conta" na sua integração.

Não recebe parâmetros. A conta é sempre a dona do token — ou a conta filha informada em `X-On-Behalf-Of`, para agências. Este endpoint respeita o limite de requisições da API.

**Corpo de resposta:**

```json5
{
    "user_id": "9fe358e0-5ffa-4aee-90f4-c010eef2aede", // ID da conta
    "name": "Minha Empresa", // Nome da conta
    "email": "contato@minhaempresa.com", // E-mail da conta
    "credits": { // Mesmo conteúdo do GET /credits
        "wallet": { "billed": ["whatsapp", "ai"], "currency": "BRL", "available": "150.00" },
        "sms": { "contracted": 2000, "sent": 766, "available": 1234 },
        "call": { "contracted": 0, "sent": 0, "available": 0 }
    }
}
```

***

<mark style="color:green;">**GET**</mark>**&#x20;/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 de confirmação da recarga
            "description": "Recarga Direta", // Descrição
            "service": "SMS", // Serviço: "SMS", "WhatsApp" ou "Ligação"
            "credits": 1000, // Quantidade de créditos recarregados (0 em recargas por valor na Carteira)
            "price": "0.05000", // Preço unitário (string, para preservar a precisão)
            "total": "50.00000", // Valor pago (string, para preservar a precisão)
            "situation": "APPROVED", // Situação (somente recargas confirmadas são listadas)
            "invoice_url": null // Link da nota fiscal, quando disponível
        }, ...
    ]
}
```

{% hint style="info" %}
Recargas feitas **por valor** na Carteira aparecem com `"credits": 0` — o valor creditado é o `total`, em reais. Veja Saldo e Carteira.
{% endhint %}

***

<mark style="color:green;">**GET**</mark>**&#x20;/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
}
```

***

<mark style="color:green;">**GET**</mark>**&#x20;/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" 
}
```

{% hint style="warning" %}
**O formato desta resposta mudou com a Carteira.** Quando algum canal da conta é cobrado pela Carteira (saldo em R$), a resposta passa a ter o bloco `wallet` como primeira chave, os canais migrados ganham `deprecated: true` e o bloco `whatsapp` deixa de ser devolvido. Veja todos os detalhes em **Saldo e Carteira**.
{% endhint %}

**Corpo de resposta — conta com a Carteira:**

```json5
{
    "wallet": {
        "billed": ["sms", "call", "whatsapp", "ai"], // Canais cobrados pela Carteira
        "currency": "BRL",
        "available": "4000.00" // Saldo em reais (string). null = consulta indisponível no momento
    },
    "sms": {
        "contracted": 10500, // Histórico do pacote de créditos
        "sent": 3200, // Histórico do pacote de créditos
        "available": 50000, // Estimativa de SMS que cabem no saldo da Carteira
        "deprecated": true // Canal cobrado pela Carteira — use "wallet"
    },
    "call": {
        "contracted": 0,
        "sent": 0,
        "available": 1428, // Estimativa de ligações de até 30s que cabem no saldo
        "deprecated": true
    }
}
```

**Corpo de resposta — conta sem nenhum canal na Carteira (formato antigo):**

```json5
{
    "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
    }
}
```

***

<mark style="color:green;">**GET**</mark>**&#x20;/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` aparecem quando a conta possui campanhas ou broadcasts, e podem vir vazias (`[]`) quando não houve envios no período. Os totais `sms`, `whatsapp` e `clicks` da raiz são sempre da conta inteira no período, mesmo quando você informa `id`. O `id` precisa ser de uma campanha ou broadcast da conta consultada; um `id` que não existe ou não pertence à conta devolve `campaigns` e `broadcasts` vazios.

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 que não saíram (número inválido, blacklist, cancelamento ou saldo insuficiente)
            "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"
        }
    ]
}
```

***

<mark style="color:green;">**GET**</mark>**&#x20;/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
}
```

***

<mark style="color:green;">**POST**</mark>**&#x20;/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
}
```

Cada telefone é reduzido aos dígitos; o que fica com menos de 8 dígitos é descartado sem erro. Número que já estava na blacklist não é duplicado. `phones_count` conta os números válidos recebidos (sem repetição), **não** quantos eram novos.

***

<mark style="color:red;">**DELETE**</mark>**&#x20;/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
}
```

A remoção compara os dígitos exatos. `phones_removed` conta os números válidos recebidos, **não** quantos estavam de fato na lista.

***

**Perguntas frequentes**

**Minha conta é cobrada pela Carteira. Onde vejo o saldo?**\
Em `GET /credits` (ou no campo `credits` do `GET /me`), no bloco `wallet`. Veja Saldo e Carteira.

**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.

***
