> 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/campanhas.md).

# Campanhas

As **Campanhas** definem fluxos automatizados de mensagens (sequências) disparados aos leads de uma lista. Através destes endpoints você pode criar, consultar, atualizar e remover suas campanhas.

{% hint style="success" %}
**A URL de base de todos os endpoints é**: <https://web.smsfunnel.com.br/api/parceiros/v1>
{% 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 %}

***

### Endpoints

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

**Função:** Lista todas as suas campanhas, da mais recente para a mais antiga.

**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": "018f9c2a-7b31-7c4e-9a1d-2f3b4c5d6e7f", // ID da campanha
            "name": "Black Friday", // Nome da campanha
            "active": true, // Indica se a campanha está ativa
            "lead_list_id": "018f9c2a-1111-7c4e-9a1d-aaaabbbbcccc", // ID da lista vinculada
            "created_at": "2026-06-30T14:05:00+00:00", // Data de criação
            "updated_at": "2026-06-30T14:05:00+00:00" // Data da última atualização
        }
    ],
    "first_page_url": "https://web.smsfunnel.com.br/api/parceiros/v1/sms/campaigns?page=1",
    "from": 1,
    "next_page_url": null,
    "path": "https://web.smsfunnel.com.br/api/parceiros/v1/sms/campaigns",
    "per_page": 20,
    "prev_page_url": null,
    "to": 1
}
```

{% hint style="info" %}
A listagem **não** retorna o detalhamento das sequências. Para obter as sequências de uma campanha, utilize o endpoint de consulta individual (`GET /sms/campaigns/{id}`).
{% endhint %}

***

<mark style="color:green;">**POST**</mark>**&#x20;/sms/campaigns**

**Função:** Cria uma nova campanha. Caso não informe `lead_list_id`, uma lista própria será criada e vinculada automaticamente. As sequências podem ser criadas junto, no mesmo corpo da requisição.

**Corpo de envio:**

```json5
{
    "name": "Black Friday", // Obrigatório. String de 1 a 50 caracteres.
    "active": true, // Opcional. Padrão: true.
    "lead_list_id": "018f9c2a-1111-7c4e-9a1d-aaaabbbbcccc", // Opcional. ID de uma lista sua. Se omitido, criamos uma lista automaticamente.
    "sequences": [ // Opcional. Até 50 sequências.
        {
            "interval": 1, // Obrigatório (se houver sequências). Inteiro >= 1.
            "interval_type_id": 3, // Obrigatório. 1=Minuto, 2=Hora, 3=Dia, 4=Semana, 5=Mês.
            "text": "Ola {first_name}, confira {meu_link}", // Obrigatório. 1 a 1530 caracteres.
            "active": true, // Opcional. Padrão: true.
            "url": "https://example.com/promo" // Opcional. Obrigatório quando o texto contém {meu_link}.
        }
    ]
}
```

{% hint style="warning" %}
Quando o texto de uma sequência contém a variável `{meu_link}`, o campo `url` é **obrigatório** naquela sequência (e vice-versa). Nós encurtamos o link automaticamente e o retornamos em `short_url`.
{% endhint %}

**Corpo de resposta — `201 Created`:**

```json5
{
    "id": "018f9c2a-7b31-7c4e-9a1d-2f3b4c5d6e7f",
    "name": "Black Friday",
    "active": true,
    "lead_list_id": "018f9c2a-1111-7c4e-9a1d-aaaabbbbcccc",
    "created_at": "2026-06-30T14:05:00+00:00",
    "updated_at": "2026-06-30T14:05:00+00:00",
    "sequences": [
        {
            "id": "018f9c2a-9999-7c4e-9a1d-1234567890ab", // ID da sequência
            "campaign_id": "018f9c2a-7b31-7c4e-9a1d-2f3b4c5d6e7f", // ID da campanha
            "interval": 1, // Intervalo
            "interval_type_id": 3, // Tipo de intervalo (3 = Dia)
            "position": 1, // Posição na sequência
            "text": "Ola {first_name}, confira {meu_link}", // Texto da mensagem
            "active": true, // Sequência ativa
            "url": "https://example.com/promo", // Link "Meu Link" (ou nulo)
            "short_url": "https://go.site/abc123", // Link encurtado (ou nulo)
            "created_at": "2026-06-30T14:05:00+00:00",
            "updated_at": "2026-06-30T14:05:00+00:00"
        }
    ]
}
```

***

<mark style="color:green;">**GET**</mark>**&#x20;/sms/campaigns/{id}**

**Função:** Obtém os detalhes de uma campanha específica, incluindo suas sequências.

**Corpo de resposta — `200 OK`:**

```json5
{
    "id": "018f9c2a-7b31-7c4e-9a1d-2f3b4c5d6e7f",
    "name": "Black Friday",
    "active": true,
    "lead_list_id": "018f9c2a-1111-7c4e-9a1d-aaaabbbbcccc",
    "created_at": "2026-06-30T14:05:00+00:00",
    "updated_at": "2026-06-30T14:05:00+00:00",
    "sequences": [
        {
            "id": "018f9c2a-9999-7c4e-9a1d-1234567890ab",
            "campaign_id": "018f9c2a-7b31-7c4e-9a1d-2f3b4c5d6e7f",
            "interval": 1,
            "interval_type_id": 3,
            "position": 1,
            "text": "Ola {first_name}, confira {meu_link}",
            "active": true,
            "url": "https://example.com/promo",
            "short_url": "https://go.site/abc123",
            "created_at": "2026-06-30T14:05:00+00:00",
            "updated_at": "2026-06-30T14:05:00+00:00"
        }
    ]
}
```

***

<mark style="color:blue;">**PUT**</mark>**&#x20;/sms/campaigns/{id}**

**Função:** Atualiza uma campanha. Apenas os campos `name` e `active` podem ser alterados.

**Corpo de envio:**

```json5
{
    "name": "Black Friday 2026", // Opcional. Se informado, 1 a 50 caracteres.
    "active": false // Opcional. Boolean.
}
```

{% hint style="warning" %}
Os campos `lead_list_id` e `sequences` **não** podem ser enviados neste endpoint — o envio retornará `422 VALIDATION_ERROR`. A lista e as sequências são definidas apenas na criação da campanha.
{% endhint %}

**Corpo de resposta — `200 OK`:** mesmo formato do `GET /sms/campaigns/{id}`.

***

<mark style="color:red;">**DELETE**</mark>**&#x20;/sms/campaigns/{id}**

**Função:** Remove uma campanha. As sequências vinculadas são removidas automaticamente em cascata.

**Corpo de resposta:** `204 No Content` (sem corpo).

***

### Tabela de tipos de intervalo

| `interval_type_id` | Tipo   |
| ------------------ | ------ |
| 1                  | Minuto |
| 2                  | Hora   |
| 3                  | Dia    |
| 4                  | Semana |
| 5                  | Mês    |

***

### Código de Erros Comuns

* `401 Unauthorized` (`UNAUTHORIZED`): Não foi possível identificar o parceiro a partir da Chave de API.
* `404 Not Found` (`NOT_FOUND`): A campanha (ou a lista informada em `lead_list_id`) não foi encontrada ou não pertence à sua conta.
* `422 Unprocessable Entity` (`VALIDATION_ERROR`): Algum campo do corpo da requisição é inválido (inclui enviar `lead_list_id`/`sequences` no `PUT`, ou `{meu_link}` sem `url`).
* `500 Internal Server Error` (`INTERNAL_ERROR`): Ocorreu um erro interno ao processar a requisição.

**Corpo de resposta de erro:**

```json5
{
    "error": {
        "code": "VALIDATION_ERROR", // Código do erro
        "message": "The given data was invalid.", // Descrição
        "details": { // Opcional: detalhes por campo (presente em erros de validação)
            "name": [
                "Field `name` is required."
            ]
        }
    }
}
```

#### Dúvidas?

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