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

# Listas

As **Listas** permitem agrupar e gerenciar seus leads. Através destes endpoints você pode criar listas, consultar, atualizar, remover e gerenciar os leads contidos em cada uma delas.

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

{% hint style="info" %}
Os endpoints de listagem utilizam **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;/lists**

**Função:** Lista todas as suas listas, 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": "018f8e2a-1c4d-7a3b-9e21-3f6a2b8c1d0e", // ID da lista
            "name": "Black Friday VIP", // Nome da lista
            "leads_count": 1280, // Quantidade de leads na lista
            "campaigns_count": 2, // Quantidade de campanhas que utilizam a lista
            "created_at": "2026-06-29T14:03:11+00:00", // Data de criação
            "updated_at": "2026-06-29T14:03:11+00:00" // Data da última atualização
        }
    ],
    "first_page_url": "https://web.smsfunnel.com.br/api/parceiros/v1/lists?page=1",
    "from": 1,
    "next_page_url": "https://web.smsfunnel.com.br/api/parceiros/v1/lists?page=2",
    "path": "https://web.smsfunnel.com.br/api/parceiros/v1/lists",
    "per_page": 20,
    "prev_page_url": null,
    "to": 20
}
```

***

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

**Função:** Cria uma nova lista.

**Corpo de envio:**

```json5
{
    "name": "Black Friday VIP" // Obrigatório. String de 1 a 100 caracteres.
}
```

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

```json5
{
    "id": "018f8e2a-1c4d-7a3b-9e21-3f6a2b8c1d0e", // ID da lista criada
    "name": "Black Friday VIP",
    "leads_count": 0,
    "campaigns_count": 0,
    "created_at": "2026-06-30T12:00:00+00:00",
    "updated_at": "2026-06-30T12:00:00+00:00"
}
```

***

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

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

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

```json5
{
    "id": "018f8e2a-1c4d-7a3b-9e21-3f6a2b8c1d0e",
    "name": "Black Friday VIP",
    "leads_count": 1280,
    "campaigns_count": 2,
    "created_at": "2026-06-29T14:03:11+00:00",
    "updated_at": "2026-06-29T14:03:11+00:00"
}
```

***

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

**Função:** Atualiza (renomeia) uma lista existente.

**Corpo de envio:**

```json5
{
    "name": "Black Friday VIP 2026" // Opcional. Se informado, deve ter de 1 a 100 caracteres.
}
```

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

```json5
{
    "id": "018f8e2a-1c4d-7a3b-9e21-3f6a2b8c1d0e",
    "name": "Black Friday VIP 2026",
    "leads_count": 1280,
    "campaigns_count": 2,
    "created_at": "2026-06-29T14:03:11+00:00",
    "updated_at": "2026-06-30T12:05:00+00:00"
}
```

***

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

**Função:** Remove uma lista.

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

{% hint style="warning" %}
Não é possível remover uma lista que ainda possua **campanhas vinculadas** a ela. Nesse caso, a resposta será `409 Conflict` com o código `LIST_HAS_DEPENDENT_CAMPAIGNS` e a lista das campanhas dependentes em `details.dependent_campaigns`.
{% endhint %}

***

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

**Função:** Lista os leads contidos em uma lista, do mais recente para o mais antigo.

**Parâmetros de query (opcionais):**

```json5
{
    "per_page": 50, // Itens por página. Padrão: 50. Mínimo: 1, Máximo: 200.
    "page": 1 // Página desejada
}
```

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

```json5
{
    "current_page": 1,
    "data": [
        {
            "id": "018f8e2a-9a1b-7c2d-8e3f-aa11bb22cc33", // ID do lead
            "phone": "5511999998888", // Telefone (apenas dígitos)
            "name": "Maria Silva", // Nome do lead
            "email": "maria@example.com", // E-mail (pode ser nulo)
            "custom_fields": ["Sao Paulo", "premium"], // Campos personalizados (até 3)
            "blacklisted": false, // Indica se o número está na blacklist
            "created_at": "2026-06-29T14:05:00+00:00" // Data de criação
        }
    ],
    "first_page_url": "https://web.smsfunnel.com.br/api/parceiros/v1/lists/018f8e2a-1c4d-7a3b-9e21-3f6a2b8c1d0e/leads?page=1",
    "from": 1,
    "next_page_url": null,
    "path": "https://web.smsfunnel.com.br/api/parceiros/v1/lists/018f8e2a-1c4d-7a3b-9e21-3f6a2b8c1d0e/leads",
    "per_page": 50,
    "prev_page_url": null,
    "to": 1
}
```

***

<mark style="color:green;">**POST**</mark>**&#x20;/lists/{id}/leads**

**Função:** Insere um lote de leads na lista. Leads aceitos (não pertencentes à blacklist) acionam automaticamente as campanhas/sequências ativas vinculadas à lista.

**Corpo de envio:**

```json5
{
    "leads": [ // Obrigatório. Lista de 1 a 500 leads.
        {
            "phone": "5511999998888", // Obrigatório. 10 a 15 dígitos, com DDI/DDD (aceita "+" inicial).
            "name": "Maria Silva", // Obrigatório. Até 150 caracteres.
            "email": "maria@example.com", // Opcional. E-mail válido, até 150 caracteres.
            "custom_fields": ["Sao Paulo", "premium"] // Opcional. Até 3 valores, até 255 caracteres cada.
        }
    ]
}
```

{% hint style="info" %}
**Idempotência (opcional):** envie o header `Idempotency-Key` (máx. 80 caracteres) para evitar inserções duplicadas. Se recebermos a mesma chave para a mesma lista em até **24 horas**, retornamos a resposta original sem reprocessar, incluindo o header `Idempotency-Replayed: true`.
{% endhint %}

**Corpo de resposta — `202 Accepted`:**

```json5
{
    "accepted_count": 2, // Leads aceitos e enfileirados
    "blacklisted_count": 1, // Leads inseridos, porém na blacklist (não disparam sequências)
    "leads": [
        { "lead_id": "018f8e2a-...-1", "status": "accepted", "blacklisted": false },
        { "lead_id": "018f8e2a-...-2", "status": "accepted", "blacklisted": false },
        { "lead_id": "018f8e2a-...-3", "status": "blacklisted", "blacklisted": true }
    ]
}
```

***

<mark style="color:red;">**DELETE**</mark>**&#x20;/lists/{id}/leads/{lead\_id}**

**Função:** Remove um lead específico de uma lista.

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

***

### 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 lista (ou o lead) não foi encontrada ou não pertence à sua conta.
* `409 Conflict` (`LIST_HAS_DEPENDENT_CAMPAIGNS`): Tentativa de remover uma lista com campanhas vinculadas.
* `409 Conflict` (`CONCURRENT_REQUEST`): Já existe uma requisição em processamento com o mesmo `Idempotency-Key`.
* `422 Unprocessable Entity` (`VALIDATION_ERROR`): Algum campo do corpo da requisição é inválido.

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