workflows

API paginada: confira o lote antes de ações em massa

Uma resposta com sucesso pode trazer só parte dos registros. Use o próximo cursor, confira a cobertura e só então libere ações sobre o lote.

Uma execução verde não prova que a lista da API veio inteira. Algumas APIs devolvem somente a primeira página; outras entregam um cursor ou link de continuação. Se a automação trata a primeira resposta como o lote completo, pode deixar cobranças, pedidos ou chamados fora da conferência.

Resposta curta

Leia a regra de paginação do endpoint, percorra as páginas até o sinal oficial de término, registre quantas páginas e IDs únicos foram lidos e compare a cobertura com um total ou intervalo confiável quando disponível. Para ações em massa, só libere efeitos externos depois dessa conferência. O processamento independente de cada item pode ser seguro com ID estável, proteção contra repetição e aprovação definida. Se a API mudou durante a leitura ou o cursor falhou, marque o lote como incompleto e reconcilie; não invente o que faltou.

Descubra o contrato antes de montar o laço

Confira na documentação do fornecedor: tamanho máximo da página, ordenação, campo next/cursor ou número de página, indicação de última página, limite de requisições e validade do cursor. O Asaas documenta como a ausência de paginação pode ocultar registros de uma listagem. Isso é um exemplo brasileiro, não uma regra universal de API.

No Dataverse, a Microsoft distingue a paginação automática do uso explícito de @odata.nextLink. O comportamento depende das configurações; ativar uma opção não dispensa conferir o que a resposta realmente contém. A Zendesk explica diferenças entre paginação por deslocamento e por cursor. Escolha o mecanismo do endpoint, sem trocar um pelo outro por suposição.

Matriz de cobertura do lote

Evidência ao final da leitura Decisão Motivo
Sinal de término oficial, IDs únicos e total compatível quando houver Liberar a etapa seguinte conforme as aprovações do processo Há evidência de cobertura para o recorte consultado
Ainda existe próximo cursor ou página Continuar a leitura dentro dos limites A resposta atual é parcial
Cursor repetido, expirado ou erro no meio Parar, guardar ponto de controle e reconciliar Repetir sem controle pode omitir ou duplicar
Total informado diverge dos IDs únicos Investigar filtros, mudanças simultâneas e duplicatas Contagem de páginas não prova completude
A API não informa total nem snapshot estável Reter efeitos irreversíveis em massa; processar por item só com ID estável, proteção contra repetição e aprovação definida A última resposta não comprova cobertura perfeita; registre a limitação e reconcilie IDs/intervalo em outra leitura autorizada

Ativo original da Pulse: para cada lote, anote fonte | filtro e intervalo | página/cursor | primeiro e último ID | IDs únicos acumulados | próximo cursor | estado | responsável. Não inclua tokens de acesso nem dados pessoais na planilha de controle. Este é um modelo editorial, não resultado de um teste realizado pela Pulse.

Exemplo hipotético

Uma loja consulta pedidos alterados ontem. A primeira resposta contém 50 IDs e um next não vazio; o fluxo marca “concluído” e envia o relatório. Pela matriz, a decisão correta é não liberar: a leitura ainda não terminou. Na página seguinte, o cursor se repete. A equipe interrompe o lote, consulta o estado do endpoint e compara os IDs já obtidos antes de retomar. O exemplo é fictício; o número 50 ilustra uma página, não um limite de fornecedor.

Antes de usar a lista para agir

Mantenha a mesma ordenação e filtros entre páginas. Defina limite de páginas/tempo e um dono para o caso de interrupção. Se os dados mudam durante a varredura, prefira o mecanismo de snapshot ou cursor previsto pelo fornecedor; sem isso, trate a cobertura como aproximada e faça reconciliação posterior. Deduplique por ID estável antes de criar efeitos. A Zapier observa que certos resultados de testes e menus podem mostrar só uma parte dos registros; não confunda essa interface com prova da lista completa.

Pare antes de atualizar ou notificar clientes se a cobertura não foi confirmada, o cursor falhou, o limite de chamadas foi atingido ou o destino pode ter recebido parte das ações. Se a automação está ativa mas faltam registros, use o rastreamento da lacuna. Para HTTP 429, siga a decisão de espera e retomada. Se houve efeitos parciais, use o plano de contingência antes de reprocessar.

Fontes