Paginação e filtros
Como percorrer as listas da API aberta da Astrify Flows com limit e offset e quais filtros cada listagem aceita.
As listagens que podem crescer muito são paginadas por limit (quantos itens por página) e offset (quantos itens pular). O padrão e o máximo de limit mudam de rota para rota:
| Rota | limit padrão |
limit máximo |
offset |
O que a resposta traz |
|---|---|---|---|---|
GET /v1/leads?view=list |
30 | 100 | sim | leads e total |
GET /v1/contatos |
50 | 100 | sim | contatos, total e has_more |
GET /v1/conversas |
50 | 100 | sim | conversas, limit e offset |
GET /v1/conversas/{conversa_id}/mensagens |
50 | 200 | sim | mensagens, da mais nova para a mais antiga |
GET /v1/campanhas |
50 | 100 | não | campanhas, das mais novas para as mais antigas |
GET /v1/workflows/{workflow_id}/execucoes |
50 | 100 | não | execucoes, das mais novas para as mais antigas |
Um limit acima do máximo é reduzido ao máximo. Para as demais listagens, confira os parâmetros de cada rota na Referência da API.
Como percorrer uma lista
Peça limit=100&offset=0, depois offset=100, offset=200… e pare quando has_more for false, quando offset passar de total, ou quando vier menos itens que o limit.
import os, requests
BASE = "https://api2.astrify.com.br"H = {"Authorization": f"Bearer {os.environ['ASTRIFY_API_KEY']}"}
def todos_os_contatos(): offset = 0 while True: r = requests.get(f"{BASE}/v1/contatos", headers=H, params={"limit": 100, "offset": offset}, timeout=20) r.raise_for_status() pagina = r.json() yield from pagina["contatos"] if not pagina.get("has_more"): break offset += 100Filtros
Os filtros vão na query string. Os que cada rota aceita:
| Rota | Filtros |
|---|---|
GET /v1/leads |
view, funil_id, etapa_id, status, temperatura, origem, responsavel_id, valor_min, valor_max, data_inicio, data_fim, tags, contato_id, search, ids |
GET /v1/contatos |
busca, etiqueta, carteira |
GET /v1/conversas |
status, atendente_id, instancia_id, canal |
GET /v1/campanhas |
status |
Os valores aceitos por cada filtro e os de outras rotas estão na Referência da API.
Formatos
- WhatsApp: só dígitos, com o código do país (ex.:
5511900000000). - Datas:
AAAA-MM-DDou ISO 8601 em UTC. - Valores: número (
4500.00). - Ids de funil, etapa, responsável, contato e equipe sempre da sua empresa. Liste antes (
GET /v1/funiseGET /v1/funis/{funil_id}/etapas) e guarde os ids.