Ctrlk
For the complete documentation index, see llms.txt. This page is also available as Markdown.

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

A URL de base de todos os endpoints é: https://web.smsfunnel.com.br/api/parceiros/v1

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.

Endpoints

GET /lists

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

Parâmetros de query (opcionais):

{
    "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:

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

POST /lists

Função: Cria uma nova lista.

Corpo de envio:

Corpo de resposta — 201 Created:

GET /lists/{id}

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

Corpo de resposta — 200 OK:

PUT /lists/{id}

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

Corpo de envio:

Corpo de resposta — 200 OK:

DELETE /lists/{id}

Função: Remove uma lista.

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

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.

GET /lists/{id}/leads

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

Parâmetros de query (opcionais):

Corpo de resposta — 200 OK:

POST /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:

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.

Corpo de resposta — 202 Accepted:

DELETE /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:

Dúvidas?

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

PreviousQuickstartNextCampanhas

Last updated