Datas do Pedido¶

O pedido traz várias datas de logística: prazo de envio, previsão de entrega, data da transportadora. Os nomes são parecidos, mas só algumas vêm do marketplace. As outras são preenchidas pela Gubee quando o canal não informa nada e não devem ser usadas para decisão.

Esta página explica o que cada campo significa, em que fuso ele vem, de onde ele vem em cada marketplace, quando muda e quais campos não usar.

Resumo

Prazo para despachar o pedido: marketplaceDeadlineShippingDt.
Previsão de entrega ao comprador: marketplaceEstimatedDeliveryDt.
Não use shipments[].estimatedDeliveryDt, marketplaceShipments[].estimatedDeliveryDt nem transport.deliveredCarrierDate de pedidos de marketplace como prazo ou data de coleta.
Toda data sem sufixo de fuso está em UTC.
A origem e a confiabilidade de cada campo mudam por marketplace: consulte Como cada marketplace preenche.
Mudança de data não gera webhook.

Onde esses campos aparecem

Todos os campos desta página vêm no OrderApiDTO, o objeto devolvido por GET /integration/orders/{orderId}, POST /integration/orders/list/search e pela fila GET /integration/orders/queue/{status} (veja Receber Pedidos). Campos sem valor não são enviados no JSON: trate ausência como "o canal não informou".

Campos¶

Campo	O que é	Use para
`marketplaceDeadlineShippingDt`	Data limite que o marketplace dá ao vendedor para despachar o pedido (postagem ou coleta).	Prazo de envio, fila de expedição, alerta de atraso.
`marketplaceEstimatedDeliveryDt`	Previsão de entrega ao comprador informada pelo marketplace.	Previsão de entrega exibida ou repassada ao cliente.
`shipments[].estimatedDeliveryDt`	Previsão de entrega de um envio. Em pedidos de marketplace, pode ser um valor provisório (veja abaixo).	Só em envios que o seu ERP informou.
`marketplaceShipments[].estimatedDeliveryDt`	Previsão por pacote no marketplace. Pode ser um valor provisório.	Não use como prazo.
`shipments[].transport.deliveredCarrierDate`	Data em que a transportadora recebeu o pacote. Só é confiável quando o seu ERP informa o envio.	Só em envios que o seu ERP informou.
`status.estimatedDeliveryDt`	Previsão registrada no status `SHIPPED`.	Histórico; prefira `marketplaceEstimatedDeliveryDt`.

Fuso horário¶

O OrderApiDTO entrega as datas em UTC, em dois formatos:

Formato	Campos	Exemplo
Com sufixo `Z`	`marketplaceDeadlineShippingDt`	`2026-10-24T02:59:59Z`
Sem sufixo de fuso	todas as outras datas do pedido	`2026-10-30T00:00:00`

A falta do sufixo não quer dizer horário de Brasília. Interprete toda data sem fuso como UTC e converta para America/Sao_Paulo só na exibição.

from datetime import datetime, timezone
from zoneinfo import ZoneInfo

def parse_gubee_dt(value: str) -> datetime:
    dt = datetime.fromisoformat(value.replace("Z", "+00:00"))
    if dt.tzinfo is None:          # sem sufixo: é UTC
        dt = dt.replace(tzinfo=timezone.utc)
    return dt

parse_gubee_dt("2026-10-30T00:00:00").astimezone(ZoneInfo("America/Sao_Paulo"))
# 2026-10-29 21:00:00-03:00

Canais com diferença de 3 horas

Em alguns canais o horário de Brasília é gravado como se fosse UTC, e o valor fica deslocado em 3 horas. Esses casos estão marcados nas tabelas de Como cada marketplace preenche. Para prazos e previsões, considere a data e trate o horário com tolerância.

Exemplos conferidos com o painel do marketplace¶

Pedido	Campo	Valor no JSON	Em São Paulo	No painel do marketplace
Shopee	`marketplaceDeadlineShippingDt`	`2026-10-24T02:59:59Z`	23/10/2026 23:59	Prazo para envio: 23/10/2026 23:59
Shopee	`marketplaceEstimatedDeliveryDt`	`2026-10-30T00:00:00`	29/10/2026 21:00	Entrega prometida: 29/10/2026 21:00
Mercado Livre	`marketplaceEstimatedDeliveryDt`	`2026-10-23T03:00:00`	23/10/2026 00:00	Entrega prometida: 23/10/2026 00:00

Como cada marketplace preenche¶

As tabelas abaixo mostram, por código de plataforma (platform), de onde vem cada data hoje. "Calculado" quer dizer que o marketplace não informa a data e a Gubee estima a partir de outros dados do pedido. "Provisório" quer dizer um valor de preenchimento, sem relação com o marketplace.

Prazo de envio — `marketplaceDeadlineShippingDt`¶

Plataforma	Origem	Observação
`MERCADOLIVRE`	Data esperada de despacho do SLA do envio.	Levada ao fim do dia em `-03:00` (23:59:59.999). Não vem sem envio criado no Mercado Livre.
`SHOPEE`	`ship_by_date`.	Não vem antes do pagamento.
`AMAZONV2`	`LatestShipDate`.	Sem `LatestShipDate`, vem provisório: data da leitura + 1 dia.
`ALIEXPRESS`	Calculado: pagamento + maior prazo de preparo dos itens, em dias úteis (segunda a sexta).	Não vem antes do pagamento. Mantém o horário do pagamento.
`SHEIN`	Calculado: pagamento + 2 dias úteis, às 23:59:59 em `-03:00`.	Não reflete reagendamento na Shein.
`TEMU`	`expectShipLatestTime`.	—
`TIKTOKSHOP`	`delivery_due_time`; na falta, `collection_due_time`.	Confira com o prazo de despacho do Seller Center: pode ser posterior a ele.
`KWAI`	Prazo de coleta do pedido; na falta, `shippingDeadline`.	—
`MAGALU`	Data limite da entrega (`shipping.deadline.limit_date`).	Hoje traz o prazo de entrega ao comprador, não o de despacho. Não use como prazo de coleta.
`VIAVAREJO`	`promisedExpeditionDate`.	Casas Bahia, Extra e Ponto Frio.
`B2W`	`expedition_limit_date`.	Americanas.
`CARREFOURV2`	`shipping_deadline`.	—
`KABUM`	`shipping_deadline`.	—
`LEROYMERLINV2`	`shipping_deadline`.	—
`MADEIRAMADEIRAV2`	Não vem.	Controle o prazo pelo painel da MadeiraMadeira.
`NETSHOES`	Calculado: pagamento + 4 dias úteis.	Pode vir com diferença de 3 horas.
`CARREFOUR` (v1)	Calculado: débito do comprador + prazo de expedição da oferta, em dias úteis.	Pode vir com diferença de 3 horas.
`LEROYMERLIN` (v1)	`shipping_deadline`.	—
`MADEIRAMADEIRA` (v1)	Calculado: aprovação + maior prazo de expedição da cotação, em dias úteis.	Não vem quando o prazo de expedição é zero.
Demais plataformas	Não documentado.	Não conte com o campo.

Previsão de entrega — `marketplaceEstimatedDeliveryDt`¶

Plataforma	Origem	Observação
`MERCADOLIVRE`	Data estimada de entrega do envio (`estimated_delivery_time`).	Não vem sem envio criado no Mercado Livre.
`SHOPEE`	Fim da janela estimada de entrega (`edt_to`).	—
`AMAZONV2`	`LatestDeliveryDate`; na falta, `LatestShipDate`.	—
`ALIEXPRESS`	Não vem.	—
`SHEIN`	Não vem.	—
`TEMU`	`latestDeliveryTime`.	—
`TIKTOKSHOP`	`delivery_sla_time`.	—
`KWAI`	Prazo de despacho avaliado (`shippingAssessDeadline`).	A Kwai não informa previsão de entrega: o valor é um prazo de despacho.
`MAGALU`	Data limite da entrega + 3 dias.	Calculado a partir da data do Magalu.
`VIAVAREJO`	`promisedDeliveryDate`.	—
`B2W`	`estimated_delivery`.	Pode vir com diferença de 3 horas.
`CARREFOURV2`	`delivery_date.latest`.	Na falta, calculado pela cotação de frete; por último, provisório (data da leitura).
`KABUM`	`delivery_date.latest`.	Na falta, provisório (data da leitura).
`LEROYMERLINV2`	`shipping_deadline`.	Hoje traz o prazo de envio, não a previsão de entrega.
`MADEIRAMADEIRAV2`	`data_previsao_entrega`.	Pode vir com diferença de 3 horas.
`NETSHOES`	Não vem.	—
`CARREFOUR` (v1)	`delivery_date`; na falta, calculado.	—
`LEROYMERLIN` (v1)	Não vem.	—
`MADEIRAMADEIRA` (v1)	`data_previsao_entrega`.	—
Demais plataformas	Não documentado.	Não conte com o campo.

Data da transportadora — `transport.deliveredCarrierDate`¶

Plataforma	O que vem
`MADEIRAMADEIRAV2`, `MADEIRAMADEIRA` (v1)	Data da transportadora informada pela MadeiraMadeira, quando existe. Sem ela, provisório.
`MERCADOLIVRE`	Última atualização do envio no Mercado Livre a partir de "pronto para envio" (não é a coleta). Antes disso, provisório.
Todas as outras	Provisório: a data e hora em que o pedido foi lido.

Em todos os canais, o campo só tem o significado de "data em que a transportadora recebeu o pacote" quando o seu ERP informa o envio.

Prazo de envio — quando aparece¶

O prazo pode não vir na primeira notificação e aparecer depois:

Antes do pagamento: Shopee, AliExpress e os canais com prazo calculado a partir do pagamento ainda não têm o valor.
Antes do envio existir no marketplace: no Mercado Livre o campo não vem enquanto o pedido não tem envio criado, quando o envio é combinado com o vendedor ou quando o Mercado Livre não devolve o SLA naquele momento.

Depois que o prazo aparece, a Gubee só o troca por outro valor vindo do marketplace. Ele não volta a ficar vazio.

Valores provisórios em `shipments[]`¶

As datas dentro de shipments[] e marketplaceShipments[] são por envio e, em pedidos de marketplace, podem ser um valor provisório quando o canal não informa a data:

a data e hora em que o pedido foi lido;
uma data distante no futuro (de 15 a 60 dias após a leitura, conforme o canal);
o próprio prazo de envio (Shein, Leroy Merlin) ou o horário do despacho (Temu).

Por isso esses valores podem divergir da previsão do marketplace. Um sinal claro de valor provisório é uma data quase igual (diferença de milissegundos) a transport.deliveredCarrierDate do mesmo envio. Para a previsão de entrega, use sempre marketplaceEstimatedDeliveryDt.

Quando o seu ERP informa o envio¶

Ao informar o envio em PUT /integration/orders/shipped/{orderId} (veja Faturar e Expedir), os campos do envio passam a ter os valores que você enviou:

transport.deliveredCarrierDate: data de hoje ou do passado. Data futura é recusada com shipment.transport.deliveredCarrierDate must be past date.
estimatedDeliveryDt: data futura.

Atualizações e notificações¶

O marketplace pode reagendar o prazo de envio ou a previsão de entrega. Se a Gubee acompanha essa mudança sem troca de status depende do canal:

Plataforma	Mudança de data sem troca de status
`MERCADOLIVRE`, `SHOPEE`	Atualizada no pedido quando o marketplace avisa a mudança.
`AMAZONV2`	Atualizada enquanto o pedido está em `CREATED` ou `PAID`. Depois disso, não.
Todas as outras	Não é acompanhada. As datas ficam como foram lidas na criação ou no pagamento; o envio é lido de novo só na troca para `SHIPPED`.

Pergunta	Resposta
A mudança aparece na API?	Nos canais que acompanham a mudança, sim: a próxima consulta do pedido devolve o valor novo.
A mudança gera webhook?	Não. Webhooks de pedido são disparados só por mudança de status (veja Eventos de Webhook). Não existe evento "pedido atualizado".
Existe um indicador de "pedido completo"?	Não. Trate as datas como valores que podem mudar até o envio.

Entrega própria do vendedor¶

Nenhum canal muda a origem das datas conforme a modalidade de logística (logisticType). O que muda é se o marketplace tem um envio criado:

Mercado Livre: sem envio criado no Mercado Livre (envio combinado ou personalizado, retirada), nem o prazo de envio nem a previsão de entrega vêm, e o pedido não tem marketplaceShipments.
Demais canais: as datas seguem as tabelas acima. O campo vem se o canal informar e fica ausente se não informar.

Quando o prazo de expedição é combinado entre vendedor e comprador, ele deve ser controlado pelo seu ERP. Ao informar o envio pela API, preencha transport.deliveredCarrierDate e estimatedDeliveryDt com os valores reais.

Recomendação¶

Grave o prazo de envio a partir de marketplaceDeadlineShippingDt, exceto nos canais em que a tabela indica que ele não vem ou que traz outra data (hoje, MAGALU e MADEIRAMADEIRAV2). Nesses, controle o prazo pelo painel do marketplace.
Mostre ao comprador a previsão de marketplaceEstimatedDeliveryDt, considerando as observações da tabela do canal.
Converta de UTC antes de exibir: toda data sem sufixo de fuso é UTC.
Leia o pedido no webhook OrderPayed (ou na fila PAID) e grave as datas.
Consulte o pedido de novo antes de despachar, por exemplo ao faturar ou gerar a etiqueta, com GET /integration/orders/{orderId}. Isso pega um prazo que ainda não existia no pagamento ou que foi reagendado nos canais que acompanham a mudança, já que essas mudanças não geram webhook.
Não use transport.deliveredCarrierDate nem shipments[].estimatedDeliveryDt de pedidos de marketplace como prazo, data de coleta ou previsão.

curl "$GUBEE_API/integration/orders/261023BNWW03M5" \
  -H "Authorization: Bearer $JWT"

{
  "id": "261023BNWW03M5",
  "platform": "SHOPEE",
  "marketplaceDeadlineShippingDt": "2026-10-24T02:59:59Z",
  "marketplaceEstimatedDeliveryDt": "2026-10-30T00:00:00",
  "shipments": [
    {
      "estimatedDeliveryDt": "2026-10-30T00:00:00",
      "transport": {
        "deliveredCarrierDate": "2026-10-22T20:55:05.603"
      }
    }
  ]
}

Nesse pedido, o ERP deve gravar o prazo de envio de 23/10/2026 23:59 (marketplaceDeadlineShippingDt em São Paulo) e a previsão de entrega de 29/10/2026 21:00. O deliveredCarrierDate (2026-10-22T20:55:05.603) é só o momento em que o pedido foi lido, não uma coleta.