apointoo.
Solicitar acesso
Plataformas de Agendamento

Por que um agendamento recorrente remarcado no Google Calendar mantém o originalStartTime antigo?

cmsapointoo··8 min de leitura

Um agendamento recorrente remarcado mantém o originalStartTime antigo porque esse campo identifica a ocorrência dentro da série, mesmo quando ela muda de horário. O novo horário efetivo fica em start. O campo recurringEventId continua apontando para o evento recorrente que gerou aquela ocorrência.

Não corrija o originalStartTime para igualá-lo ao horário novo. Preserve a identidade original e atualize o estado atual separadamente. Essa distinção permite reconhecer a mesma ocorrência após uma remarcação, sem criar uma duplicata, cancelar a consulta errada ou perder a ligação com a série.

Por que originalStartTime não muda com a remarcação?

A documentação de eventos recorrentes do Google Calendar diz que originalStartTime identifica de forma exclusiva a ocorrência dentro da série, mesmo quando ela foi movida para outro horário. O valor representa onde aquela instância nasceu na regra de recorrência. Ele não é o relógio atual do agendamento.

Essa estabilidade resolve uma pergunta prática: como saber se uma ocorrência movida ainda é a mesma? A resposta não depende apenas do novo início. A integração combina a série indicada por recurringEventId com a posição original indicada por originalStartTime, além do identificador do evento retornado pela API.

Se um sistema substituir a identidade original pelo horário atual, uma nova sincronização pode parecer trazer duas ocorrências. Uma será o registro local remarcado; a outra será a instância reconhecida pelo Google com sua posição original. O erro está no modelo local, não no fato de o campo permanecer antigo.

O problema é diferente do envelope abordado em notificações push do Google Calendar sem detalhes do evento. A notificação apenas inicia a busca. originalStartTime faz parte do evento obtido depois dessa consulta autorizada.

Qual é a diferença entre start, originalStartTime e recurringEventId?

Os três campos respondem a perguntas distintas. start informa quando a ocorrência está marcada agora. originalStartTime informa sua posição de origem na recorrência. recurringEventId informa qual evento recorrente principal gerou a instância.

Campo Pergunta respondida Uso seguro
start Quando a ocorrência acontece agora? Exibição e disponibilidade atuais
originalStartTime Qual posição da série esta ocorrência representa? Identidade estável após uma mudança
recurringEventId De qual série ela veio? Vínculo com o evento recorrente principal

Não use somente start como chave. Duas ocorrências podem trocar de horário, e uma remarcação pode ocupar o início antes associado a outro item. O horário atual é um atributo mutável. A identidade precisa sobreviver à alteração.

Também não use apenas recurringEventId. Todas as instâncias da mesma série compartilham esse vínculo. Sem a posição original ou o identificador específico da ocorrência, o sistema não sabe qual item da série foi alterado.

O que events.list retorna por padrão?

O guia de eventos recorrentes informa que events.list, por padrão, retorna eventos únicos, eventos recorrentes principais e exceções. Ele não expande todas as instâncias que continuam seguindo a regra sem alteração. Essa visão é adequada para sincronizar a definição da série e suas exceções sem materializar cada ocorrência normal.

Uma ocorrência remarcada é uma exceção à regra original. Por isso, a integração pode encontrar o evento principal e o item alterado sem receber uma lista completa de ocorrências normais. O item movido mantém a identidade original, mas seu start representa o horário efetivo.

Quando singleEvents=true, a listagem expande as recorrências em instâncias. O guia também explica que, nessa visão expandida, os eventos recorrentes principais não aparecem. A escolha do parâmetro muda o formato da leitura, não a identidade documentada de cada ocorrência.

Não confunda uma leitura parcial com exclusão. Uma instância normal ausente da resposta padrão pode continuar existindo como parte da série. Da mesma forma, a ausência do evento principal em uma consulta expandida é comportamento da visão solicitada, não prova de que a série foi removida.

Quando usar events.instances?

O método events.instances lista as ocorrências pertencentes a um evento recorrente específico. Ele é útil quando a integração já conhece a série e precisa comparar suas instâncias, inclusive as exceções, dentro do escopo autorizado.

Use o identificador do evento recorrente principal para consultar essa coleção. Depois, associe cada resultado à identidade já armazenada. Uma remarcação deve atualizar o horário atual do registro correspondente, não criar um segundo agendamento só porque start mudou.

A resposta da API continua sendo a fonte para o estado atual. Uma notificação, uma tela em cache ou uma projeção local não substitui a leitura. Se a consulta falhar, mantenha o estado como incerto. Não converta ausência de resposta em horário livre ou cancelamento.

Esse cuidado importa quando a agenda influencia disponibilidade externa. O guia sobre Doctoralia, Feegow e Google Calendar mostra que um link ou uma integração entre dois componentes não cria automaticamente uma sincronização entre todos os calendários envolvidos.

Como modelar uma ocorrência remarcada sem duplicá-la?

Guarde identidade e estado em campos separados. O registro local precisa manter o identificador do evento, o recurringEventId, o originalStartTime e o start atual. Outros campos podem existir conforme o contrato da aplicação, mas nenhum deles deve transformar o horário atual na única chave.

Quando chegar uma atualização, procure primeiro pela identidade estável da ocorrência. Se ela já existir, aplique o novo estado de horário ao mesmo registro. Se não existir, confirme que a leitura inclui a série e a instância corretas antes de criar algo. Uma simples busca por data atual pode não encontrar o item que foi movido.

  1. Correlacione a notificação com a agenda autorizada, quando houver aviso push.
  2. Busque o estado atual pela API com a estratégia de recorrência escolhida.
  3. Associe a ocorrência à série e à posição original.
  4. Atualize start sem substituir originalStartTime.
  5. Recalcule disponibilidade somente após concluir a leitura.
  6. Registre o resultado técnico sem copiar conteúdo de paciente.

Preserve também a origem operacional do agendamento. Remarcar sem apagar a origem original evita que uma mudança de horário pareça uma nova aquisição ou um novo agendamento independente.

Como tratar exceções sem alterar a série inteira?

O guia do Google diferencia a atualização de uma ocorrência da atualização do evento recorrente principal. Uma mudança aplicada a uma instância cria ou altera uma exceção. Isso permite mover um agendamento específico sem reescrever automaticamente todas as ocorrências da série.

Antes de escrever, confirme qual recurso está sendo alterado. Uma operação sobre o evento principal pode ter alcance diferente de uma operação sobre uma instância. A pergunta deste artigo é de leitura e identidade; ela não autoriza uma política de edição em massa.

Na sincronização local, mantenha a exceção vinculada ao principal. Não copie os dados como se fosse um evento totalmente independente e depois perca o recurringEventId. Também não force a exceção a voltar para o horário original porque esse valor aparece em originalStartTime.

Se o agendamento participa de relatórios, separe mudança operacional de atribuição. Origem do agendamento e origem de marketing são fatos diferentes. A remarcação de uma ocorrência recorrente não deve gerar uma nova conversão por conta própria.

Como testar a identidade recorrente com segurança?

Crie uma agenda controlada e uma série sintética, sem nome, contato, diagnóstico, motivo de consulta ou texto clínico. Consulte o evento principal e suas instâncias. Guarde o recurringEventId, o originalStartTime e o start de uma ocorrência escolhida.

Remarque somente essa ocorrência por um caminho autorizado. Consulte novamente a API. O teste passa quando o sistema reconhece o mesmo item, preserva a posição original e atualiza o horário atual sem criar um registro duplicado.

Repita a leitura com o comportamento padrão de events.list, com singleEvents=true e com events.instances. Documente quais recursos aparecem em cada visão. A diferença de forma não deve mudar a identidade local da ocorrência.

Por fim, teste uma falha de leitura após a notificação. A agenda deve permanecer pendente ou incerta até obter o estado atual. Ela não deve liberar o horário original ou ocupar o novo com base em uma suposição. A taxonomia de resultados de agendamento ajuda a manter esses estados técnicos fora das conversões confirmadas.

Perguntas frequentes

originalStartTime deveria mudar para o novo horário?

Não. O Google usa esse campo para identificar a posição original da ocorrência na série, mesmo quando ela foi movida. O horário efetivo atualizado fica em start.

Posso identificar a ocorrência usando apenas start?

Não com segurança. start muda quando o agendamento é remarcado. Preserve o vínculo com a série e a identidade original para atualizar o mesmo registro.

singleEvents=true também retorna o evento recorrente principal?

Não segundo o guia. Essa opção expande as recorrências em instâncias e omite os eventos recorrentes principais da resposta.

Uma notificação push informa qual ocorrência foi remarcada?

Não. A notificação push não contém os detalhes do evento alterado. Ela deve iniciar uma consulta autorizada à API, que então fornece o estado da ocorrência.

Referências

Leia também

Por que um agendamento recorrente remarcado no Google Calendar mantém o originalStartTime antigo? | Apointoo