Campo Date no Odoo: Guia Completo para Usar e Configurar

Introdução

Se já abriu um pedido de venda, uma tarefa de projeto ou uma ordem de produção em Odoo, provavelmente já interagiu com um campo Data. Prazos, datas de entrega, vencimentos de fatura e inícios de contratos são exemplos típicos: toda a informação dependente do calendário em Odoo costuma assentar neste tipo de campo.

Para utilizadores finais, o campo Data parece simples — um clique abre um calendário e escolhe-se o dia. Contudo, internamente há regras importantes: aprender como o campo é representado no modelo de dados, em que difere do campo DateTime e como o configurar evita armadilhas com fusos horários e comportamentos inesperados nas automações.

Este guia reúne o essencial sobre o campo Data em Odoo: o que guarda, como aparece na interface, como o manipular via código ou Studio e como tirar partido dele sem causar surpresas nos processos de negócio.

O que é o campo Data no Odoo

No ORM do Odoo, o tipo fields.Date serve para registar uma data do calendário sem qualquer componente horário. Um valor como "2026-03-06" representa apenas o dia, sem horas, minutos ou segundos.

No PostgreSQL, que é a base de dados usada pelo Odoo, um campo Date corresponde ao tipo de coluna DATE. Isto distingue-se do DateTime, que usa TIMESTAMP e contém a hora completa até aos segundos.

Na interface, o campo Data surge como um campo de texto com um seletor de calendário. Pode-se escrever a data manualmente ou selecioná-la no calendário; nas vistas de lista aparece formatado consoante a localidade do utilizador.

Exemplo de definição de um campo Data num módulo personalizado

from odoo import fields, models

class ProjectTask(models.Model):
    _inherit = 'project.task'

    x_deadline_confirmed = fields.Date(
        string='Confirmed Deadline',
        help='The officially confirmed deadline agreed with the customer.',
    )

Quando se cria um campo através do Odoo Studio, ele é rotulado como Date e recebe automaticamente o prefixo x_studio_. Se o criar via código Python ou pela API XML-RPC, escolhe-se o nome técnico do campo manualmente.

Como funciona o campo

Data vs DateTime: o que realmente muda

O ponto crucial: o campo Data não contém hora. Não há conversões de fuso horário nem deslocamentos de horas — apenas o dia do calendário em si.

O campo DateTime, pelo contrário, guarda um carimbo temporal completo e costuma ser armazenado em UTC. Odoo converte esse valor para o fuso horário do utilizador ao apresentar a informação, o que é muitas vezes a origem dos problemas de "datas que mudam de dia" relatados pelas equipas. Esses casos são normalmente problemas de DateTime, não de Date.

Com um campo Data, o valor que grava é exatamente o que todos os utilizadores veem: 2026-03-15 será 2026-03-15 em qualquer lugar do mundo, sem alterações.

Atributos principais do campo

A seguir estão as propriedades mais relevantes que pode configurar num campo Data no framework do Odoo:

• required: torna o campo obrigatório na interface e ao nível do modelo.
• default: define um valor por defeito automático. Por exemplo, fields.Date.today preenche a data atual em novos registos.
• index: cria um índice na base de dados para acelerar filtros e pesquisas sobre o campo.
• compute: liga o campo a um método Python que calcula dinamicamente o seu valor.
• store: quando usado com compute, persiste o valor calculado na base de dados.
• readonly: impede a edição direta do campo na interface.
• copy: controla se o valor é copiado ao duplicar um registo. Por defeito é True.

Como aparece nas vistas

Em formulários, o campo Data mostra um campo com popup de calendário; em listas aparece como texto formatado. Nos filtros de pesquisa suporta intervalos predefinidos — "esta semana", "este mês", etc. — e operadores de comparação como antes, depois ou num dia específico.

O formato de exibição obedece à língua/localidade do utilizador: um utilizador em Portugal verá DD/MM/YYYY enquanto outro em Estados Unidos verá MM/DD/YYYY. Internamente, porém, o valor é sempre armazenado em ISO (YYYY-MM-DD).

Interação com o ORM do Odoo

Ao ler um campo Date em código, o ORM devolve um objecto Python datetime.date ou False se estiver vazio. Ao escrever, pode fornecer um datetime.date ou uma string em "YYYY-MM-DD". Pela API XML-RPC, as datas circulam como strings.

Trabalhar com campos Date no modelo de dados Odoo não envolve transformações complexas — o framework gere a formatação e o armazenamento automaticamente, o que torna este tipo de campo prático no desenvolvimento diário.

Casos de uso empresariais

Exemplos práticos de uso nas empresas

CRM: datas de início e fim de contrato

Em equipas de vendas, os contratos costumam ter datas de início e término bem definidas. Um campo Data no lead ou num modelo de contrato facilita saber quando um acordo entra em vigor e quando expira.

Com acionadores automáticos, pode configurar notificações por email ou alterar o estado do contrato quando a data de término se aproxima, evitando renovações perdidas e reduzindo trabalho manual.

Vendas: datas de entrega solicitadas

Os clientes pedem frequentemente uma data específica de entrega. Muitas empresas adicionam um campo "Data solicitada pelo cliente" no pedido de venda para que a equipa de operações tenha um prazo claro para planear.

Usar um campo Data em vez de DateTime mantém a informação simples e evita confusões de fuso horário nas operações de armazém: toda a equipa vê exactamente a mesma data introduzida pela equipa de vendas.

Inventário: datas de validade em lotes

Em setores como alimentação e farmacêutica, é essencial registar datas de validade por lote. A gestão de lotes do Odoo utiliza campos Date para registar validade e data de consumo preferencial em stock.lot.

Essas datas alimentam estratégias FEFO (First Expired First Out) e alertas automáticos quando o stock se aproxima da validade, ajudando a cumprir normas e a proteger a qualidade sem inspeções manuais constantes.

Contabilidade: vencimentos de faturas

Os vencimentos das faturas em Odoo são campos Date. Eles determinam quando são enviadas notificações de pagamento, como se identificam cobranças em atraso e como se calculam relatórios de envelhecimento de saldos.

Ter estes prazos corretos é crítico para o fluxo de caixa: um vencimento errado pode quebrar o acompanhamento automático de cobranças e prejudicar a gestão financeira.

Recursos Humanos: datas de admissão, contrato e certificações

Nas equipas de RH, campos Date são usados para data de admissão, fim de período experimental, início/fim de contrato e validade de certificações. Esses valores alimentam emails automáticos, alertas e regras de cálculo salarial.

Um módulo de RH bem desenhado depende de dados temporais limpos: muitas automações críticas partem destas datas registadas com precisão nos registos dos colaboradores.

Como criar ou personalizar um campo Data

Tem três formas principais de adicionar um campo Data a um modelo Odoo, conforme a sua equipa e o nível técnico disponível.

Usar o Odoo Studio (sem código)

O Odoo Studio é a forma mais simples para adicionar um campo Data sem escrever código — aconselhável para utilizadores e consultores que querem adicionar rastreio de datas em formulários padrão de forma rápida:

1. Abra o Odoo Studio a partir do menu principal.
2. Vá ao formulário onde pretende inserir o campo.
3. Arraste um campo Date da barra lateral para o formulário.
4. Defina a etiqueta, se é obrigatório e um valor por defeito, se necessário.
5. Grave e feche o Studio.

O Studio cria o campo com prefixo x_studio_ e o adiciona à vista imediatamente, sem necessidade de migração manual de base de dados.

Usar Python num módulo personalizado

Para desenvolvedores, os campos Date declaram-se em ficheiros Python de modelos. Esta abordagem é indicada quando precisa de controlo de versão e deployment entre ambientes:

from odoo import fields, models

class SaleOrder(models.Model):
    _inherit = 'sale.order'

    x_customer_requested_date = fields.Date(
        string='Customer Requested Date',
        index=True,
        copy=False,
        help='Delivery date requested by the customer at time of order.',
    )

Depois de adicionar o campo no modelo, inclua-o na vista XML correspondente para que apareça na interface. Odoo cria a coluna na base de dados ao instalar ou atualizar o módulo.

Usar a API XML-RPC

Para criação programática de campos como parte de pipelines de deployment ou scripts remotos, pode criar campos Date via XML-RPC:

field_id = models.execute_kw(
    ODOO_DB, uid, ODOO_API_KEY,
    'ir.model.fields', 'create',
    [{
        'name': 'x_customer_requested_date',
        'field_description': 'Customer Requested Date',
        'model_id': model_id,
        'ttype': 'date',
        'state': 'manual',
    }]
)

O ttype para um campo Date é 'date'; para DateTime seria 'datetime'. Definir 'manual' em state indica que o campo foi criado manualmente e não por instalação de módulo — útil em automações de configuração remota.

Boas práticas

1. Use Date, não DateTime, quando a hora não interessa

Se o que importa é apenas o dia (um prazo, início de contrato, data de nascimento ou validade), opte por fields.Date. Usar DateTime nestes casos complica com fusos horários sem vantagem prática e pode originar erros de um dia dependendo da configuração do servidor.

2. Defina um valor por defeito significativo quando fizer sentido

Para campos como "Data prevista de entrega" ou "Data de follow-up", ter como padrão hoje ou hoje + N dias dá aos utilizadores um ponto de partida lógico. Use default=fields.Date.today (sem parêntesis) para um default dinâmico que avalia a data no momento da criação do registo.

3. Indexe campos de data usados em relatórios e filtros

Se os utilizadores filtram regularmente por um campo de data (faturas em atraso, renovações próximas, certificações a expirar), adicione index=True. Em conjuntos de dados grandes, isto melhora muito o desempenho das pesquisas e relatórios com um custo inicial muito baixo.

4. Use copy=False para datas que não devem ser copiadas

Datas como "Data de início de contrato" ou "Data de validade" normalmente não devem ser duplicadas ao duplicar um registo. copy=False obriga a introduzir a data novamente no novo registo, evitando que uma data antiga se propague silenciosamente.

5. Acrescente constraints quando dois campos de data formarem um intervalo

Quando existir uma dupla "Data de Início" e "Data de Fim", implemente uma constraint com @api.constrains para garantir que a data final não é anterior à inicial. É simples de implementar e evita muitos problemas de qualidade de dados posteriores.

Erros comuns

Confundir Date e DateTime

A confusão mais comum é usar DateTime quando apenas se precisa de uma data. DateTime é armazenado em UTC e convertido na exibição, por isso uma data introduzida num fuso pode aparecer deslocada noutro. Por exemplo, 15 de março num servidor em UTC+2 pode surgir como 14 de março para alguém em UTC-5.

Use sempre o tipo mais simples que satisfaça a necessidade do negócio.

Ignorar o fuso do servidor em ações agendadas

Ao criar ações agendadas ou relatórios que comparam com "hoje", lembre-se de que fields.Date.today() devolve a data do servidor em UTC. Para a maior parte dos casos isto é aceitável, mas pode haver discrepâncias de um dia para equipas espalhadas por fusos horários distantes. Teste automações sensíveis a datas em diferentes fusos se a sua equipa for distribuída globalmente.

Falta de validação em pares de datas

É comum encontrar implementações com "Data de Início" e "Data de Fim" sem validação que evite que a data final seja anterior à inicial. Sem essa verificação, entram dados inválidos que comprometem cálculos de duração, filtros e relatórios. Adicione sempre um @api.constrains nesses casos.

Esquecer de indexar campos de data usados em filtros

Campos de data usados em verificações de "atrasado", vistas de "próximos prazos" ou relatórios de envelhecimento costumam ser consultados com comparações do tipo "data < hoje". Sem índice, cada consulta faz um scan completo da tabela. Em modelos com muitos registos, como faturas ou movimentos de stock, a ausência de índices pode degradar significativamente a performance operacional.

Guardar datas em campos Char

Algumas equipas guardam datas como texto para manter um formato específico ou evitar o seletor de calendário. Isso impede ordenação, filtragem e cálculos de datas, e arruína relatórios. Use sempre fields.Date: o Odoo e a base de dados tratam da formatação e da localização corretamente, sem necessidade de armazenar datas como texto.

Perguntas frequentes

Qual é a diferença entre um campo Date e um DateTime no Odoo?

Um campo Date guarda apenas a data do calendário (ano, mês, dia) sem componente horário. Um campo DateTime guarda um timestamp completo com hora, minutos e segundos, normalmente armazenado em UTC e apresentado no fuso horário do utilizador. Use Date quando a hora do dia não for relevante; use DateTime quando precisar de registar o momento exacto de um evento.

Como definir a data de hoje como valor por defeito num campo Date?

Em Python, utilize default=fields.Date.today sem parêntesis. Isto passa uma função que o Odoo avalia no momento da criação do registo, garantindo que o valor por defeito é sempre a data atual. No Odoo Studio, seleccione "Today" nas propriedades do campo.

Posso calcular um campo Date com base noutros campos?

Sim. Defina o campo com compute='_compute_my_date' e escreva um método com @api.depends() listando os campos que disparam a recomputação. Use as classes datetime.date e timedelta para as operações. Acrescente store=True se pretender guardar o resultado na base de dados para permitir pesquisa, agrupamento e exportação.

Como filtrar registos por um intervalo de datas num domínio Odoo?

Utilize operadores de comparação padrão no domínio. Por exemplo, para encontrar registos com data em março de 2026:

[
    ('x_date_field', '>=', '2026-03-01'),
    ('x_date_field', '<=', '2026-03-31')
]

As strings de data em domínios devem usar sempre o formato ISO: YYYY-MM-DD.

Posso tornar um campo Data obrigatório apenas em determinadas condições?

O Odoo padrão não aplica obrigatoriedade condicional no backend sem código. Pode usar attrs na vista XML para marcar visualmente um campo como exigido segundo outras condições, mas a validação no servidor exige uma constraint Python com @api.constrains. Para casos simples, as regras condicionais do Odoo Studio são uma alternativa prática sem escrever código.

Conclusão

O campo Data é um dos tipos mais úteis no framework Odoo: simples de compreender, fácil de usar e poderoso o suficiente para suportar lógica de negócio crítica como lembretes, verificações de atrasos e relatórios temporais.

Principais mensagens a reter: opte por Date em vez de DateTime quando só precisar do dia, configure defaults e índices para melhorar usabilidade e performance, e garanta validações quando duas datas definam um intervalo.

Modelos de dados limpos e bem concebidos em Odoo começam com escolhas pequenas — como seleccionar o tipo de campo adequado. Acertar nestes detalhes desde o princípio distingue uma implementação sólida e o campo Data é uma peça central desse trabalho.

Na Dasolo, apoiamos empresas a implementar, personalizar e otimizar Odoo em todos os departamentos. Se precisa de ajuda a desenhar um modelo de dados consistente, adicionar campos e fluxos de trabalho personalizados ou desenvolver um módulo completo, a nossa equipa está disponível para colaborar. Contacte-nos e vamos conversar sobre o seu projeto Odoo.