Paginação

Como paginar listagens da API externa e os dois formatos de resposta em uso.

Todos os endpoints de listagem (GET) aceitam paginação por page e limit. Use-os para percorrer grandes volumes de dados em lotes.

Parâmetros de query

Query params
pagenumberopcionalpadrão 1

Número da página, começando em 1.

limitnumberopcionalpadrão 20 ou 50

Itens por página. O padrão varia por recurso — 20 na maioria, 50 em mensagens e logs — e o máximo é 100.

sortOrderstringopcionalpadrão desc

Ordenação, quando suportada. Disponível, por exemplo, em mensagens de uma conversa.

valoresascdesc

Limite máximo

O limit é limitado a 100 nos endpoints que aplicam esse teto. Valores acima são reduzidos para 100. Para volumes maiores, percorra várias páginas.

Formatos de resposta

Por evolução histórica, a API tem dois formatos de resposta paginada. Ambos trazem os mesmos dados — muda apenas onde a lista e os contadores ficam.

Formato 1 — envelope data + pagination

A lista vem em data e os contadores em um objeto pagination. Usado pelas listagens de e-mail (templates e campanhas).

Formato 1
{
  "success": true,
  "data": [
    { "id": "tpl_email_123", "name": "Boas-vindas" }
  ],
  "pagination": {
    "page": 1,
    "limit": 20,
    "total": 1,
    "totalPages": 1
  }
}

Formato 2 — chave nomeada com contadores no mesmo nível

A lista vem em uma chave com o nome do recurso — conversations, flows, messages — e os contadores total, page e totalPages ficam ao lado dela, dentro de data. Usado por conversas, mensagens e flows.

Formato 2
{
  "success": true,
  "data": {
    "conversations": [
      { "id": "conv_...", "phoneNumber": "5511999999999" }
    ],
    "total": 1,
    "page": 1,
    "totalPages": 1
  }
}

Confira o formato do recurso

Antes de consumir uma listagem, verifique na página do recurso qual formato ela retorna. A chave da lista (data, conversations, flows, templates, campaigns) e a localização dos contadores mudam entre os dois formatos.

Como percorrer todas as páginas

  1. Comece com page=1.
  2. Leia totalPages, ou compare page * limit com total.
  3. Incremente page até alcançar totalPages.
cURL
curl -X GET "https://external-api.lip7.com.br/api/external/conversations?page=2&limit=50" \
  -H "x-api-key: lip_SUA_CHAVE"