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

Criação de merchandisingMerchandising creationCreación de merchandising

A transação de escrita que registra a criação de material de merchandising no ponto de venda, via o Dispatcher. Quando o representante de vendas conclui uma ordem de serviço de merchandising cujo fluxo roda fora do CRM, o app envia este registro — atividade, serviço, motivo e as peças com suas fotos e comentários. É um payload enxuto: sem cálculo, sem variantes, só o retrato do que foi instalado/mantido no PDV. The write transaction that records the creation of merchandising material at the point of sale, through the Dispatcher. When the sales rep finishes a merchandising service order whose flow runs outside the CRM, the app sends this record — activity, service, reason and the pieces with their photos and comments. It's a lean payload: no computation, no variants, just a snapshot of what was installed/maintained at the retail. La transacción de escritura que registra la creación de material de merchandising en el punto de venta, vía el Dispatcher. Cuando el representante de ventas termina una orden de servicio de merchandising cuyo flujo corre fuera del CRM, la app envía este registro — actividad, servicio, motivo y las piezas con sus fotos y comentarios. Es un payload compacto: sin cálculo, sin variantes, solo el retrato de lo que se instaló/mantuvo en el punto de venta.

PúblicoAudiencePúblico

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

CamadaLayerCapa

Escrita · DispatcherWrite · DispatcherEscritura · Dispatcher

RelacionadoRelatedRelacionado

Merchandising · Service order

AtualizadoUpdatedActualizado

17/08/20262026-08-17

Disponível emAvailable inDisponible en BR

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

Merchandising é o material de ponto de venda — displays, geladeiras, expositores, cartazes — que a marca instala e mantém no varejo. Quando o representante de vendas registra uma ordem de serviço de merchandising (o que foi instalado, mantido ou removido, com foto e comentário), o app envia esse registro ao backend por esta transação. É o momento em que o trabalho de campo do merchandising vira um registro no sistema. Merchandising is the point-of-sale material — displays, coolers, racks, posters — that the brand installs and maintains at the retail. When the sales rep records a merchandising service order (what was installed, maintained or removed, with a photo and comment), the app sends that record to the backend through this transaction. It's the moment the merchandising field work becomes a record in the system. Merchandising es el material de punto de venta — displays, refrigeradores, exhibidores, carteles — que la marca instala y mantiene en el punto de venta. Cuando el representante de ventas registra una orden de servicio de merchandising (lo que se instaló, mantuvo o retiró, con foto y comentario), la app envía ese registro al backend por esta transacción. Es el momento en que el trabajo de campo de merchandising se vuelve un registro en el sistema.

Cada envio carrega:Each send carries:Cada envío lleva:

Contexto do serviçoService contextContexto del servicio

A atividade, o serviço e o motivo escolhidos pelo rep, além do varejo e da visita em que ocorreu.The activity, service and reason the rep picked, plus the retail and visit where it happened.La actividad, el servicio y el motivo que eligió el rep, además del punto de venta y la visita donde ocurrió.

Peças e fotosPieces & photosPiezas y fotos

Cada peça de merchandising vai com o seu tipo, um comentário e até três fotos tiradas no PDV.Each merchandising piece goes with its type, a comment and up to three photos taken at the point of sale.Cada pieza de merchandising va con su tipo, un comentario y hasta tres fotos tomadas en el punto de venta.

Sem escolhas do repNo rep choicesSin elecciones del rep

Não há variantes nem ramificações: o gesto é sempre o mesmo — concluir a ordem de serviço e enviar.There are no variants or branches: the gesture is always the same — finish the service order and send.No hay variantes ni ramificaciones: el gesto es siempre el mismo — terminar la orden de servicio y enviar.

Um par de enviosA pair of sendsUn par de envíos Ao concluir a ordem de serviço, o app dispara duas transações em sequência: esta (Criação de merchandising), que registra o retrato do serviço, e logo a Ordem de serviço de merchandising, que gera a ordem em si. Para o rep é um único gesto. On finishing the service order, the app fires two transactions in sequence: this one (Merchandising creation), which records the service snapshot, and right after the Merchandising service order, which creates the order itself. For the rep it's a single gesture. Al terminar la orden de servicio, la app dispara dos transacciones en secuencia: esta (Creación de merchandising), que registra el retrato del servicio, y enseguida la Orden de servicio de merchandising, que crea la orden en sí. Para el rep es un solo gesto.

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

A transação é o último passo da ordem de serviço de merchandising. As telas do caminho pertencem à feature de Merchandising; aqui só situamos onde o envio acontece:The transaction is the last step of the merchandising service order. The screens along the way belong to the Merchandising feature; here we only place where the send happens:La transacción es el último paso de la orden de servicio de merchandising. Las pantallas del camino pertenecen a la feature de Merchandising; aquí solo situamos dónde ocurre el envío:

EspecificaçõesSpecificationsEspecificacionesO rep escolhe a atividade, o serviço e o motivo do merchandising.The rep picks the merchandising activity, service and reason.El rep elige la actividad, el servicio y el motivo del merchandising.
Tipos de peçaPiece typesTipos de piezaSeleciona as peças de merchandising e, para cada uma, tira fotos e escreve um comentário.Selects the merchandising pieces and, for each, takes photos and writes a comment.Selecciona las piezas de merchandising y, para cada una, toma fotos y escribe un comentario.
ResumoSummaryResumenConfere o serviço e as peças antes de enviar.Reviews the service and pieces before sending.Revisa el servicio y las piezas antes de enviar.
Enviar → esta transaçãoSend → this transactionEnviar → esta transacciónAo tocar em enviar no resumo, o app dispara a Criação de merchandising (e, na sequência, a ordem de serviço). É este toque que aciona a transação.Tapping send on the summary fires Merchandising creation (and, right after, the service order). This tap is what triggers the transaction.Al tocar enviar en el resumen, la app dispara la Creación de merchandising (y, enseguida, la orden de servicio). Este toque es lo que activa la transacción.

Depois do envioAfter sendingDespués del envío

Confirmação ao repConfirmation to the repConfirmación al rep: A conclusão da ordem de serviço só é confirmada ao rep quando o segundo envio (a ordem de serviço) é aceito. Este registro de criação é complementar: se ele falhar, o app apenas anota o erro internamente e segue — não bloqueia a conclusão.Finishing the service order is only confirmed to the rep when the second send (the service order) is accepted. This creation record is complementary: if it fails, the app just logs the error internally and moves on — it doesn't block completion.La conclusión de la orden de servicio solo se confirma al rep cuando el segundo envío (la orden de servicio) es aceptado. Este registro de creación es complementario: si falla, la app solo anota el error internamente y continúa — no bloquea la conclusión.
Sem internetOfflineSin internet: O envio pode entrar em fila e ser reenviado quando a conexão volta. Um reenvio pode, em tese, duplicar o registro; o sistema usa um identificador de transação para reduzir isso.The send may be queued and retried when the connection returns. A retry could, in theory, duplicate the record; the system uses a transaction id to reduce that.El envío puede quedar en cola y reintentarse cuando vuelve la conexión. Un reenvío podría, en teoría, duplicar el registro; el sistema usa un identificador de transacción para reducir eso.
Acompanhar o envioTracking the sendSeguir el envío: O status técnico do despacho (enviado, em fila, com erro) pode ser acompanhado na central de dados / tracking de despachos do app — útil para suporte investigar um envio.The dispatch's technical status (sent, queued, errored) can be followed in the app's data center / dispatch tracking — useful for support to investigate a send.El estado técnico del despacho (enviado, en cola, con error) puede seguirse en el centro de datos / tracking de despachos de la app — útil para que soporte investigue un envío.

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

Criação de merchandising (DispatcherType.merchandisingCreation, serviceName CreateMerchan) é a transação de saída que registra o retrato de uma ordem de serviço de merchandising. É disparada pelo notifier da ordem de serviço quando o fluxo roda fora do CRM (usesWorkflowOutsideCrm), antes do envio da ordem de serviço em si. Payload enxuto: sem cálculo monetário, sem variantes, sem campos inertes de contrato. Merchandising creation (DispatcherType.merchandisingCreation, serviceName CreateMerchan) is the outbound transaction that records a merchandising service order's snapshot. It's fired by the service-order notifier when the flow runs outside the CRM (usesWorkflowOutsideCrm), before the service order itself is sent. Lean payload: no monetary computation, no variants, no inert contract fields. Creación de merchandising (DispatcherType.merchandisingCreation, serviceName CreateMerchan) es la transacción de salida que registra el retrato de una orden de servicio de merchandising. Se dispara desde el notifier de la orden de servicio cuando el flujo corre fuera del CRM (usesWorkflowOutsideCrm), antes del envío de la orden de servicio en sí. Payload compacto: sin cálculo monetario, sin variantes, sin campos inertes de contrato.

Payload enxutoLean payloadPayload compacto

7 chaves na raiz + typeParts (6 chaves por peça). Todos os valores vêm direto do input — o build() não calcula nada.7 root keys + typeParts (6 keys per piece). Every value comes straight from the input — build() computes nothing.7 claves en la raíz + typeParts (6 claves por pieza). Todos los valores vienen directo del input — el build() no calcula nada.

Uma variante sóSingle variantUna sola variante

Um único DispatcherType, um único serviceName, sem prefixo Promo_ (hasPromotion: false fixo).A single DispatcherType, a single serviceName, no Promo_ prefix (hasPromotion: false fixed).Un único DispatcherType, un único serviceName, sin prefijo Promo_ (hasPromotion: false fijo).

RPC genéricoGeneric RPCRPC genérico

Como toda transação, passa pelo mesmo sendTransaction, com o JSON serializado em message e CreateMerchan como discriminador.Like every transaction, it goes through the same sendTransaction, with the JSON serialized into message and CreateMerchan as the discriminator.Como toda transacción, pasa por el mismo sendTransaction, con el JSON serializado en message y CreateMerchan como discriminador.

FontesSourcesFuentes BuildMerchandisingCreationDispatcherPayloadUseCase + MerchandisingCreationDispatcherPayloadInput + DispatcherType + DispatcherConectaRep.proto. O input carrega entities cruas de domínio (CLAUDE.md §36); o build() só renomeia e serializa. BuildMerchandisingCreationDispatcherPayloadUseCase + MerchandisingCreationDispatcherPayloadInput + DispatcherType + DispatcherConectaRep.proto. The input carries raw domain entities (CLAUDE.md §36); build() only renames and serializes. BuildMerchandisingCreationDispatcherPayloadUseCase + MerchandisingCreationDispatcherPayloadInput + DispatcherType + DispatcherConectaRep.proto. El input lleva entities crudas de dominio (CLAUDE.md §36); el build() solo renombra y serializa.

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. TODA transação de escrita do app usa este mesmo sendTransaction; o que muda é o serviceName (discriminador) e o JSON dentro de message. Aqui o serviceName é CreateMerchan.The service exposes a single generic RPC — there's no per-transaction message. EVERY write transaction in the app uses this same sendTransaction; what changes is the serviceName (discriminator) and the JSON inside message. Here the serviceName is CreateMerchan.El servicio expone un único RPC genérico — no existe mensaje por transacción. TODA transacción de escritura de la app usa este mismo sendTransaction; lo que cambia es el serviceName (discriminador) y el JSON dentro de message. Aquí el serviceName es CreateMerchan.

sendTransactionunary

MétodoMethodMétodo

rpc sendTransaction(InboxTransactionRequest) returns (InboxTransactionReply)

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

Request · InboxTransactionRequest

endpoint: string · #1 · endpoint alvo (config de ambiente)target endpoint (environment config)endpoint destino (config de ambiente)
serviceName: string · #2 · discriminador — CreateMerchan (sem prefixo Promo_)discriminator — CreateMerchan (no Promo_ prefix)discriminador — CreateMerchan (sin prefijo Promo_)
dateReference: string · #3 · AAAA-MM-DD do envio (formatDate(submittedAt))YYYY-MM-DD of the submission (formatDate(submittedAt))AAAA-MM-DD del envío (formatDate(submittedAt))
transactionReference: string · #4 · vazio (envelope não preenche)empty (envelope leaves it blank)vacío (el envelope no lo completa)
username: string · #5
message: string · #6 · o payload JSON serializado (a tabela da seção 07)the JSON payload serialized (the table in section 07)el payload JSON serializado (la tabla de la sección 07)
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 = sucesso)ack status (0 = success)status del ack (0 = éxito)
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, serviceName, payload, account, dateReference). Aqui transactionReference e tid ficam no default do envelope. O DispatcherGateway serializa payload em JSON para message, copia serviceName/dateReference, preenche os campos de dispositivo e o bearer token de auth, e chama o RPC. The builder returns a DispatcherEnvelope (type, serviceName, payload, account, dateReference). Here transactionReference and tid keep the envelope default. The DispatcherGateway serializes payload to JSON into message, copies serviceName/dateReference, fills in the device fields and the auth bearer token, and calls the RPC. El builder devuelve un DispatcherEnvelope (type, serviceName, payload, account, dateReference). Aquí transactionReference y tid quedan en el default del envelope. El DispatcherGateway serializa payload a JSON en message, copia serviceName/dateReference, completa los campos del dispositivo y el bearer token de auth, y llama al RPC.

destination = none (sem roteamento externo específico) e resendMayDuplicate == true: um reenvio (ex.: recuperação de fila offline) pode duplicar o registro; a idempotência via tid é o que mitiga isso.destination = none (no specific external routing) and resendMayDuplicate == true: a resend (e.g. offline-queue recovery) may duplicate the record; idempotency via tid is what mitigates it.destination = none (sin ruteo externo específico) y resendMayDuplicate == true: un reenvío (p. ej. recuperación de cola offline) puede duplicar el registro; la idempotencia vía tid es lo que lo mitiga.

Como é disparadoHow it's firedCómo se dispara

A transação é orquestrada pelo notifier da ordem de serviço de merchandising. O notifier apenas reúne entities cruas (representante de vendas, varejo, peças) e valores injetados (rótulos, relógio, fotos em base64); o builder é o dono único do rename e da serialização. A cascata:The transaction is orchestrated by the merchandising service-order notifier. The notifier only gathers raw entities (sales rep, retail, pieces) and injected values (labels, clock, base64 photos); the builder is the sole owner of the rename and serialization. The cascade:La transacción se orquesta desde el notifier de la orden de servicio de merchandising. El notifier solo reúne entities crudas (representante de ventas, punto de venta, piezas) y valores inyectados (etiquetas, reloj, fotos en base64); el builder es el dueño único del rename y la serialización. La cascada:

MerchandisingServiceOrderNotifiersubmitServiceOrder()
- reúne entities cruas + injetadosgathers raw entities + injectedreúne entities crudas + inyectadosMerchandisingCreationDispatcherPayloadInput
  - build()BuildMerchandisingCreationDispatcherPayloadUseCasemonta o wireassembles the wirearma el wire
    - devolvereturnsdevuelveDispatcherEnvelope
      - SubmitMerchandisingServiceOrderUseCaseDispatcherRepository
        
        serializa + authserialize + authserializa + authDispatcherGateway
        
        sendTransactionBackendgRPC

O notifier dispara dois envelopes em sequência pelo mesmo SubmitMerchandisingServiceOrderUseCase: primeiro este (creationEnvelope) — se falhar, só loga merchandisingCreationRecordFailed e não aborta —; depois o serviceOrderEnvelope da Ordem de serviço, cujo resultado decide a conclusão. Só percorre este caminho quando usesWorkflowOutsideCrm; caso contrário o notifier dispara o rastreamento de ativos (Asset item tracking).The notifier fires two envelopes in sequence through the same SubmitMerchandisingServiceOrderUseCase: first this one (creationEnvelope) — on failure it only logs merchandisingCreationRecordFailed and doesn't abort —; then the Service order's serviceOrderEnvelope, whose result decides completion. It only takes this path when usesWorkflowOutsideCrm; otherwise the notifier fires asset tracking (Asset item tracking).El notifier dispara dos envelopes en secuencia por el mismo SubmitMerchandisingServiceOrderUseCase: primero este (creationEnvelope) — si falla, solo registra merchandisingCreationRecordFailed y no aborta —; luego el serviceOrderEnvelope de la Orden de servicio, cuyo resultado decide la conclusión. Solo recorre este camino cuando usesWorkflowOutsideCrm; de lo contrario el notifier dispara el rastreo de activos (Asset item tracking).

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

MerchandisingCreationDispatcherPayloadInput (Freezed). Carrega o dado como existe no domínio; nada de formato wire. Os rótulos (activityLabel/serviceLabel/reasonLabel) já vêm resolvidos do State (.label das seleções); as fotos chegam como base64 lidas pelo FileCaptureService; o relógio como submittedAt (DateTimeUtils.now()).MerchandisingCreationDispatcherPayloadInput (Freezed). Carries data as it exists in the domain; no wire shaping. The labels (activityLabel/serviceLabel/reasonLabel) arrive already resolved from the State (the selections' .label); the photos come as base64 read by FileCaptureService; the clock as submittedAt (DateTimeUtils.now()).MerchandisingCreationDispatcherPayloadInput (Freezed). Lleva el dato como existe en el dominio; nada de formato wire. Las etiquetas (activityLabel/serviceLabel/reasonLabel) ya vienen resueltas del State (el .label de las selecciones); las fotos llegan como base64 leídas por FileCaptureService; el reloj como submittedAt (DateTimeUtils.now()).

CampoFieldCampo	TipoTypeTipo	PapelRoleRol
`resource`	`ResourceEntity`	representante de vendas (cru — o builder usa `resource.sfid`)sales rep (raw — the builder uses `resource.sfid`)representante de ventas (crudo — el builder usa `resource.sfid`)
`account`	`AccountDataEntity`	varejo (`sfid`, `customerCode`, `name`) — vem de `VisitEntity.accountData`retail (`sfid`, `customerCode`, `name`) — from `VisitEntity.accountData`punto de venta (`sfid`, `customerCode`, `name`) — viene de `VisitEntity.accountData`
`visitSfid`	`String`	→ `visitId`
`activityLabel`	`String`	→ `activityType` (`selectedActivity.label`)→ `activityType` (`selectedActivity.label`)→ `activityType` (`selectedActivity.label`)
`serviceLabel`	`String`	→ `serviceType` (`selectedService?.label ?? ""`)→ `serviceType` (`selectedService?.label ?? ""`)→ `serviceType` (`selectedService?.label ?? ""`)
`reasonLabel`	`String`	→ `reasonType` (`selectedReason?.label ?? ""`)→ `reasonType` (`selectedReason?.label ?? ""`)→ `reasonType` (`selectedReason?.label ?? ""`)
`pieces`	`List<MerchandisingServiceOrderPieceInput>`	→ `typeParts` (uma entrada por peça)→ `typeParts` (one entry per piece)→ `typeParts` (una entrada por pieza)
`submittedAt`	`DateTime`	→ `dateReference` (`DateTimeUtils.now()`)→ `dateReference` (`DateTimeUtils.now()`)→ `dateReference` (`DateTimeUtils.now()`)

Cada MerchandisingServiceOrderPieceInput carrega asset (MerchandisingAssetEntity), quantity (int), movement (MerchandisingMovement), comment (String) e imagesBase64 (List<String>). O input é compartilhado com a ordem de serviço; a Criação de merchandising usa só asset.type, asset.name, comment e imagesBase64 — quantity e movement são ignorados aqui (ver Pendências).Each MerchandisingServiceOrderPieceInput carries asset (MerchandisingAssetEntity), quantity (int), movement (MerchandisingMovement), comment (String) and imagesBase64 (List<String>). The input is shared with the service order; Merchandising creation uses only asset.type, asset.name, comment and imagesBase64 — quantity and movement are ignored here (see Pending).Cada MerchandisingServiceOrderPieceInput lleva asset (MerchandisingAssetEntity), quantity (int), movement (MerchandisingMovement), comment (String) e imagesBase64 (List<String>). El input es compartido con la orden de servicio; la Creación de merchandising usa solo asset.type, asset.name, comment e imagesBase64 — quantity y movement se ignoran aquí (ver Pendientes).

Payload (`message`)

O JSON serializado no campo message do request. Cada tabela abaixo tem 4 colunas — Campo JSON · Tipo · Origem do Dado · Regra — e lista toda chave que o build() emite (13 no total: 7 na raiz + 6 por peça em typeParts). 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. Each table below has 4 columns — JSON field · Type · Data source · Rule — and lists every key that build() emits (13 total: 7 at the root + 6 per piece in typeParts). 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. Cada tabla abajo tiene 4 columnas — Campo JSON · Tipo · Origen del Dato · Regla — y lista toda clave que build() emite (13 en total: 7 en la raíz + 6 por pieza en typeParts). 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
`activityType`	string	`input.activityLabel`	rótulo da atividade selecionada (`selectedActivity.label`)selected activity's label (`selectedActivity.label`)etiqueta de la actividad seleccionada (`selectedActivity.label`)
`serviceType`	string	`input.serviceLabel`	rótulo do serviço; `""` se nenhum selecionadoservice label; `""` if none selectedetiqueta del servicio; `""` si ninguno seleccionado
`reasonType`	string	`input.reasonLabel`	rótulo do motivo; `""` se nenhum selecionadoreason label; `""` if none selectedetiqueta del motivo; `""` si ninguno seleccionado
`accountUuid`	string	`input.account.sfid`	SFID do varejoretail SFIDSFID del punto de venta
`repSfid`	string	`input.resource.sfid`	SFID do representante de vendassales rep SFIDSFID del representante de ventas
`visitId`	string	`input.visitSfid`	SFID da visita em que o serviço ocorreuSFID of the visit the service happened inSFID de la visita en que ocurrió el servicio
`typeParts`	array	`input.pieces`	uma entrada por peça selecionada (ver tabela abaixo)one entry per selected piece (see table below)una entrada por pieza seleccionada (ver tabla abajo)

typeParts por peçaper piecepor pieza 6 camposfieldscampos

Uma entrada por MerchandisingServiceOrderPieceInput em input.pieces. As três chaves de imagem são posicionais: mapeiam os índices 0, 1 e 2 de imagesBase64; ausentes viram "".One entry per MerchandisingServiceOrderPieceInput in input.pieces. The three image keys are positional: they map indices 0, 1 and 2 of imagesBase64; missing ones become "".Una entrada por MerchandisingServiceOrderPieceInput en input.pieces. Las tres claves de imagen son posicionales: mapean los índices 0, 1 y 2 de imagesBase64; las ausentes se vuelven "".

Campo JSON	TipoTypeTipo	Origem do DadoData sourceOrigen del Dato	RegraRuleRegla
`name`	string	`piece.asset.type`	tipo do ativo de merchandisingmerchandising asset typetipo del activo de merchandising
`description`	string	`piece.asset.name`	nome do ativoasset namenombre del activo
`imageBase1`	string	`piece.imagesBase64[0]`	1ª foto base64; `""` se não houver1st base64 photo; `""` if none1ª foto base64; `""` si no hay
`imageBase2`	string	`piece.imagesBase64[1]`	2ª foto base64; `""` se houver < 22nd base64 photo; `""` if < 22ª foto base64; `""` si hay < 2
`imageBase3`	string	`piece.imagesBase64[2]`	3ª foto base64; `""` se houver < 3. Fotos além da 3ª são descartadas (ver Pendências)3rd base64 photo; `""` if < 3. Photos beyond the 3rd are dropped (see Pending)3ª foto base64; `""` si hay < 3. Fotos más allá de la 3ª se descartan (ver Pendientes)
`comments`	string	`piece.comment`	comentário da peça (default `""`)piece comment (default `""`)comentario de la pieza (default `""`)

Regras de negócioBusiness rulesReglas de negocio

Quando é disparadaWhen it firesCuándo se dispara usesWorkflowOutsideCrm

submitServiceOrder() ramifica por usesWorkflowOutsideCrm:submitServiceOrder() branches on usesWorkflowOutsideCrm:submitServiceOrder() se ramifica por usesWorkflowOutsideCrm:

usesWorkflowOutsideCrm == true → dispara esta Criação de merchandising (creationEnvelope) e, na sequência, a Ordem de serviço.usesWorkflowOutsideCrm == true → fires this Merchandising creation (creationEnvelope) and, right after, the Service order.usesWorkflowOutsideCrm == true → dispara esta Creación de merchandising (creationEnvelope) y, enseguida, la Orden de servicio.
false → dispara o rastreamento de ativos (Asset item tracking); a Criação de merchandising não é enviada.false → fires asset tracking (Asset item tracking); Merchandising creation is not sent.false → dispara el rastreo de activos (Asset item tracking); la Creación de merchandising no se envía.

Envio complementar (best-effort)Complementary send (best-effort)Envío complementario (best-effort) merchandisingCreationRecordFailed

A Criação de merchandising é o primeiro dos dois envelopes e é tratada como best-effort: se o SubmitMerchandisingServiceOrderUseCase retornar erro para ela, o notifier apenas registra LogEvents.merchandisingCreationRecordFailed() e segue para o segundo envelope. Quem decide sucesso/falha da conclusão é a Ordem de serviço (segundo envelope).Merchandising creation is the first of the two envelopes and is treated as best-effort: if SubmitMerchandisingServiceOrderUseCase returns an error for it, the notifier just logs LogEvents.merchandisingCreationRecordFailed() and proceeds to the second envelope. What decides success/failure of completion is the Service order (second envelope).La Creación de merchandising es el primero de los dos envelopes y se trata como best-effort: si SubmitMerchandisingServiceOrderUseCase devuelve error para ella, el notifier solo registra LogEvents.merchandisingCreationRecordFailed() y continúa al segundo envelope. Quien decide éxito/falla de la conclusión es la Orden de servicio (segundo envelope).

Rótulos, não códigosLabels, not codesEtiquetas, no códigos activityType · serviceType · reasonType

Diferente da Ordem de serviço (que envia activityCode/serviceCode/reasonCode), a Criação de merchandising envia os rótulos legíveis (.label) da atividade, do serviço e do motivo — não os códigos. É um registro descritivo, não um comando estruturado.Unlike the Service order (which sends activityCode/serviceCode/reasonCode), Merchandising creation sends the human-readable labels (.label) of the activity, service and reason — not the codes. It's a descriptive record, not a structured command.A diferencia de la Orden de servicio (que envía activityCode/serviceCode/reasonCode), la Creación de merchandising envía las etiquetas legibles (.label) de la actividad, el servicio y el motivo — no los códigos. Es un registro descriptivo, no un comando estructurado.

Imagens posicionais (máx. 3)Positional images (max 3)Imágenes posicionales (máx. 3) imageBase1 · imageBase2 · imageBase3

As fotos vêm em piece.imagesBase64 (base64 lido pelo FileCaptureService) e são mapeadas posicionalmente para três chaves fixas: índice 0 → imageBase1, 1 → imageBase2, 2 → imageBase3.Photos come in piece.imagesBase64 (base64 read by FileCaptureService) and are mapped positionally to three fixed keys: index 0 → imageBase1, 1 → imageBase2, 2 → imageBase3.Las fotos vienen en piece.imagesBase64 (base64 leído por FileCaptureService) y se mapean posicionalmente a tres claves fijas: índice 0 → imageBase1, 1 → imageBase2, 2 → imageBase3.
Índice ausente → "" (lista mais curta que 3 preenche o resto com vazio).Missing index → "" (a list shorter than 3 fills the rest with empty).Índice ausente → "" (una lista más corta que 3 completa el resto con vacío).
O contrato só tem 3 slots: uma 4ª foto ou além é silenciosamente descartada (ver Pendências).The contract has only 3 slots: a 4th photo or beyond is silently dropped (see Pending).El contrato solo tiene 3 slots: una 4ª foto o más es silenciosamente descartada (ver Pendientes).

Sem cálculo, sem filtroNo computation, no filterSin cálculo, sin filtro build() 1:1

O build() é uma projeção direta: nenhum arredondamento, nenhuma derivação, nenhum trim(), nenhum campo inerte de contrato. Toda peça de input.pieces vira uma entrada de typeParts — não há filtro por quantidade, movimento ou peça vazia (diferente da Ordem de serviço, que compõe/aparra mensagem e filtra comentários vazios).build() is a direct projection: no rounding, no derivation, no trim(), no inert contract field. Every piece in input.pieces becomes a typeParts entry — there's no filter by quantity, movement or empty piece (unlike the Service order, which composes/trims a message and filters empty comments).El build() es una proyección directa: sin redondeo, sin derivación, sin trim(), sin campo inerte de contrato. Toda pieza de input.pieces se vuelve una entrada de typeParts — no hay filtro por cantidad, movimiento o pieza vacía (a diferencia de la Orden de servicio, que compone/recorta mensaje y filtra comentarios vacíos).

Pendências / roadmapPending / roadmapPendientes / roadmap

O que o builder ainda não aproveita ou onde o contrato limita, documentado fiel ao estado atual do código (nunca descrito como se já existisse):What the builder does not yet leverage, or where the contract limits, documented faithfully to the current code state (never described as already existing):Lo que el builder aún no aprovecha, o dónde el contrato limita, documentado fiel al estado actual del código (nunca descrito como si ya existiera):

Não aproveitado / limitadoNot leveraged / limitedNo aprovechado / limitado

piece.quantity e piece.movement: presentes no input (compartilhado com a Ordem de serviço) mas ignorados por esta transação — só a Ordem de serviço os emite (quantity, movement.wireValue).piece.quantity and piece.movement: present on the input (shared with the Service order) but ignored by this transaction — only the Service order emits them (quantity, movement.wireValue).piece.quantity y piece.movement: presentes en el input (compartido con la Orden de servicio) pero ignorados por esta transacción — solo la Orden de servicio los emite (quantity, movement.wireValue).
Imagens: o contrato tem apenas 3 slots (imageBase1..3). Uma 4ª foto ou além em imagesBase64 é descartada sem aviso — não há campo/lista para elas.Images: the contract has only 3 slots (imageBase1..3). A 4th photo or beyond in imagesBase64 is dropped without warning — there's no field/list for them.Imágenes: el contrato tiene solo 3 slots (imageBase1..3). Una 4ª foto o más en imagesBase64 se descarta sin aviso — no hay campo/lista para ellas.
Sem trim(): comments vai cru; um comentário só com espaços é enviado como está (a Ordem de serviço, ao contrário, apara e filtra vazios).No trim(): comments ships raw; a whitespace-only comment is sent as-is (the Service order, by contrast, trims and filters empties).Sin trim(): comments va crudo; un comentario solo con espacios se envía tal cual (la Orden de servicio, en cambio, recorta y filtra vacíos).
Transporte: deviceUuid vai como literal provisório no gateway (pendência conhecida do Dispatcher).Transport: deviceUuid ships as a provisional literal in the gateway (known Dispatcher pending item).Transporte: deviceUuid va como literal provisional en el gateway (pendiente conocido del Dispatcher).

Transações irmãsSister transactionsTransacciones hermanas Domínio de merchandising (BR): 18 · Ordem de serviço (par desta, compartilha o input de peças), 16 · Asset item tracking (caminho alternativo), 13 · Image recognition e 17 · Annotation. Merchandising domain (BR): 18 · Service order (this one's pair, shares the piece input), 16 · Asset item tracking (alternate path), 13 · Image recognition and 17 · Annotation. Dominio de merchandising (BR): 18 · Orden de servicio (par de esta, comparte el input de piezas), 16 · Asset item tracking (camino alternativo), 13 · Image recognition y 17 · Annotation.

★

MercadosMarketsMercados

A disponibilidade da transação vem do DispatcherType.merchandisingCreation.enabledMarkets = [BR]. É uma transação só do Brasil; os demais mercados não a listam e não a disparam.Transaction availability comes from DispatcherType.merchandisingCreation.enabledMarkets = [BR]. It's a Brazil-only transaction; the other markets don't list it and don't fire it.La disponibilidad de la transacción viene de DispatcherType.merchandisingCreation.enabledMarkets = [BR]. Es una transacción solo de Brasil; los demás mercados no la listan y no la disparan.

BRx CL— ZA— AR— PY— PE—

disponívelavailabledisponible presente, desligadopresent, offpresente, apagado ausenteabsentausente

Só no BrasilBrazil onlySolo Brasil Toda a ordem de serviço de merchandising com fluxo fora do CRM (usesWorkflowOutsideCrm) é um cenário exclusivo do Brasil. O destination é none (sem roteamento externo específico) — mesmo padrão das outras transações de merchandising BR. The whole merchandising service order with an outside-CRM flow (usesWorkflowOutsideCrm) is a Brazil-exclusive scenario. The destination is none (no specific external routing) — same pattern as the other BR merchandising transactions. Toda la orden de servicio de merchandising con flujo fuera del CRM (usesWorkflowOutsideCrm) es un escenario exclusivo de Brasil. El destination es none (sin ruteo externo específico) — mismo patrón de las otras transacciones de merchandising BR.

CL · ZA · AR · PY · PE Existem como mercados do app, mas não têm a transação de Criação de merchandising — enabledMarkets lista apenas BR. Nesses mercados a ordem de serviço de merchandising com fluxo fora do CRM não é disparada. They exist as app markets, but don't have the Merchandising creation transaction — enabledMarkets lists only BR. In these markets the outside-CRM merchandising service order is not fired. Existen como mercados de la app, pero no tienen la transacción de Creación de merchandising — enabledMarkets lista solo BR. En estos mercados la orden de servicio de merchandising con flujo fuera del CRM no se dispara.