Transação gRPC · DispatchergRPC transaction · DispatcherTransacción gRPC · Dispatcher

Atualização de status de entregaDelivery status updateActualización de estado de entrega

A transação de escrita que informa ao backend o resultado da entrega de um pedido: entregue, sem sucesso ou reagendado. É disparada da tela de Entregas do dia. Diferente de Envio de pedido, não cria nem edita o pedido — só carimba o status de entrega. Ambas usam o mesmo serviceName MobileorderAPI, com payloads distintos. The write transaction that tells the backend the outcome of a delivery for an order: delivered, unsuccessful or rescheduled. It's fired from the Deliveries of the day screen. Unlike Order placement, it neither creates nor edits the order — it only stamps the delivery status. Both use the same MobileorderAPI serviceName, with distinct payloads. La transacción de escritura que informa al backend el resultado de la entrega de un pedido: entregado, sin éxito o reprogramado. Se dispara desde la pantalla de Entregas del día. A diferencia de Envío de pedido, no crea ni edita el pedido — solo marca el estado de entrega. Ambas usan el mismo serviceName MobileorderAPI, con payloads distintos.

PúblicoAudiencePúblico

QA · Suporte · Produto · DevQA · Support · Product · DevQA · Soporte · Producto · Dev

CamadaLayerCapa

Escrita · DispatcherWrite · DispatcherEscritura · Dispatcher

RelacionadoRelatedRelacionado

Deliveries · Order placement

AtualizadoUpdatedActualizado

17/08/20262026-08-17

Disponível emAvailable inDisponible en BR CL ZA

O que é e quando aconteceWhat it is and when it happensQué es y cuándo ocurre

Quando o representante de vendas trata uma entrega do dia, o app avisa o backend o que aconteceu com aquele pedido. É o momento em que a entrega deixa de estar "pendente" e ganha um desfecho. O pedido continua o mesmo — o que muda é apenas o status de entrega. Depois, esse status aparece de volta na lista de entregas e no pedido. When the sales rep handles a delivery of the day, the app tells the backend what happened to that order. It's the moment a delivery stops being "pending" and gets an outcome. The order itself stays the same — only the delivery status changes. That status then shows back up in the deliveries list and on the order. Cuando el representante de ventas gestiona una entrega del día, la app avisa al backend qué pasó con ese pedido. Es el momento en que la entrega deja de estar "pendiente" y obtiene un desenlace. El pedido sigue siendo el mismo — lo que cambia es solo el estado de entrega. Luego, ese estado vuelve a aparecer en la lista de entregas y en el pedido.

São três desfechos, cada um um gesto do rep:There are three outcomes, each a rep gesture:Son tres desenlaces, cada uno un gesto del rep:

Confirmar (entregue)Confirm (delivered)Confirmar (entregado)

A entrega foi feita com sucesso. Se o pedido exigir cobrança, o app pode coletar o pagamento antes de confirmar.The delivery was successful. If the order requires collection, the app may take the payment before confirming.La entrega se hizo con éxito. Si el pedido exige cobro, la app puede cobrar antes de confirmar.

Rejeitar (sem sucesso)Reject (unsuccessful)Rechazar (sin éxito)

A entrega não pôde ser concluída. O rep escolhe um motivo numa lista pré-definida.The delivery couldn't be completed. The rep picks a reason from a predefined list.La entrega no pudo concluirse. El rep elige un motivo de una lista predefinida.

ReagendarRescheduleReprogramar

A entrega é adiada para uma nova data, escolhida num calendário. Isso também gera uma folha de rota (trip sheet).The delivery is postponed to a new date, chosen on a calendar. This also generates a trip sheet.La entrega se pospone a una nueva fecha, elegida en un calendario. Esto también genera una hoja de ruta (trip sheet).

Não é o mesmo que criar pedidoNot the same as creating an orderNo es lo mismo que crear un pedido Esta transação não mexe nos itens, preços ou pagamento do pedido — isso é o Envio de pedido. Aqui só se registra o desfecho da entrega. This transaction does not touch the order's items, prices or payment — that's Order placement. Here we only record the delivery outcome. Esta transacción no toca los ítems, precios o pago del pedido — eso es el Envío de pedido. Aquí solo se registra el desenlace de la entrega.

Fluxo de telas que disparaScreen flow that fires itFlujo de pantallas que lo dispara

A jornada acontece toda na tela de Entregas do dia; aqui só situamos onde cada gesto dispara o envio:The journey happens entirely on the Deliveries of the day screen; here we only place where each gesture fires the send:El recorrido ocurre todo en la pantalla de Entregas del día; aquí solo situamos dónde cada gesto dispara el envío:

Abrir Entregas do diaOpen Deliveries of the dayAbrir Entregas del díaCada entrega é um cartão; as pendentes trazem um seletor para marcar uma.Each delivery is a card; pending ones carry a selector to pick one.Cada entrega es una tarjeta; las pendientes traen un selector para marcar una.
Confirmar → esta transaçãoConfirm → this transactionConfirmar → esta transacciónSelecionada uma entrega, o botão Confirmar abre um modal de confirmação (e a coleta de pagamento, se houver). Ao confirmar, dispara o envio com status entregue.With a delivery selected, the Confirm button opens a confirmation modal (and payment collection, if any). On confirm it fires the send with delivered status.Con una entrega seleccionada, el botón Confirmar abre un modal de confirmación (y el cobro, si lo hay). Al confirmar dispara el envío con estado entregado.
Rejeitar → esta transaçãoReject → this transactionRechazar → esta transacciónO botão Rejeitar abre um modal com a lista de motivos. Escolhido o motivo, dispara o envio com status sem sucesso e o código do motivo.The Reject button opens a modal with the reasons list. Once a reason is chosen it fires the send with unsuccessful status and the reason code.El botón Rechazar abre un modal con la lista de motivos. Elegido el motivo, dispara el envío con estado sin éxito y el código del motivo.
Reagendar → esta transaçãoReschedule → this transactionReprogramar → esta transacciónArrastar o cartão revela a ação de reagendar, que abre um calendário (próximo dia útil até +60 dias). Escolhida a data, dispara o envio com status reagendado e a nova data.Swiping the card reveals the reschedule action, which opens a calendar (next business day up to +60 days). Once the date is chosen it fires the send with rescheduled status and the new date.Deslizar la tarjeta revela la acción de reprogramar, que abre un calendario (próximo día hábil hasta +60 días). Elegida la fecha, dispara el envío con estado reprogramado y la nueva fecha.

Reagendar envia dois avisosReschedule sends two noticesReprogramar envía dos avisos Ao reagendar, o app envia duas transações em sequência: esta (status reagendado) e, logo depois, uma folha de rota (trip sheet) com a nova data. Para o rep, o gesto é um só — escolher a data. On reschedule, the app sends two transactions in sequence: this one (rescheduled status) and, right after, a trip sheet with the new date. For the rep it's a single gesture — pick the date. Al reprogramar, la app envía dos transacciones en secuencia: esta (estado reprogramado) y, justo después, una hoja de ruta (trip sheet) con la nueva fecha. Para el rep es un solo gesto — elegir la fecha.

Depois do envioAfter sendingDespués del envío

Confirmação ao repConfirmation to the repConfirmación al rep: Quando o backend aceita, o status da entrega é atualizado de imediato na lista (entregue, sem sucesso ou reagendado) — sem precisar recarregar. Se o envio falha, o status permanece pendente e o rep pode tentar de novo.When the backend accepts it, the delivery status updates immediately in the list (delivered, unsuccessful or rescheduled) — no reload needed. If the send fails, the status stays pending and the rep can retry.Cuando el backend lo acepta, el estado de la entrega se actualiza de inmediato en la lista (entregado, sin éxito o reprogramado) — sin recargar. Si el envío falla, el estado sigue pendiente y el rep puede reintentar.
Sem internetOfflineSin internet: Esta transação é enviada na hora — não entra na fila offline (a fila é usada só por visitas). Sem conexão, o envio falha e o rep repete quando a internet volta.This transaction is sent right away — it does not enter the offline queue (the queue is used by visits only). Without a connection the send fails and the rep retries when the internet is back.Esta transacción se envía en el acto — no entra en la cola offline (la cola la usan solo las visitas). Sin conexión el envío falla y el rep reintenta cuando vuelve internet.
Acompanhar o envioTracking the sendSeguir el envío: O status técnico do despacho (enviado, com erro) pode ser acompanhado na central de dados / tracking de despachos — útil para suporte investigar um envio.The dispatch's technical status (sent, errored) can be followed in the data center / dispatch tracking — useful for support to investigate a send.El estado técnico del despacho (enviado, con error) puede seguirse en el centro de datos / tracking de despachos — útil para que soporte investigue un envío.

Visão técnicaTechnical overviewVisión técnica

Atualização de status de entrega é a transação de saída que carimba no backend o desfecho da entrega de um pedido. É orquestrada pelo DeliveryOrchestrator, disparada da feature Entregas do dia. O payload é enxuto — um único cabeçalho OrderHeader — em contraste com o payload rico do Envio de pedido. Delivery status update is the outbound transaction that stamps the delivery outcome of an order on the backend. It's orchestrated by DeliveryOrchestrator, fired from the Deliveries of the day feature. The payload is lean — a single OrderHeader — in contrast with the rich payload of Order placement. Actualización de estado de entrega es la transacción de salida que marca en el backend el desenlace de la entrega de un pedido. La orquesta el DeliveryOrchestrator, disparada desde la feature Entregas del día. El payload es escueto — un único OrderHeader — en contraste con el payload rico del Envío de pedido.

Três ações, um builderThree actions, one builderTres acciones, un builder

Confirmar, rejeitar e reagendar passam pelo mesmo build(). A ação vem no input como DeliveryAction e define deliveryStatus, DeliveryDate e delResCode.Confirm, reject and reschedule go through the same build(). The action arrives in the input as DeliveryAction and drives deliveryStatus, DeliveryDate and delResCode.Confirmar, rechazar y reprogramar pasan por el mismo build(). La acción llega en el input como DeliveryAction y define deliveryStatus, DeliveryDate y delResCode.

Payload mínimoMinimal payloadPayload mínimo

Um só OrderHeader com 8 campos — sem itens, sem pagamento. A flag isDelivery marca que é atualização de entrega, não criação de pedido.A single OrderHeader with 8 fields — no items, no payment. The isDelivery flag marks it as a delivery update, not order creation.Un solo OrderHeader con 8 campos — sin ítems, sin pago. La flag isDelivery marca que es actualización de entrega, no creación de pedido.

RPC genérico compartilhadoShared generic RPCRPC genérico compartido

Usa o mesmo sendTransaction e o mesmo serviceName (MobileorderAPI) do Envio de pedido — só o JSON em message muda.Uses the same sendTransaction and the same serviceName (MobileorderAPI) as Order placement — only the JSON in message changes.Usa el mismo sendTransaction y el mismo serviceName (MobileorderAPI) del Envío de pedido — solo cambia el JSON en message.

FontesSourcesFuentes BuildDeliveryStatusUpdateDispatcherPayloadUseCase + DeliveryStatusUpdateDispatcherPayloadInput + DeliveryOrchestrator + DispatcherType + DispatcherConectaRep.proto. O input carrega entities cruas de domínio (CLAUDE.md §36); o build() constrói todo o wire. BuildDeliveryStatusUpdateDispatcherPayloadUseCase + DeliveryStatusUpdateDispatcherPayloadInput + DeliveryOrchestrator + DispatcherType + DispatcherConectaRep.proto. The input carries raw domain entities (CLAUDE.md §36); build() constructs the entire wire. BuildDeliveryStatusUpdateDispatcherPayloadUseCase + DeliveryStatusUpdateDispatcherPayloadInput + DeliveryOrchestrator + DispatcherType + DispatcherConectaRep.proto. El input lleva entities crudas de dominio (CLAUDE.md §36); el build() construye todo el wire.

Transporte gRPCgRPC transportTransporte gRPC

DispatcherConectaRep.proto · proto3 · package mn.bat.conectarep.dispatcher. O serviço expõe um único RPC genérico — não existe mensagem por transação. Esta transação usa o mesmo sendTransaction de todas as demais; o discriminador é o serviceName (aqui MobileorderAPI) e o JSON dentro de message.The service exposes a single generic RPC — there's no per-transaction message. This transaction uses the same sendTransaction as every other one; the discriminator is the serviceName (here MobileorderAPI) and the JSON inside message.El servicio expone un único RPC genérico — no existe mensaje por transacción. Esta transacción usa el mismo sendTransaction que todas las demás; el discriminador es el serviceName (aquí MobileorderAPI) y el JSON dentro de message.

sendTransactionunary

MétodoMethodMétodo

rpc sendTransaction(InboxTransactionRequest) returns (InboxTransactionReply)

path /mn.bat.conectarep.dispatcher.DispatcherConectaRepService/sendTransaction

Request · InboxTransactionRequest

endpoint: string · #1 · endpoint alvo — type.destination (Salesforce)target endpoint — type.destination (Salesforce)endpoint destino — type.destination (Salesforce)
serviceName: string · #2 · discriminador — MobileorderAPI (sem prefixo Promo_: entrega não tem promoção)discriminator — MobileorderAPI (no Promo_ prefix: delivery has no promotion)discriminador — MobileorderAPI (sin prefijo Promo_: la entrega no tiene promoción)
dateReference: string · #3 · AAAA-MM-DD do envio (submittedAt)YYYY-MM-DD of the submission (submittedAt)AAAA-MM-DD del envío (submittedAt)
transactionReference: string · #4 · o purchaseOrderNumber do pedido (correlação)the order's purchaseOrderNumber (correlation)el purchaseOrderNumber del pedido (correlación)
username: string · #5
message: string · #6 · o payload JSON serializado (a tabela da seção 08)the JSON payload serialized (the table in section 08)el payload JSON serializado (la tabla de la sección 08)
manufacturer: string · #7 · dado do dispositivodevice datadato del dispositivo
model: string · #8 · dado do dispositivodevice datadato del dispositivo
deviceUuid: string · #9 · literal provisório hoje (ver Pendências)provisional literal today (see Pending)literal provisional hoy (ver Pendientes)
deviceVersion: string · #10
tid: int64 · #11 · id de transação para idempotência/replaytransaction id for idempotency/replayid de transacción para idempotencia/replay

Reply · InboxTransactionReply

status: int32 · #1 · status do ack (0 ou 5 = sucesso; 1 = duplicado)ack status (0 or 5 = success; 1 = duplicate)status del ack (0 o 5 = éxito; 1 = duplicado)
message: string · #2 · mensagem do backendbackend messagemensaje del backend
transactionId: int32 · #3 · id atribuído pelo backend (correlação)backend-assigned id (correlation)id asignado por el backend (correlación)

Envelope → Request O builder devolve um DispatcherEnvelope (type = order, serviceName, payload, account, transactionReference, dateReference). O DispatcherGateway serializa payload em JSON para message, copia serviceName/dateReference/transactionReference, preenche os campos de dispositivo e o bearer token de auth, e chama o RPC. The builder returns a DispatcherEnvelope (type = order, serviceName, payload, account, transactionReference, dateReference). The DispatcherGateway serializes payload to JSON into message, copies serviceName/dateReference/transactionReference, fills in the device fields and the auth bearer token, and calls the RPC. El builder devuelve un DispatcherEnvelope (type = order, serviceName, payload, account, transactionReference, dateReference). El DispatcherGateway serializa payload a JSON en message, copia serviceName/dateReference/transactionReference, completa los campos del dispositivo y el bearer token de auth, y llama al RPC.

Para o tipo order, resendMayDuplicate == true: um reenvio pode duplicar a operação no backend; a idempotência via tid é o que mitiga isso. Diferente das visitas, esta transação não usa a fila offline — é enviada imediatamente.For the order type, resendMayDuplicate == true: a resend may duplicate the operation on the backend; idempotency via tid is what mitigates it. Unlike visits, this transaction does not use the offline queue — it's sent immediately.Para el tipo order, resendMayDuplicate == true: un reenvío puede duplicar la operación en el backend; la idempotencia vía tid es lo que lo mitiga. A diferencia de las visitas, esta transacción no usa la cola offline — se envía de inmediato.

serviceName compartilhado com Envio de pedidoserviceName shared with Order placementserviceName compartido con Envío de pedido

Esta transação reusa o DispatcherType.order e, com ele, o serviceName MobileorderAPI — o mesmo endpoint e o mesmo RPC do Envio de pedido. Não são transações concorrentes: o backend distingue pela forma do payload e, sobretudo, pela flag isDelivery.This transaction reuses DispatcherType.order and, with it, the MobileorderAPI serviceName — the same endpoint and the same RPC as Order placement. They're not competing transactions: the backend tells them apart by the payload shape and, above all, by the isDelivery flag.Esta transacción reusa DispatcherType.order y, con él, el serviceName MobileorderAPI — el mismo endpoint y el mismo RPC del Envío de pedido. No son transacciones concurrentes: el backend las distingue por la forma del payload y, sobre todo, por la flag isDelivery.

AspectoAspectAspecto	01 · Order placement	02 · Este doc02 · This doc02 · Este doc
`DispatcherType`	`order` / `orderIndirect` / `orderApproval`	`order`
`serviceName`	`MobileorderAPI` (+ variantes)(+ variants)(+ variantes)	`MobileorderAPI`
Raiz do payloadPayload rootRaíz del payload	`OrderHeader` + `OrderDetail` + `OrderPaymentInstruction` + …(≈179 chaves)…(≈179 keys)…(≈179 claves)	`OrderHeader` (8 campos)(8 fields)(8 campos)
`isDelivery`	`false`	`true` (discrimina)(discriminates)(discrimina)
IntençãoIntentIntención	criar / editar / liberar / cancelar pedidocreate / edit / release / cancel ordercrear / editar / liberar / cancelar pedido	carimbar status de entregastamp delivery statusmarcar estado de entrega
Disparado porFired fromDisparado por	fluxo de carrinhocart flowflujo de carrito	Deliveries of the day

Companheira: folha de rotaCompanion: trip sheetCompañera: hoja de ruta Ao reagendar, o DeliveryOrchestrator dispara também uma segunda transação — DispatcherType.deliveryReschedule (serviceName TripsheetUploadAPI, via BuildDeliveryTripSheetDispatcherPayloadUseCase) — sequencial, só se este status-update tiver sucesso. É uma transação separada (raiz tripSheet), não coberta por este doc. On reschedule, DeliveryOrchestrator also fires a second transaction — DispatcherType.deliveryReschedule (serviceName TripsheetUploadAPI, via BuildDeliveryTripSheetDispatcherPayloadUseCase) — sequentially, only if this status update succeeds. It's a separate transaction (root tripSheet), not covered by this doc. Al reprogramar, el DeliveryOrchestrator dispara también una segunda transacción — DispatcherType.deliveryReschedule (serviceName TripsheetUploadAPI, vía BuildDeliveryTripSheetDispatcherPayloadUseCase) — secuencial, solo si este status update tiene éxito. Es una transacción separada (raíz tripSheet), no cubierta por este doc.

Como é disparadoHow it's firedCómo se dispara

A transação é orquestrada pelo DeliveryOrchestrator.updateDelivery(...), chamado pelo DeliveriesOfTheDayNotifier (métodos confirmSelected / rejectSelected / rescheduleDelivery). O notifier apenas reúne entities cruas; o orchestrator monta o input com o relógio (DateTimeUtils.now()); o builder é o dono único de toda formatação de data e derivação wire. A cascata:The transaction is orchestrated by DeliveryOrchestrator.updateDelivery(...), called by DeliveriesOfTheDayNotifier (methods confirmSelected / rejectSelected / rescheduleDelivery). The notifier only gathers raw entities; the orchestrator assembles the input with the clock (DateTimeUtils.now()); the builder is the sole owner of all date formatting and wire derivation. The cascade:La transacción la orquesta DeliveryOrchestrator.updateDelivery(...), llamado por DeliveriesOfTheDayNotifier (métodos confirmSelected / rejectSelected / rescheduleDelivery). El notifier solo reúne entities crudas; el orchestrator arma el input con el reloj (DateTimeUtils.now()); el builder es el dueño único de todo formateo de fecha y derivación wire. La cascada:

DeliveriesOfTheDayNotifierconfirm / reject / reschedule
- order + action + reason/date + resourceorder + action + reason/date + resourceorder + action + reason/date + resourceDeliveryOrchestrator.updateDelivery
  - monta o inputassembles inputarma el inputDeliveryStatusUpdateDispatcherPayloadInput
    - build()BuildDeliveryStatusUpdateDispatcherPayloadUseCasemonta o wireassembles the wirearma el wire
      - devolvereturnsdevuelveDispatcherEnvelope
        
        SubmitDeliveryUseCaseDispatcherOrchestrator.dispatch
        
        serializa + authserialize + authserializa + authDispatcherGateway
        
        sendTransactionBackendgRPC

Após o ack de sucesso, o orchestrator faz um update otimista (order.deliveryStatus/deliveryDate) e persiste no cache de pedidos (OrderRepository.getCachedOrders → saveOrders). Não há re-fetch remoto.After the success ack, the orchestrator does an optimistic update (order.deliveryStatus/deliveryDate) and persists to the orders cache (OrderRepository.getCachedOrders → saveOrders). No remote re-fetch.Tras el ack de éxito, el orchestrator hace un update optimista (order.deliveryStatus/deliveryDate) y persiste en el cache de pedidos (OrderRepository.getCachedOrders → saveOrders). Sin re-fetch remoto.

O input (entities cruas)The input (raw entities)El input (entities crudas)

DeliveryStatusUpdateDispatcherPayloadInput (Freezed). Carrega o dado como existe no domínio; nada de formato wire. O relógio chega como submittedAt (via DateTimeUtils.now() no orchestrator).DeliveryStatusUpdateDispatcherPayloadInput (Freezed). Carries data as it exists in the domain; no wire shaping. The clock arrives as submittedAt (via DateTimeUtils.now() in the orchestrator).DeliveryStatusUpdateDispatcherPayloadInput (Freezed). Lleva el dato como existe en el dominio; nada de formato wire. El reloj llega como submittedAt (vía DateTimeUtils.now() en el orchestrator).

CampoFieldCampo	TipoTypeTipo	PapelRoleRol
`order`	`OrderEntity`	pedido cru — o builder deriva `sfid`, PO, sfid/SAP/nome da contaraw order — the builder derives `sfid`, PO, account sfid/SAP/namepedido crudo — el builder deriva `sfid`, PO, sfid/SAP/nombre de la cuenta
`action`	`DeliveryAction`	`confirm · reject · reschedule`
`submittedAt`	`DateTime`	→ `dateReference` (`yyyy-MM-dd`)
`rescheduleDate`	`DateTime?`	nova data (só `reschedule`) → `DeliveryDate`new date (`reschedule` only) → `DeliveryDate`nueva fecha (solo `reschedule`) → `DeliveryDate`
`rejectionReason`	`DeliveryCancelReasonEntity?`	motivo (só `reject`) → `delResCode` = `reason.code`reason (`reject` only) → `delResCode` = `reason.code`motivo (solo `reject`) → `delResCode` = `reason.code`

A lista de motivos de rejeição (DeliveryCancelReasonEntity = code + reason) vem do reference data (GetDeliveryCancelReasonsUseCase) e é escolhida no modal de rejeição; só o code vai para o payload.The rejection reasons list (DeliveryCancelReasonEntity = code + reason) comes from reference data (GetDeliveryCancelReasonsUseCase) and is chosen in the reject modal; only the code reaches the payload.La lista de motivos de rechazo (DeliveryCancelReasonEntity = code + reason) viene del reference data (GetDeliveryCancelReasonsUseCase) y se elige en el modal de rechazo; solo el code llega al payload.

Payload (`message`)

O JSON serializado no campo message do request. A tabela tem 4 colunas — Campo JSON · Tipo · Origem do Dado · Regra — e lista toda chave que o build() emite: 1 chave raiz (OrderHeader) + 8 campos no objeto do cabeçalho. Campo, Tipo e Origem são código cru; só a Regra é prosa. Um exemplo completo está em transaction_example.json, ao lado deste doc.The JSON serialized into the request's message field. The table has 4 columns — JSON field · Type · Data source · Rule — and lists every key that build() emits: 1 root key (OrderHeader) + 8 fields in the header object. Field, Type and Source are raw code; only Rule is prose. A full example sits in transaction_example.json, next to this doc.El JSON serializado en el campo message del request. La tabla tiene 4 columnas — Campo JSON · Tipo · Origen del Dato · Regla — y lista toda clave que build() emite: 1 clave raíz (OrderHeader) + 8 campos en el objeto del encabezado. Campo, Tipo y Origen son código crudo; solo la Regla es prosa. Un ejemplo completo está en transaction_example.json, junto a este doc.

Raiz do payloadPayload rootRaíz del payload

Campo JSON	TipoTypeTipo	Origem do DadoData sourceOrigen del Dato	RegraRuleRegla
`OrderHeader`	array	`build()`	array de um único objeto (cabeçalho de entrega)single-element array (delivery header)array de un solo objeto (encabezado de entrega)

OrderHeader objeto únicosingle objectobjeto único 8 camposfieldscampos

Campo JSON	TipoTypeTipo	Origem do DadoData sourceOrigen del Dato	RegraRuleRegla
`OrderSfId`	string	`order.sfid`	Salesforce id do pedidoorder Salesforce idSalesforce id del pedido
`OrderID`	string	`order.purchaseOrderNumber`	PO do pedidoorder POPO del pedido
`deliveryStatus`	string	`action.writeStatus`	`Delivered` (confirm) · `Unsuccessful` (reject) · `Rescheduled` (reschedule)`Delivered` (confirm) · `Unsuccessful` (reject) · `Rescheduled` (reschedule)`Delivered` (confirm) · `Unsuccessful` (reject) · `Rescheduled` (reschedule)
`DeliveryDate`	string	`Calculado`	`reschedule` com data → `rescheduleDate` em `yyyy-MM-dd`; senão `""reschedule` with date → `rescheduleDate` as `yyyy-MM-dd`; else `""reschedule` con fecha → `rescheduleDate` en `yyyy-MM-dd`; si no `""`
`RetailerID`	string	`order.accountSfid`	sfid do varejoretail sfidsfid del punto de venta
`delResCode`	string	`Calculado`	`reject` → `rejectionReason?.code ?? ""`; senão `""reject` → `rejectionReason?.code ?? ""`; else `""reject` → `rejectionReason?.code ?? ""`; si no `""`
`isDelivery`	bool	`Fixo: true`	marca o payload como atualização de entrega (discrimina de criação de pedido)marks the payload as a delivery update (discriminates from order creation)marca el payload como actualización de entrega (discrimina de la creación de pedido)
`proofOfDelivery`	string	`Fixo: "slRep"`	literal fixo do contrato (ver Pendências)fixed contract literal (see Pending)literal fijo del contrato (ver Pendientes)

Regras de negócioBusiness rulesReglas de negocio

Ação → status de escritaAction → write statusAcción → estado de escritura DeliveryAction · deliveryStatus

O DeliveryAction escolhido na UI define três campos do payload de uma vez. Cada valor do enum carrega seu writeStatus de wire:The DeliveryAction chosen in the UI drives three payload fields at once. Each enum value carries its wire writeStatus:El DeliveryAction elegido en la UI define tres campos del payload de una vez. Cada valor del enum lleva su writeStatus de wire:

`DeliveryAction`	`deliveryStatus`	`DeliveryDate`	`delResCode`
`confirm`	`Delivered`	`""`	`""`
`reject`	`Unsuccessful`	`""`	`reason.code`
`reschedule`	`Rescheduled`	`rescheduleDate` (`yyyy-MM-dd`)	`""`

Datas e códigos condicionaisConditional dates & codesFechas y códigos condicionales DeliveryDate · delResCode · dateReference

DeliveryDate: preenchido só quando action == reschedule && rescheduleDate != null, formatado com DateFormatType.isoDate (yyyy-MM-dd). Em confirm/reject vai "".DeliveryDate: filled only when action == reschedule && rescheduleDate != null, formatted with DateFormatType.isoDate (yyyy-MM-dd). On confirm/reject it's "".DeliveryDate: se completa solo cuando action == reschedule && rescheduleDate != null, formateado con DateFormatType.isoDate (yyyy-MM-dd). En confirm/reject va "".
delResCode: preenchido só quando action == reject, com rejectionReason?.code ?? "". Em confirm/reschedule vai "".delResCode: filled only when action == reject, with rejectionReason?.code ?? "". On confirm/reschedule it's "".delResCode: se completa solo cuando action == reject, con rejectionReason?.code ?? "". En confirm/reschedule va "".
dateReference (envelope, não payload): submittedAt em yyyy-MM-dd — o instante do envio, do relógio único (DateTimeUtils.now()).dateReference (envelope, not payload): submittedAt as yyyy-MM-dd — the send instant, from the single clock (DateTimeUtils.now()).dateReference (envelope, no payload): submittedAt en yyyy-MM-dd — el instante del envío, del reloj único (DateTimeUtils.now()).

Conta no envelopeAccount on the envelopeCuenta en el envelope DispatchAccountEntity

O builder anexa ao envelope uma DispatchAccountEntity (metadado de despacho, fora do payload JSON), derivada do pedido:The builder attaches a DispatchAccountEntity to the envelope (dispatch metadata, outside the JSON payload), derived from the order:El builder adjunta al envelope una DispatchAccountEntity (metadato de despacho, fuera del payload JSON), derivada del pedido:

DispatchAccountEntity	OrigemSourceOrigen
`sfid`	`order.accountSfid`
`sapCode`	`order.accountSapId`
`name`	`order.accountName`

Envio, ack e update otimistaSend, ack & optimistic updateEnvío, ack y update optimista dispatch · cache

O envio é imediato: o tipo order não entra na fila offline (a fila cobre só visit). Sem conexão, o envio falha e é retentado pelo rep.The send is immediate: the order type does not enter the offline queue (the queue covers only visit). Without a connection the send fails and is retried by the rep.El envío es inmediato: el tipo order no entra en la cola offline (la cola cubre solo visit). Sin conexión el envío falla y el rep lo reintenta.
Sucesso = ack com status == 0 ou status == 5 (DispatcherAck.isSuccess); status == 1 = duplicado. Só então o orchestrator prossegue.Success = ack with status == 0 or status == 5 (DispatcherAck.isSuccess); status == 1 = duplicate. Only then does the orchestrator proceed.Éxito = ack con status == 0 o status == 5 (DispatcherAck.isSuccess); status == 1 = duplicado. Solo entonces el orchestrator continúa.
Update otimista: order.copyWith(deliveryStatus: newStatus.value, deliveryDate: ...) — delivered / rejected / rescheduled (enum DeliveryStatus) — persistido no cache de OrdersEntity. Sem re-fetch remoto.Optimistic update: order.copyWith(deliveryStatus: newStatus.value, deliveryDate: ...) — delivered / rejected / rescheduled (DeliveryStatus enum) — persisted to the OrdersEntity cache. No remote re-fetch.Update optimista: order.copyWith(deliveryStatus: newStatus.value, deliveryDate: ...) — delivered / rejected / rescheduled (enum DeliveryStatus) — persistido en el cache de OrdersEntity. Sin re-fetch remoto.
Em reschedule bem-sucedido, o orchestrator ainda dispara a folha de rota (deliveryReschedule / TripsheetUploadAPI) antes do update otimista.On a successful reschedule, the orchestrator additionally fires the trip sheet (deliveryReschedule / TripsheetUploadAPI) before the optimistic update.En un reschedule exitoso, el orchestrator además dispara la hoja de ruta (deliveryReschedule / TripsheetUploadAPI) antes del update optimista.

Pendências / roadmapPending / roadmapPendientes / roadmap

O que o builder envia inerte ou provisório, documentado fiel ao estado atual do código (nunca descrito como se já existisse):What the builder ships inert or provisional, documented faithfully to the current code state (never described as already existing):Lo que el builder envía inerte o provisional, documentado fiel al estado actual del código (nunca descrito como si ya existiera):

Não portado / pendenteNot ported / pendingNo portado / pendiente

proofOfDelivery: literal fixo "slRep" — não há captura real de comprovante de entrega (foto/assinatura). O campo existe no contrato mas o app não coleta nada hoje.proofOfDelivery: fixed literal "slRep" — there's no real proof-of-delivery capture (photo/signature). The field exists in the contract but the app collects nothing today.proofOfDelivery: literal fijo "slRep" — no hay captura real de comprobante de entrega (foto/firma). El campo existe en el contrato pero la app no recoge nada hoy.
isDelivery: sempre true — constante do builder que discrimina esta transação da criação de pedido no mesmo serviceName.isDelivery: always true — builder constant that discriminates this transaction from order creation on the same serviceName.isDelivery: siempre true — constante del builder que discrimina esta transacción de la creación de pedido en el mismo serviceName.
Transporte: deviceUuid vai como literal provisório no gateway (pendência conhecida do Dispatcher, herdada).Transport: deviceUuid ships as a provisional literal in the gateway (known Dispatcher pending item, inherited).Transporte: deviceUuid va como literal provisional en el gateway (pendiente conocido del Dispatcher, heredado).
A companheira deliveryReschedule (TripsheetUploadAPI) tem enabledMarkets BR/CL, mas o DeliveryOrchestrator a dispara em qualquer reagendamento com data, sem cruzar o mercado — possível divergência de gating a confirmar com o backend.The companion deliveryReschedule (TripsheetUploadAPI) has enabledMarkets BR/CL, yet DeliveryOrchestrator fires it on any reschedule with a date, without checking the market — a possible gating divergence to confirm with the backend.La compañera deliveryReschedule (TripsheetUploadAPI) tiene enabledMarkets BR/CL, pero el DeliveryOrchestrator la dispara en cualquier reprogramación con fecha, sin cruzar el mercado — posible divergencia de gating a confirmar con el backend.

Transação irmãSister transactionTransacción hermana O serviceName MobileorderAPI é compartilhado com a criação de pedido — documentada em 01 · Order placement (doc separado). The MobileorderAPI serviceName is shared with order creation — documented in 01 · Order placement (separate doc). El serviceName MobileorderAPI es compartido con la creación de pedido — documentada en 01 · Order placement (doc separado).

★

MercadosMarketsMercados

A disponibilidade vem do DispatcherType.order.enabledMarkets = BR/CL/ZA. AR/PY/PE não têm o dispatcher de pedido (config PANGEA mínima), então não disparam esta transação.Availability comes from DispatcherType.order.enabledMarkets = BR/CL/ZA. AR/PY/PE have no order dispatcher (minimal PANGEA config), so they don't fire this transaction.La disponibilidad viene de DispatcherType.order.enabledMarkets = BR/CL/ZA. AR/PY/PE no tienen el dispatcher de pedido (config PANGEA mínima), así que no disparan esta transacción.

BRx CLx ZAx AR— PY— PE—

disponívelavailabledisponible presente, desligadopresent, offpresente, apagado ausenteabsentausente

BRCL

Folha de rota do reagendamentoReschedule trip sheetHoja de ruta del reagendamiento A transação companheira do reagendamento (deliveryReschedule / TripsheetUploadAPI) é declarada só para BR/CL em enabledMarkets. O status-update em si (este doc) vale nos três mercados. The reschedule's companion transaction (deliveryReschedule / TripsheetUploadAPI) is declared only for BR/CL in enabledMarkets. The status update itself (this doc) applies in all three markets. La transacción compañera del reagendamiento (deliveryReschedule / TripsheetUploadAPI) está declarada solo para BR/CL en enabledMarkets. El status update en sí (este doc) aplica en los tres mercados.

AR · PY · PE Existem como mercados do app (config PANGEA mínima), mas não têm dispatcher de pedido — DispatcherType.order não os lista em enabledMarkets. A atualização de status de entrega não é disparada nesses mercados. They exist as app markets (minimal PANGEA config), but have no order dispatcher — DispatcherType.order doesn't list them in enabledMarkets. Delivery status update is not fired in these markets. Existen como mercados de la app (config PANGEA mínima), pero no tienen dispatcher de pedido — DispatcherType.order no los lista en enabledMarkets. La actualización de estado de entrega no se dispara en estos mercados.