workflows

Token de sincronização inválido: reconstrua a cópia antes de agir

Diferencie token de estado e acesso, faça a carga completa exigida pelo fornecedor e concilie a cópia local antes de liberar avisos ou atualizações.

Quando a API rejeita um token de sincronização incremental, repetir a mesma consulta pode manter uma cópia local desatualizada. Primeiro descubra se o erro é do token que marca o estado das mudanças ou da autenticação. Só depois reconstrua o espelho conforme o contrato do fornecedor e volte a acionar outros sistemas.

Resposta curta

Na API do Google Agenda, um 410 em uma consulta incremental pode indicar syncToken inválido. A documentação pede uma nova sincronização completa e substituição do estado local. O Microsoft Graph também prevê reset de consulta delta, inclusive 410 Gone ou erro de token expirado. Isso não é a mesma coisa que renovar um token OAuth. Antes de enviar lembretes, remover registros ou atualizar o CRM a partir da cópia, conclua a carga e reconcilie IDs, exclusões e alterações.

Protocolo em quatro etapas para o espelho

Fase Ação Condição para avançar
1. Conter Pause efeitos baseados no espelho; registre provedor, coleção, erro e último checkpoint sem guardar o token em texto aberto O erro foi identificado como token de estado, não de autenticação
2. Reconstruir Preserve uma evidência limitada do estado local; faça leitura completa em cópia de trabalho, cobrindo todas as páginas A fonte retornou o marcador de conclusão, como nextSyncToken ou deltaLink
3. Conciliar Compare IDs e estados; trate exclusões e entradas restauradas conforme o provedor Diferenças materiais têm explicação ou responsável
4. Liberar Substitua o espelho local conforme o método da integração e só então retome efeitos Teste de amostra e contagem de controle coerentes

Esta tabela é uma síntese operacional da Pulse, não uma sequência executada pela equipe nem uma instrução para apagar dados do fornecedor. “Limpar armazenamento do cliente” na documentação Google refere-se à cópia do aplicativo: não exclua eventos da agenda de origem. Se o espelho contém notas próprias, preserve-as separadamente antes de reconstruir.

O que conferir no retorno

O Google informa que nextSyncToken aparece apenas na última página da carga inicial. Durante atualização incremental paginada, mantenha os parâmetros compatíveis e percorra as páginas até receber o novo token. O Graph diferencia @odata.nextLink de @odata.deltaLink, admite mudanças repetidas e representa remoções com @removed nos recursos compatíveis. Não trate a primeira página nem a ausência temporária de uma entrada como prova de exclusão.

Em uma pequena clínica brasileira, por exemplo, um espelho de compromissos alimenta lembretes. Se a atualização incremental falha, a equipe suspende os lembretes baseados naquele espelho, reconstrói a cópia local e compara os IDs antes de reativar o fluxo. O exemplo é ilustrativo; não afirma integração testada, regra de prontuário nem política de retenção.

Quando interromper e pedir revisão humana

Pare se não souber qual coleção o token representa, se a carga completa não terminar, se os parâmetros mudaram, se exclusões não puderem ser distinguidas de falhas de leitura ou se o espelho guarda dados próprios que seriam perdidos. Não use o mesmo procedimento para erro 401 de acesso; verifique a conexão nesse caso. Para a nova carga, confira todas as páginas. Se o fluxo já deixou registros de fora, rastreie a lacuna.

Fontes