Pular para o conteúdo principal

TaxPointDate — Data do Facto Gerador e Movimento de Stock

O que é o TaxPointDate?​

taxPointDate (Data do facto gerador) tem uma dupla função: é o momento do facto gerador do IVA e a data efectiva do movimento de stock de uma linha.

  • Como momento do facto gerador do IVA, marca o instante em que nasce a obrigação tributária — ou seja, quando os bens foram colocados à disposição do adquirente ou o serviço foi realizado. Por regra, o imposto torna-se exigível nesse mesmo momento, podendo contudo ser antecipado consoante as regras de faturação aplicáveis. Trata-se de uma data com relevância legal para efeitos de reporte fiscal, sendo relevante para todos os tipos de documento fiscais, independentemente de a gestão de stock estar activa.
  • Como data de movimento de stock, responde à pergunta: "Em que data é que este artigo entrou ou saiu fisicamente do stock?" — determinando o histórico de stock (ItemStockOrders), os cálculos de preço de custo e as consultas de quantidade disponível sempre que XConfig.OnlineStock estiver activo.

Na prática estes dois conceitos coincidem: a data em que a mercadoria se movimentou é a data em que nasce a obrigação fiscal.

Comportamento por defeito

Por omissão, taxPointDate segue a data do documento. Pode ser definido de forma independente por linha quando o movimento de stock ocorreu numa data diferente — por exemplo ao retrodatar um documento ou corrigir um lançamento anterior.

Localização do campo​

taxPointDate é um campo por linha, enviado dentro de cada entrada do array items[]:

{
  "documentTypeId": 5,
  "items": [
    {
      "itemKeyId": "ART001",
      "quantity": 2,
      "taxId": 1,
      "taxPointDate": "2026-06-10T14:30:00Z"
    }
  ]
}

Cada linha pode ter um taxPointDate diferente. Isto é intencional — num único documento, artigos distintos podem ter movimentado stock em datas diferentes.

Comportamento por defeito quando omitido​

Quando taxPointDate não é fornecido numa linha, o sistema resolve automaticamente um valor por defeito:

CenáriotaxPointDate resultante
documentDate fornecido, passado ou hojeSegue documentDate — o stock move-se nessa data
documentDate não fornecidoInstante actual (UtcNow)
documentDate é uma data futuraLimitado ao instante actual (UtcNow) — o movimento de stock nunca é colocado automaticamente no futuro
Movimentos de stock futuros

O sistema nunca atribui automaticamente um taxPointDate futuro. Se a data do documento for futura e não for fornecido taxPointDate, o campo assume o momento actual.

Se enviar explicitamente um taxPointDate futuro, será respeitado — mas tenha em atenção que os movimentos de stock serão registados com uma data futura, o que pode afectar relatórios de disponibilidade de stock e cálculos de custo.

Efeito no stock​

taxPointDate é a chave temporal para toda a lógica de stock. Afecta três áreas:

1. ItemStockOrders — registo histórico​

Cada movimento de stock é registado em ItemStockOrders com o taxPointDate como marca temporal. É este campo que ordena cronologicamente o histórico de movimentos.

2. LastEntrance / LastExit em ItemStock​

Após a aplicação de um movimento de stock, o sistema actualiza LastEntrance (para entradas) ou LastExit (para saídas) apenas se o taxPointDate do novo movimento for igual ou mais recente do que a data já registada.

Isto significa que um movimento retroactivo não sobrescreve um LastEntrance/LastExit mais recente, embora a alteração de quantidade seja sempre aplicada independentemente da data.

3. AverageCostPrice​

O preço de custo médio ponderado é recalculado em cada movimento de entrada. Quando um movimento é retroactivo e não actualiza LastEntrance, a actualização do preço de custo segue a mesma salvaguarda — apenas o preço de custo do movimento mais recente é mantido como referência actual.

Artigos compostos​

Para artigos com componentes (compostos), o taxPointDate da linha pai é automaticamente herdado por todas as linhas de componentes filhos. Não é necessário definir taxPointDate nas linhas filhas — o sistema propaga o valor do pai.

Conversões de documentos​

Ao criar um documento a partir de outro documento — por exemplo uma nota de crédito ou uma nota de débito com referência a uma venda original — a API ancora automaticamente o taxPointDate de cada linha convertida à data de movimento da linha original.

Desta forma o histórico de stock mantém-se consistente.

Ordem de prioridade (da mais alta para a mais baixa):

  1. taxPointDate definido explicitamente no payload para a linha — respeitado sempre.
  2. taxPointDate da linha de origem referenciada (originBodyGuid) — utilizado quando não é fornecido valor explícito.
  3. UtcNow — fallback para linhas sem referência.

Por isso, se precisar de substituir a data ancorada numa linha convertida específica, basta enviar o taxPointDate pretendido nessa linha e terá prioridade.

Relação com documentDate​

CampoFinalidadeAfecta o stock?
documentDateData legal/fiscal de emissão do documento❌ Sem efeito directo
taxPointDate (por linha)Data efectiva do movimento de stock✅ Sim — toda a lógica de stock

Ambos podem coexistir de forma independente:

{
  "documentDate": "2026-06-01T00:00:00Z",
  "items": [
    {
      "itemKeyId": "ART001",
      "quantity": 1,
      "taxId": 1,
      "taxPointDate": "2026-05-28T10:00:00Z"
    }
  ]
}

Neste exemplo, a factura tem data legal de 1 de junho, mas o movimento de stock é registado a 28 de maio.

O stock só é actualizado quando onlineStock está activo​

taxPointDate não tem efeito em ItemStock ou ItemStockOrders a menos que XConfig.OnlineStock esteja activo para a base de dados. Quando desactivado, o campo continua a ser guardado na linha do documento, mas não é efectuado qualquer movimento de stock.

Fuso horário​

Todas as datas na API — incluindo taxPointDate — são enviadas e recebidas em UTC. O sistema converte-as de forma transparente para o fuso horário indicado no cabeçalho X-TimeZone antes de persistir, pelo que os valores guardados na base de dados estão no fuso horário local do cliente que fez o pedido, e não em UTC.

Resumo​

AspectoComportamento
Campo por linha✅ Cada linha pode ter uma data diferente
Opcional✅ Por defeito assume a data do documento ou UtcNow se omitido
Datas futuras⚠️ Permitido se enviado explicitamente; nunca atribuído automaticamente
Datas retroactivas✅ Suportado — alteração de quantidade sempre aplicada; LastEntrance/LastExit só actualizado se mais recente
Filhos de compostos✅ Herdam automaticamente do pai
Conversões de documentos✅ Ancorado automaticamente à data de movimento da linha de origem (substituível por linha)
Efeito no stockApenas quando XConfig.OnlineStock = true
FormatoISO 8601 UTC (2026-06-10T14:30:00Z)

Relacionado​

Última actualização: 25 de junho de 2026