Datas em planilhas e APIs: evite formatos ambíguos e mudanças de dia

Por que uma data pode ter mais de uma interpretação

Uma célula pode exibir «03/04/2025», mas essa aparência não basta para saber se representa 3 de abril ou 4 de março. A Microsoft observa que as regras usadas por programas de planilha para interpretar datas podem ser complexas e recomenda especificá-las o máximo possível em seu [guia sobre sistemas, formatos e interpretação de datas](https://support.microsoft.com/es-es/excel/change-the-date-system-format-or-two-digit-year-interpretation).

Por isso, não trate a apresentação visual como contrato de integração. Antes de exportar, identifique o que cada valor representa e combine como o sistema deve recebê-lo. O [guia de formatos de data e número da Google Sheets API](https://developers.google.com/workspace/sheets/api/guides/formats?hl=es-419) descreve padrões de formato que podem ser incluídos em solicitações. Consulte a documentação do serviço específico para confirmar o que ele aceita.

• Evite datas numéricas em que dia e mês possam ser trocados, a menos que o contrato defina claramente a ordem.
• Não presuma que a aparência de uma célula determina como o consumidor interpretará o valor.

Defina se o campo representa um dia ou um momento

Antes de escolher um formato, esclareça o significado do campo. Uma data que identifica apenas um dia, como a data de vencimento de uma tarefa, não indica por si só um horário ou um local. Já um momento representa um ponto específico no tempo, como o horário em que uma operação foi registrada. Embora os dois valores possam aparecer como datas em uma planilha, o contrato deve deixar claro qual deles é esperado.

Registre essa distinção no contrato de dados. Para cada coluna, informe o nome, o significado, o tipo esperado, se aceita valores vazios e um exemplo válido. Se o campo representa apenas um dia, não acrescente um horário fictício. Se representa um momento, especifique como expressar o horário e qual fuso horário a integração deve considerar.

• Se o dado precisa identificar o mesmo dia sem representar um horário, defina o campo como uma data.
• Se é necessário saber quando algo aconteceu, defina o tratamento do horário e do fuso horário para essa integração.

Combine uma representação explícita

Como escolha para o contrato desta integração, você pode usar uma ordem explícita de ano, mês e dia, como «2025-04-03», em vez de «03/04/2025». Para momentos, especifique também como expressar o horário e o fuso horário. Produtor e consumidor precisam concordar tanto sobre o formato quanto sobre o significado do dado.

Documente as condições relevantes para o serviço específico: se segundos são permitidos, qual é a precisão, como o fuso horário é indicado e o que é considerado inválido. Não confunda formato com significado: uma célula exibida como data pode conter texto ou outro valor. O guia da Google Sheets API citado acima trata de padrões de formato que podem ser incluídos em solicitações; ele não substitui o contrato da sua integração.

• Defina formato, tipo, fuso horário quando aplicável, precisão, obrigatoriedade e um exemplo para cada coluna.
• Encaminhe valores fora do contrato para revisão ou rejeite-os; não os corrija silenciosamente.

Considere o fuso horário quando houver horário

Para um campo que representa apenas um dia, avalie se o processo realmente precisa de informação adicional de horário. Para um evento com horário específico, combine o fuso horário que produtor e consumidor usarão e registre essa decisão no contrato. Evite misturar um horário local com uma interpretação diferente em outra etapa do fluxo.

Como prática de validação para sua integração, inclua casos próximos da meia-noite se forem relevantes. Uma mudança de dia na exibição não basta, por si só, para concluir que o valor foi corrompido: compare o resultado com o significado e as regras combinados no contrato. Se o campo representa apenas um dia, evite acrescentar informações de horário desnecessárias.

• Para cada momento, documente o fuso horário combinado por produtor e consumidor.
• Se houver uma mudança de dia, compare o resultado com o contrato antes de decidir se ocorreu um erro.

Teste os casos importantes para sua integração

Para verificar um fluxo específico, prepare casos de teste conforme o contrato. Você pode incluir datas em que dia e mês possam ser confundidos, valores próximos da mudança de dia, uma célula vazia, texto que não seja uma data e um valor com precisão ou fuso horário inesperado. Decida antecipadamente se cada caso deve ser aceito, rejeitado ou encaminhado para revisão. Esta é uma prática de validação para a integração, não uma afirmação sobre requisitos de uma norma externa.

Defina também o que significa uma célula vazia. Se o fluxo precisar distinguir entre «sem dado», «desconhecido» e «não se aplica», documente essas opções. Para valores inválidos, estabeleça uma resposta identificável ou interrompa o envio para corrigir a origem; não substitua dados silenciosamente.

Como verificação do percurso, mantenha uma cópia de um pequeno conjunto de valores de entrada, envie-os pelo fluxo previsto e inspecione o que o consumidor recebe. Se houver retorno à planilha, confira também esse resultado. Compare o significado, não apenas a aparência, e registre os resultados esperados e observados. Se houver uma diferença, verifique em que etapa ela aparece e repita os testes após qualquer ajuste.

• Possível lista de testes: data ambígua, fim do mês, mudança de ano, meia-noite, célula vazia e texto inválido.
• Guarde a entrada, o valor enviado, a resposta e o resultado visível para comparar as etapas.
• Considere a verificação aprovada quando o significado combinado for preservado e os erros previstos forem detectados.

Organize a revisão e a integração no Apification

Como fluxo de trabalho, mantenha uma planilha de teste separada dos dados operacionais. No Apification Cloud, você pode organizar arquivos e projetos em um espaço de trabalho com controle de versões e criar ou editar planilhas com o ONLYOFFICE sem tirá-las do armazenamento do Cloud. Use a planilha para revisar cabeçalhos, valores vazios e exemplos antes de preparar a integração. Essa revisão facilita a inspeção pela equipe, mas não substitui as regras de validação do serviço que consome ou envia os dados.

O Apification permite integrar o Cloud e seus serviços por meio de REST API, OpenAPI, webhooks, iframe e JavaScript. Consulte a documentação da API pertinente para definir a troca real; não presuma um endpoint ou comportamento específico com base apenas nesses recursos. Após uma alteração importante, o histórico de itens do Cloud permite revisar versões anteriores, baixá-las e restaurar conteúdo. Esse recurso ajuda a recuperar uma planilha de trabalho, mas não substitui a verificação do contrato nem a revisão dos resultados.

• Antes de conectar dados reais, valide uma cópia de trabalho com exemplos representativos e regras combinadas.
• Confirme na documentação da API qual operação e formato o serviço específico aceita.
• Se uma planilha for alterada, consulte o histórico e mantenha uma versão conhecida para facilitar a recuperação.

Perguntas frequentes