Introdução
Datas e carimbos de tempo estão integrados em quase todos os processos de negócios. Quando foi feito este pedido? Quando está agendada a entrega? Quando o funcionário fez o check-in? No Odoo, o campo Datetime é a maneira padrão de capturar e armazenar esse tipo de informação.
Ao contrário do campo Data, que armazena apenas uma data do calendário, o campo Datetime captura tanto a data quanto a hora exata. Esta distinção é mais importante do que pode parecer, especialmente em ambientes com usuários em múltiplos fusos horários ou ao rastrear eventos ao nível da hora e do minuto.
Este guia cobre tudo o que você precisa saber sobre o campo Datetime no Odoo: o que ele armazena, como se comporta no modelo de dados, como criá-lo e configurá-lo usando o Odoo Studio ou Python, e exemplos práticos de fluxos de trabalho empresariais reais.
O que é o Campo Datetime no Odoo
No ORM do Odoo, fields.Datetime armazena um valor combinado de data e hora, até o segundo. No nível do banco de dados, ele mapeia para uma coluna TIMESTAMP no PostgreSQL. O Odoo sempre armazena valores Datetime em UTC internamente e os converte para o fuso horário local do usuário ativo ao exibi-los na interface.
Do ponto de vista do utilizador, um campo Datetime aparece como um seletor de data e hora combinado em formulários. Mostra um widget de calendário ao lado de uma entrada de hora. Nas visualizações de lista e relatórios, o valor é formatado de acordo com as definições de idioma e fuso horário do utilizador ativo.
Aqui está como um campo Datetime se apresenta numa definição de modelo Python:
from odoo import fields, models
class SaleOrder(models.Model):
_inherit = 'sale.order'
x_confirmed_on = fields.Datetime(
string='Confirmado Em',
default=fields.Datetime.now,
readonly=True,
copy=False,
)O parâmetro string define o rótulo mostrado na interface. O parâmetro default preenche automaticamente o campo com o carimbo de data/hora atual quando um novo registo é criado. O parâmetro readonly impede a edição manual, o que é comum para carimbos de auditoria.
No Odoo Studio, este tipo de campo é chamado de campo Data & Hora. Quando criado através do Studio, recebe automaticamente um prefixo x_studio_. Quando criado via código ou pela API XML-RPC, você define o nome técnico você mesmo.
Como o Campo Funciona
Quando você define um campo Datetime no Odoo, o framework cria automaticamente a coluna correspondente no banco de dados durante a instalação ou atualização do módulo. Não há necessidade de escrever migrações SQL à mão.
Uma coisa que surpreende muitos desenvolvedores e utilizadores de negócios é como o Odoo lida com fusos horários. O banco de dados armazena sempre o valor em UTC. Quando um utilizador em Paris define um horário de reunião para as 15:00, o Odoo salva 13:00 UTC no banco de dados. Um utilizador em Nova Iorque que lê o mesmo registo verá 9:00 na sua interface. O ORM do Odoo lida com essa conversão de forma transparente com base no fuso horário configurado no perfil de cada utilizador.
Principais Atributos do Campo
Aqui estão as propriedades mais importantes de um campo Datetime no framework Odoo:
- default: Frequentemente definido como
fields.Datetime.nowpara preencher automaticamente com o carimbo de data/hora UTC atual quando um registo é criado. - required: Torna o campo obrigatório em formulários e a nível de modelo.
- readonly: Impede a edição manual na interface. Comum para carimbos de data/hora gerados automaticamente.
- compute: Liga um método Python que calcula o valor do campo dinamicamente a partir de outros campos ou lógica de negócios.
- store: Quando combinado com
compute, persiste o valor calculado na base de dados para uso em pesquisas e relatórios. - copy: Controla se o valor é duplicado ao copiar um registro. O padrão é
True. Defina comoFalsepara timestamps que não devem ser transferidos para duplicados. - index: Cria um índice de base de dados. Útil em campos que são frequentemente utilizados em filtros, como datas agendadas em tabelas grandes.
Como Aparece nas Vistas
Em vistas de formulário, um campo Datetime é apresentado como um seletor de data e hora combinado. Os utilizadores clicam para abrir um calendário e definir a hora diretamente na mesma entrada. Em vistas de lista, o valor aparece como uma string formatada com base nas definições de idioma do utilizador. Em vistas de pesquisa, os campos Datetime suportam filtros de intervalo de datas, como antes, depois e entre um período específico.
Você também pode emparelhar um campo Datetime com o widget date_range para exibir uma seleção de intervalo diretamente no formulário, o que é útil para agendar janelas e tarefas com prazo.
Datetime vs Data: Escolhendo o Campo Certo
Uma pergunta comum no desenvolvimento Odoo é quando usar fields.Datetime em vez de fields.Date. A regra é simples: use fields.Date quando a hora do dia não for relevante, e fields.Datetime quando precisar de precisão ao nível da hora ou minuto.
Use Date para: datas de vencimento de faturas, aniversários, datas de validade de produtos, datas de renovação de contratos.
Use Datetime para: timestamps de confirmação de pedidos, horários de início de reuniões, registos de presença de funcionários, operações de armazém agendadas.
Usar Datetime desnecessariamente adiciona complexidade de fuso horário sem qualquer benefício real. Quando em dúvida, pergunte-se se a hora do dia realmente importa para o processo de negócios que você está modelando.
Casos de Uso Empresarial
O campo Datetime aparece em quase todos os módulos do Odoo. Aqui estão cinco exemplos práticos de fluxos de trabalho empresariais reais.
CRM: Rastreamento de Atividades de Leads
No módulo CRM, vários campos Datetime nativos rastreiam quando eventos-chave ocorreram. O campo date_open regista quando um lead foi definido como Em Andamento. O campo date_deadline agenda um acompanhamento. Os gerentes de vendas usam esses campos para medir tempos de resposta, identificar oportunidades estagnadas e relatar sobre a atividade da equipe. Campos Datetime personalizados podem ampliar isso ainda mais, por exemplo, para registar quando um orçamento foi enviado ou quando uma chamada específica ocorreu.
Vendas: Carimbos de Tempo de Confirmação de Pedidos
O campo date_order em sale.order é um campo Datetime. Ele captura o momento exato em que uma venda foi confirmada. Isso é valioso para relatar sobre a atividade de vendas diárias ou horárias, calcular quanto tempo os pedidos levam para serem processados e auditar alterações feitas após a confirmação. Filtrar pedidos de venda por este campo é uma das operações de relatório mais comuns em qualquer configuração de vendas do Odoo.
Inventário: Datas de Transferência Programadas
O campo scheduled_date em stock.picking é um campo Datetime que as equipes de armazém usam para planejar quando um recebimento ou envio deve ocorrer. Ações automatizadas no Odoo podem acionar fluxos de trabalho com base em como esta data se compara ao tempo atual. Por exemplo, um e-mail automatizado pode ser enviado quando uma entrega está atrasada por um certo número de horas, permitindo uma comunicação proativa com os clientes antes que eles entrem em contato.
Manufatura: Horários de Início e Fim da Produção
Os pedidos de manufatura usam campos Datetime para registar quando a produção começou e quando foi concluída. Esses dados alimentam diretamente o planejamento de capacidade, relatórios de eficiência e análise de desempenho. Para empresas que operam em múltiplos turnos, capturar o tempo preciso é essencial para entender a produção real versus a planejada e identificar gargalos por hora do dia ou por operador.
RH: Gestão de Presença e Licenças
O módulo de Presença do RH usa campos Datetime para registar os horários de entrada e saída dos funcionários. Os pedidos de licença dependem do Datetime para definir o início e o fim exatos de uma ausência. Cálculos de folha de pagamento e regras de horas extras muitas vezes dependem desses valores sendo precisos até o minuto. Qualquer desvio ou falta de carimbo de tempo nos registos de presença pode afetar diretamente os cálculos de compensação, tornando a precisão aqui uma verdadeira exigência empresarial em vez de uma preferência técnica.
Criando ou Personalizando o Campo Datetime
Existem três maneiras principais de adicionar um campo Datetime a um modelo Odoo, dependendo da sua configuração técnica e se você prefere uma abordagem sem código ou de desenvolvedor.
Usando o Odoo Studio (Sem Código)
O Odoo Studio é a ferramenta de personalização integrada que permite adicionar campos sem escrever qualquer código. Para adicionar um campo Datetime através do Studio:
- Abra o Odoo Studio a partir do menu principal.
- Navegue até o formulário onde deseja adicionar o campo.
- Arraste um campo Data & Hora da barra lateral para o formulário.
- Defina o rótulo, o status de obrigatório e, opcionalmente, um valor padrão no painel de propriedades do campo.
- Salve e feche o Studio.
O Studio cria automaticamente o campo com um prefixo x_studio_ e o adiciona à visualização do formulário. Nenhuma migração de banco de dados é necessária da sua parte. O Odoo cuida de tudo isso automaticamente quando você salva. Esta é a abordagem recomendada para usuários de negócios que precisam adicionar um carimbo de data/hora a um formulário existente sem a participação de um desenvolvedor.
Usando Python em um Módulo Personalizado
Para desenvolvedores que estão construindo módulos Odoo, os campos Datetime são definidos em arquivos de modelo Python. Esta é a abordagem recomendada para qualquer personalização que precise ser controlada por versão e implantada em vários ambientes:
from odoo import fields, models
class ResPartner(models.Model):
_inherit = 'res.partner'
x_last_contact_date = fields.Datetime(
string='Data do Último Contato',
default=fields.Datetime.now,
copy=False,
)Após definir o campo no modelo, adicione-o ao arquivo XML da visualização relevante para que apareça na interface. O Odoo cria automaticamente a coluna TIMESTAMP quando você instala ou atualiza o módulo. Nenhum SQL manual é necessário.
Usando a API XML-RPC
Se você gerencia personalizações do Odoo programaticamente, por exemplo, como parte de um pipeline de implantação ou um script de configuração remota, pode criar campos Datetime via a API XML-RPC:
field_id = models.execute_kw(
ODOO_DB, uid, ODOO_API_KEY,
'ir.model.fields', 'create',
[{
'name': 'x_last_contact_date',
'field_description': 'Data do Último Contato',
'model_id': model_id,
'ttype': 'datetime',
'state': 'manual',
}]
)O valor ttype: datetime informa ao Odoo para criar um campo Datetime. O valor state: manual indica que este campo foi criado fora da instalação de um módulo, que é a configuração correta para campos criados através do Studio ou da API. É assim que a Dasolo gerencia a criação remota de campos para clientes como parte de scripts de configuração automatizados.
Melhores Práticas
1. Use fields.Datetime.now como uma referência de função, não como uma chamada
Ao definir um padrão, escreva default=fields.Datetime.now sem parênteses. Se você adicionar parênteses, o Python avalia a função uma vez quando a classe é carregada, e cada registro criado durante a vida útil do processo Odoo compartilhará o mesmo timestamp congelado. Sem parênteses, o Odoo chama a função no momento da criação do registro, dando a cada registro seu próprio timestamp preciso.
2. Defina copy=False em timestamps de eventos
Se um campo registra quando algo aconteceu, como uma data de confirmação ou um timestamp de conclusão, defina copy=False. Quando os usuários duplicam um registro, esses timestamps não devem ser transferidos do original. Um pedido de venda duplicado não deve mostrar a data de confirmação do pedido do qual foi copiado. Sem essa configuração, os dados históricos tornam-se silenciosamente não confiáveis.
3. Sempre passe UTC ao escrever via API
Ao criar ou atualizar registros através da API XML-RPC, sempre passe valores Datetime em UTC usando o formato de string YYYY-MM-DD HH:MM:SS. A API não realiza conversão de fuso horário na gravação. Qualquer string que você passar é armazenada diretamente no banco de dados como se fosse UTC, portanto, passar um horário local criará silenciosamente um erro de deslocamento que é difícil de diagnosticar mais tarde.
4. Use readonly para timestamps gerados automaticamente
Campos que capturam quando algo aconteceu devem geralmente ser definidos como somente leitura na interface. Isso impede que os usuários ajustem manualmente timestamps que devem refletir eventos reais do sistema. Se houver uma razão legítima para permitir a edição, controle o acesso através das configurações de segurança em nível de campo do Odoo, em vez de deixar o campo abertamente editável.
5. Escolha Data em vez de DataHora quando o tempo não é necessário
Se um campo precisa apenas rastrear uma data do calendário, como um prazo de entrega, uma data de renovação ou uma data de vencimento de fatura, use fields.Date. DataHora adiciona complexidade de manipulação de fuso horário que não serve a nenhum propósito quando o componente de tempo é sempre irrelevante. Manter o tipo de campo tão simples quanto o caso de uso exige torna o modelo de dados mais fácil de entender e manter.
Erros Comuns
Confusão de fuso horário ao ler valores brutos
Esta é a fonte mais frequente de confusão com campos de DataHora. Quando você lê um valor diretamente do banco de dados ou através da API, você vê o valor UTC, não o horário local do usuário. Muitos desenvolvedores constroem relatórios ou integrações com base na saída bruta da API e acabam com timestamps que estão adiantados ou atrasados em uma ou mais horas. Sempre aplique a conversão de fuso horário no lado do cliente ao apresentar resultados da API para os usuários finais, e torne isso um passo explícito em qualquer integração que você construir.
Escrevendo horários localizados via API
Se você passar um valor de DataHora que já está em um fuso horário local para a API do Odoo, o banco de dados o armazenará como se fosse UTC. Uma reunião marcada para as 15:00, horário de Paris, escrita como 2026-01-01 15:00:00 para a API, será exibida como 16:00 ou 17:00 para um usuário em Paris, dependendo do horário de verão ou de inverno. Este é um daqueles bugs que só aparecem em produção quando usuários reais em fusos horários reais começam a usar o sistema.
Usando default=fields.Datetime.now() com parênteses
Adicionar parênteses ao padrão é um erro sutil, mas sério. fields.Datetime.now() é avaliado uma vez quando a classe Python é carregada. Cada registro criado durante toda a vida útil do processo de trabalho do Odoo compartilhará esse mesmo timestamp congelado. Os registros parecerão corretos inicialmente, mas quebrarão qualquer análise baseada em tempos de criação. Este é um bug silencioso que pode levar muito tempo para ser detectado porque os timestamps parecem existir, eles são apenas todos idênticos.
Esquecendo copy=False nos timestamps de eventos
Sem copy=False, um registro duplicado carrega todos os valores de DataHora do original. Uma data de confirmação de pedido, um horário de criação de lead ou um timestamp de início de produção do registro fonte aparecerão inalterados no novo. Isso contamina silenciosamente relatórios históricos e torna trilhas de auditoria não confiáveis. É um pequeno detalhe de configuração que tem um impacto desproporcional na qualidade dos dados.
Usando DataHora quando Data é suficiente
Escolher DataHora para um campo como a data de vencimento de uma fatura ou uma data de expiração de produto adiciona complexidade desnecessária. Os usuários veem um componente de tempo que não precisam, cálculos de fuso horário são executados em cada exibição sem nenhum benefício, e a interface se torna ligeiramente mais complicada sem razão. O tipo de campo certo é o mais simples que modela corretamente a exigência de negócios.
Conclusão
O campo Datetime é um dos tipos de campo mais úteis no Odoo quando a precisão é importante. Desde o rastreamento de quando um lead foi aberto até o registro dos horários de início de produção e a presença dos funcionários, ele aparece em quase todos os módulos do sistema.
A principal coisa a internalizar é o modelo de armazenamento UTC. Tudo armazenado no banco de dados está em UTC. A interface lida automaticamente com a exibição de fusos horários para os usuários, mas qualquer leitura ou gravação externa através da API precisa levar isso em conta explicitamente. A maioria dos bugs relacionados a fusos horários em integrações do Odoo remonta a esse único mal-entendido.
Além disso, usar a sintaxe padrão correta, definir copy=False onde apropriado e escolher Data em vez de Datetime quando o tempo é irrelevante manterá seu modelo de dados limpo e seus relatórios confiáveis.
Na Dasolo, ajudamos empresas a implementar, personalizar e otimizar o Odoo em todos os departamentos. Se você precisa de ajuda para projetar um modelo de dados sólido, adicionar campos personalizados aos seus fluxos de trabalho ou construir um módulo Odoo completo do zero, nossa equipe está pronta para ajudar. Entre em contato conosco e vamos conversar sobre o seu projeto Odoo.