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

Coleta de pagamentoPayment collectionCobro de pago

A transação de escrita que registra no backend os pagamentos coletados de um varejo contra seus itens de dívida em aberto. Um único builder monta um payload JSON de uma única variante — um array Payment com uma perna por (método → porção de débito → referência de cobrança) — cobrindo dinheiro, cheque, transferência e nota de crédito. Toda a construção do contrato wire vive no builder. The write transaction that records to the backend the payments collected from a retail against its open debit items. A single builder assembles a JSON payload of one single variant — a Payment array with one leg per (method → debit portion → collection reference) — covering cash, cheque, transfer and credit note. All wire-contract construction lives in the builder. La transacción de escritura que registra en el backend los pagos cobrados de un punto de venta contra sus ítems de deuda abierta. Un único builder arma un payload JSON de una única variante — un array Payment con una pierna por (método → porción de deuda → referencia de cobro) — cubriendo efectivo, cheque, transferencia y nota de crédito. Toda la construcción del contrato wire vive en el builder.

PúblicoAudiencePúblico

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

CamadaLayerCapa

Escrita · DispatcherWrite · DispatcherEscritura · Dispatcher

RelacionadoRelatedRelacionado

Payment creation · Financial management

AtualizadoUpdatedActualizado

18/08/20262026-08-18

Disponível emAvailable inDisponible en BR CL

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

Um varejo tem contas em aberto (dívidas a pagar). Quando o representante de vendas registra que recebeu um pagamento — em dinheiro, cheque, transferência, cartão ou usando uma nota de crédito — o app envia esse recebimento ao backend por esta transação. É o que dá baixa na dívida: informa quanto foi coletado, por qual meio e contra quais itens em aberto. A retail has open items (debts to pay). When the sales rep records a payment received — cash, cheque, transfer, card or using a credit note — the app sends that collection to the backend through this transaction. It's what settles the debt: it reports how much was collected, by which means and against which open items. Un punto de venta tiene ítems abiertos (deudas por pagar). Cuando el representante de ventas registra un pago recibido — efectivo, cheque, transferencia, tarjeta o usando una nota de crédito — la app envía ese cobro al backend por esta transacción. Es lo que salda la deuda: informa cuánto se cobró, por qué medio y contra qué ítems abiertos.

Um único registro pode combinar vários métodos e cobrir vários débitos de uma vez. O app reparte o valor de cada método entre os débitos escolhidos e gera uma perna de pagamento para cada combinação. Os métodos aparecem em três grandes formas:A single record can combine several methods and cover several debts at once. The app splits each method's amount across the chosen debts and produces one payment leg per combination. The methods come in three broad forms:Un solo registro puede combinar varios métodos y cubrir varias deudas a la vez. La app reparte el monto de cada método entre las deudas elegidas y genera una pierna de pago por combinación. Los métodos aparecen en tres grandes formas:

Dinheiro / cartãoCash / cardEfectivo / tarjeta

Pagamento à vista, sem dados bancários — o valor entra direto contra o débito.On-the-spot payment, no bank details — the amount goes straight against the debit.Pago al contado, sin datos bancarios — el monto va directo contra la deuda.

Cheque / transferênciaCheque / transferCheque / transferencia

Carrega dados de banco e agência, uma referência de cobrança e, no cheque, a data.Carries bank and branch data, a collection reference and, for a cheque, the date.Lleva datos de banco y sucursal, una referencia de cobro y, en el cheque, la fecha.

Nota de créditoCredit noteNota de crédito

Usa o saldo de uma ou mais notas de crédito do varejo — cada nota vira uma perna própria.Uses the balance of one or more of the retail's credit notes — each note becomes its own leg.Usa el saldo de una o más notas de crédito del punto de venta — cada nota se vuelve una pierna propia.

Um gesto, várias pernasOne gesture, several legsUn gesto, varias piernas Para o rep, o gesto é um só — informar o que foi pago. Nos bastidores, o app pode gerar várias pernas de pagamento a partir de um único registro, e todas viajam juntas neste envio. For the rep, it's a single gesture — report what was paid. Behind the scenes, the app may produce several payment legs from one record, and they all travel together in this send. Para el rep, el gesto es uno solo — informar lo que se pagó. Tras bambalinas, la app puede generar varias piernas de pago a partir de un solo registro, y todas viajan juntas en este envío.

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

A transação é o último passo do registro de pagamento. As telas do caminho pertencem às features de Criação de pagamentos e Gestão financeira; aqui só situamos onde o envio acontece:The transaction is the last step of recording a payment. The screens along the way belong to the Payment creation and Financial management features; here we only place where the send happens:La transacción es el último paso del registro de pago. Las pantallas del camino pertenecen a las features de Creación de pagos y Gestión financiera; aquí solo situamos dónde ocurre el envío:

Itens em aberto do varejoRetail's open itemsÍtems abiertos del punto de ventaNa Gestão financeira, o rep vê as dívidas em aberto e escolhe uma ou mais para receber.In Financial management, the rep sees the open debts and picks one or more to collect.En Gestión financiera, el rep ve las deudas abiertas y elige una o más para cobrar.
Escolha dos métodosChoose the methodsElegir los métodosAdiciona um ou mais métodos (dinheiro, cheque, transferência, cartão, nota de crédito) e o valor de cada um.Adds one or more methods (cash, cheque, transfer, card, credit note) and each one's amount.Agrega uno o más métodos (efectivo, cheque, transferencia, tarjeta, nota de crédito) y el monto de cada uno.
Dados por métodoPer-method detailsDatos por métodoPreenche banco/agência, referência de cobrança e data quando o método pede; na nota de crédito, seleciona quais notas usar.Fills bank/branch, collection reference and date when the method asks; for a credit note, selects which notes to use.Completa banco/sucursal, referencia de cobro y fecha cuando el método lo pide; en la nota de crédito, selecciona qué notas usar.
ConfirmaçãoConfirmationConfirmaciónRevisa o total coletado e o saldo restante frente aos débitos.Reviews the collected total and the remaining balance against the debts.Revisa el total cobrado y el saldo restante frente a las deudas.
Enviar → esta transaçãoSend → this transactionEnviar → esta transacciónAo confirmar o registro, o app dispara a Coleta de pagamento. É este toque que aciona a transação.On confirming the record, the app fires Payment collection. This tap is what triggers the transaction.Al confirmar el registro, la app dispara el Cobro de pago. Este toque es lo que activa la transacción.

Transação irmãSister transactionTransacción hermana Além do valor coletado, o rep pode anexar um comprovante (foto/arquivo) a um item em aberto — isso é um envio separado, documentado em 22 · Comprovante de pagamento. O fechamento de caixa do dia é a 24 · Relatório de caixa. Besides the collected amount, the rep can attach a proof (photo/file) to an open item — that's a separate send, documented in 22 · Proof of payment. The day's cash close-out is 24 · Cash payment report. Además del monto cobrado, el rep puede adjuntar un comprobante (foto/archivo) a un ítem abierto — eso es un envío separado, documentado en 22 · Comprobante de pago. El cierre de caja del día es el 24 · Informe de caja.

Depois do envioAfter sendingDespués del envío

Confirmação ao repConfirmation to the repConfirmación al rep: Quando o backend aceita, o pagamento fica registrado contra o(s) item(ns) de dívida, que passam a refletir o valor recebido na Gestão financeira do varejo.When the backend accepts it, the payment is recorded against the debit item(s), which then reflect the amount received in the retail's Financial management.Cuando el backend lo acepta, el pago queda registrado contra el/los ítem(s) de deuda, que reflejan el monto recibido en la Gestión financiera del punto de venta.
Sem internetOfflineSin internet: O envio pode entrar em fila e ser reenviado quando a conexão volta — o registro não se perde. Um reenvio pode, em tese, duplicar; o sistema usa um identificador de transação para evitar isso.The send may be queued and retried when the connection returns — the record isn't lost. A retry could, in theory, duplicate; the system uses a transaction id to avoid that.El envío puede quedar en cola y reintentarse cuando vuelve la conexión — el registro no se pierde. Un reenvío podría, en teoría, duplicar; el sistema usa un identificador de transacción para evitarlo.
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 recebimento.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 collection.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 cobro.

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

Coleta de pagamento é a transação de saída que registra no backend os pagamentos coletados de um varejo contra seus itens de dívida em aberto (DPI). É disparada pelo fluxo de registro de pagamento. Uma única variante — não há campo de tipo, não há prefixo Promo_ — com destino salesforce. Payment collection is the outbound transaction that records to the backend the payments collected from a retail against its open debit items (DPI). It's fired by the payment-recording flow. A single variant — no type field, no Promo_ prefix — with salesforce destination. Cobro de pago es la transacción de salida que registra en el backend los pagos cobrados de un punto de venta contra sus ítems de deuda abierta (DPI). Se dispara desde el flujo de registro de pago. Una única variante — sin campo de tipo, sin prefijo Promo_ — con destino salesforce.

Array de pernasArray of legsArray de piernas

Um único array Payment com N objetos de 12 campos: uma perna por (método → porção de débito → referência de cobrança).A single Payment array with N 12-field objects: one leg per (method → debit portion → collection reference).Un único array Payment con N objetos de 12 campos: una pierna por (método → porción de deuda → referencia de cobro).

Alocação no builderAllocation in the builderAsignación en el builder

O draft.allocate() reparte o valor de cada método entre os débitos; o builder itera as porções e emite uma perna por referência de cobrança.draft.allocate() splits each method's amount across the debits; the builder iterates the portions and emits one leg per collection reference.draft.allocate() reparte el monto de cada método entre las deudas; el builder itera las porciones y emite una pierna por referencia de cobro.

RPC genéricoGeneric RPCRPC genérico

Não há RPC por pagamento: tudo passa pelo mesmo sendTransaction, com o JSON serializado em message e serviceName = PaymentCollectionAPI.There's no per-payment RPC: everything goes through the same sendTransaction, with the JSON serialized into message and serviceName = PaymentCollectionAPI.No hay RPC por pago: todo pasa por el mismo sendTransaction, con el JSON serializado en message y serviceName = PaymentCollectionAPI.

FontesSourcesFuentes BuildPaymentCollectionDispatcherPayloadUseCase + PaymentCollectionDispatcherPayloadInput + DispatcherType.payment + DispatcherConectaRep.proto. O input carrega entities cruas de domínio (CLAUDE.md §36); o build() constrói todo o wire. BuildPaymentCollectionDispatcherPayloadUseCase + PaymentCollectionDispatcherPayloadInput + DispatcherType.payment + DispatcherConectaRep.proto. The input carries raw domain entities (CLAUDE.md §36); build() constructs the entire wire. BuildPaymentCollectionDispatcherPayloadUseCase + PaymentCollectionDispatcherPayloadInput + DispatcherType.payment + DispatcherConectaRep.proto. El input lleva entities crudas de dominio (CLAUDE.md §36); 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. TODA transação de escrita do app usa este mesmo sendTransaction; o que muda é o serviceName (discriminador) e o JSON dentro de message.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.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.

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 — PaymentCollectionAPI (sem prefixo Promo_: hasPromotion é sempre false)discriminator — PaymentCollectionAPI (no Promo_ prefix: hasPromotion is always false)discriminador — PaymentCollectionAPI (sin prefijo Promo_: hasPromotion siempre es false)
dateReference: string · #3 · AAAA-MM-DD do envio (submissionDate, de input.submittedAt)YYYY-MM-DD of the submission (submissionDate, from input.submittedAt)AAAA-MM-DD del envío (submissionDate, de input.submittedAt)
transactionReference: string · #4 · draft.groupId (correlação de todas as pernas do envio)draft.groupId (correlation of all the send's legs)draft.groupId (correlación de todas las piernas del envío)
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 = 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 = {"Payment": […]}, 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. O account vem de input.accountSfid / accountSapCode / accountName. The builder returns a DispatcherEnvelope (type, serviceName, payload = {"Payment": […]}, 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. The account comes from input.accountSfid / accountSapCode / accountName. El builder devuelve un DispatcherEnvelope (type, serviceName, payload = {"Payment": […]}, 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. El account viene de input.accountSfid / accountSapCode / accountName.

O destino é DispatcherDestination.salesforce (default do DispatcherType.payment). resendMayDuplicate == true para payment: um reenvio (ex.: recuperação de fila offline) pode duplicar o registro; a idempotência via tid é o que mitiga isso.The destination is DispatcherDestination.salesforce (the DispatcherType.payment default). resendMayDuplicate == true for payment: a resend (e.g. offline-queue recovery) may duplicate the record; idempotency via tid is what mitigates it.El destino es DispatcherDestination.salesforce (default de DispatcherType.payment). resendMayDuplicate == true para payment: un reenvío (p. ej. recuperación de cola offline) puede duplicar el registro; la idempotencia vía tid es lo que lo mitiga.

serviceName

Uma única variante — um só DispatcherType, um só serviceName. Não há campo de tipo no input e não há prefixo Promo_ (o builder chama type.resolveServiceName(hasPromotion: false) fixo).A single variant — one DispatcherType, one serviceName. There's no type field on the input and no Promo_ prefix (the builder calls type.resolveServiceName(hasPromotion: false) fixed).Una única variante — un solo DispatcherType, un solo serviceName. No hay campo de tipo en el input y no hay prefijo Promo_ (el builder llama type.resolveServiceName(hasPromotion: false) fijo).

`DispatcherType`	`serviceName`	DestinoDestinationDestino	MercadosMarketsMercados
`payment`	`PaymentCollectionAPI`	`salesforce`	BR · CL

Como é disparadoHow it's firedCómo se dispara

A transação é disparada pelo fluxo de registro de pagamento. O notifier apenas reúne entities cruas e valores injetados; o builder é o dono único de todo o join, alocação, rename, formatação de data e derivação wire. A cascata:The transaction is fired by the payment-recording flow. The notifier only gathers raw entities and injected values; the builder is the sole owner of every join, allocation, rename, date formatting and wire derivation. The cascade:La transacción se dispara desde el flujo de registro de pago. El notifier solo reúne entities crudas y valores inyectados; el builder es el dueño único de todo el join, asignación, rename, formateo de fecha y derivación wire. La cascada:

Payment creationnotifier
- reúne draft + entities cruas + relógiogathers draft + raw entities + clockreúne draft + entities crudas + relojPaymentCollectionDispatcherPayloadInput
  - build()BuildPaymentCollectionDispatcherPayloadUseCasealoca + monta o wireallocates + assembles the wireasigna + arma el wire
    - devolvereturnsdevuelveDispatcherEnvelope
      - Submit…UseCaseDispatcherRepository
        
        serializa + authserialize + authserializa + authDispatcherGateway
        
        sendTransactionBackendgRPC

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

PaymentCollectionDispatcherPayloadInput (Freezed). Carrega o dado como existe no domínio; nada de formato wire. O relógio chega como submittedAt (via DateTimeUtils.now()); a alocação por débito é feita dentro do builder via draft.allocate().PaymentCollectionDispatcherPayloadInput (Freezed). Carries data as it exists in the domain; no wire shaping. The clock arrives as submittedAt (via DateTimeUtils.now()); the per-debit allocation is done inside the builder via draft.allocate().PaymentCollectionDispatcherPayloadInput (Freezed). Lleva el dato como existe en el dominio; nada de formato wire. El reloj llega como submittedAt (vía DateTimeUtils.now()); la asignación por deuda se hace dentro del builder vía draft.allocate().

CampoFieldCampo	TipoTypeTipo	PapelRoleRol
`draft`	`PaymentDraftEntity`	rascunho do pagamento: `groupId`, `debits` (dívidas alvo) e `methods` (métodos + valores + evidências). O builder chama `draft.allocate()` p/ repartir cada método entre os débitospayment draft: `groupId`, `debits` (target debts) and `methods` (methods + amounts + evidence). The builder calls `draft.allocate()` to split each method across the debitsborrador del pago: `groupId`, `debits` (deudas objetivo) y `methods` (métodos + montos + evidencia). El builder llama `draft.allocate()` para repartir cada método entre las deudas
`resource`	`ResourceEntity`	representante de vendas (cru — o builder deriva `resourceSfid` primary/secondary)sales rep (raw — the builder derives `resourceSfid` primary/secondary)representante de ventas (crudo — el builder deriva `resourceSfid` primary/secondary)
`accountSfid`	`String`	→ `account.sfid` do envelopeof the envelopedel envelope
`accountSapCode`	`String`	→ `account.sapCode`
`accountName`	`String`	→ `account.name`
`submittedAt`	`DateTime`	relógio injetado (`DateTimeUtils.now()`) — vira `paymentDate` (cada perna) e `dateReference`/`submissionDate`injected clock (`DateTimeUtils.now()`) — becomes `paymentDate` (each leg) and `dateReference`/`submissionDate`reloj inyectado (`DateTimeUtils.now()`) — se vuelve `paymentDate` (cada pierna) y `dateReference`/`submissionDate`

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 (1 na raiz + 12 por perna). Campo, Tipo e Origem são código cru; só a Regra é prosa. Um exemplo completo (2 pernas) 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 (1 at the root + 12 per leg). Field, Type and Source are raw code; only Rule is prose. A full example (2 legs) 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 (1 en la raíz + 12 por pierna). Campo, Tipo y Origen son código crudo; solo la Regla es prosa. Un ejemplo completo (2 piernas) 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
`Payment`	array	`payments`	uma entrada por (método → porção de débito → referência de cobrança); pode ter várias pernasone entry per (method → debit portion → collection reference); may hold several legsuna entrada por (método → porción de deuda → referencia de cobro); puede tener varias piernas

Payment por perna de pagamentoper payment legpor pierna de pago 12 camposfieldscampos

Campo JSON	TipoTypeTipo	Origem do DadoData sourceOrigen del Dato	RegraRuleRegla
`resourceSfid`	string	`resource`	`isPrimaryResource ? primaryResourceSfid : secondaryResourceSfidisPrimaryResource ? primaryResourceSfid : secondaryResourceSfidisPrimaryResource ? primaryResourceSfid : secondaryResourceSfid`
`amount`	double	`Calculado`	nota de crédito → `entry.amountForCollectionReference(cr)`; senão `debitAllocation.amount`. Arredondado 2 casas (`CurrencyUtils.roundToTwoDecimals`)credit note → `entry.amountForCollectionReference(cr)`; else `debitAllocation.amount`. Rounded 2 dp (`CurrencyUtils.roundToTwoDecimals`)nota de crédito → `entry.amountForCollectionReference(cr)`; si no `debitAllocation.amount`. Redondeado 2 dec (`CurrencyUtils.roundToTwoDecimals`)
`bankSfid`	string	`entry.bankSfid`	banco do método; `""` em métodos sem dados bancários (ex.: nota de crédito)the method's bank; `""` for methods without bank details (e.g. credit note)banco del método; `""` en métodos sin datos bancarios (p. ej. nota de crédito)
`branchSfid`	string	`entry.bankBranchSfid`	agência (chave `branchSfid` ← campo `bankBranchSfid`)branch (key `branchSfid` ← field `bankBranchSfid`)sucursal (clave `branchSfid` ← campo `bankBranchSfid`)
`paymentDate`	string	`input.submittedAt`	data do envio, `yyyy-MM-dd` (`DateTimeUtils.formatDate`, default `isoDate`)submission date, `yyyy-MM-dd` (`DateTimeUtils.formatDate`, default `isoDate`)fecha del envío, `yyyy-MM-dd` (`DateTimeUtils.formatDate`, default `isoDate`)
`collectionReference`	string	`Calculado`	por método: nota de crédito → `creditNote.creditNoteSfid`; senão `entry.collectionReference` (trim)per method: credit note → `creditNote.creditNoteSfid`; else `entry.collectionReference` (trimmed)por método: nota de crédito → `creditNote.creditNoteSfid`; si no `entry.collectionReference` (trim)
`paymentMode`	string	`entry.method.apiName`	rótulo do método (ex.: `"Cash"`, `"Pix"`, `"Cheque"`, `"Credit Note"`) — ver Enum `PaymentMethod`method label (e.g. `"Cash"`, `"Pix"`, `"Cheque"`, `"Credit Note"`) — see `PaymentMethod` enumetiqueta del método (p. ej. `"Cash"`, `"Pix"`, `"Cheque"`, `"Credit Note"`) — ver enum `PaymentMethod`
`debitOpenItemSfid`	string	`debitAllocation.debitOpenItemSfid`	item de dívida em aberto alvo desta porçãothe open debit item targeted by this portionítem de deuda abierta objetivo de esta porción
`groupId`	string	`draft.groupId`	id do grupo (correlaciona todas as pernas do envio)group id (correlates all the send's legs)id del grupo (correlaciona todas las piernas del envío)
`paymentIdMobile`	string	`entry.paymentIdMobile`	id de pagamento gerado no cliente (por método)client-generated payment id (per method)id de pago generado en cliente (por método)
`creditNoteSfid`	string	`Calculado`	nota de crédito → `collectionReference` (o sfid da NC); senão `""`credit note → `collectionReference` (the CN sfid); else `""`nota de crédito → `collectionReference` (el sfid de la NC); si no `""`
`chequeDate`	string	`entry.paymentDate`	`""` se `null`; senão `yyyy-MM-dd` (data do método, ex.: cheque)`""` if `null`; else `yyyy-MM-dd` (the method's date, e.g. cheque)`""` si `null`; si no `yyyy-MM-dd` (fecha del método, p. ej. cheque)

Regras de negócioBusiness rulesReglas de negocio

Alocação e explosão de pernasAllocation & leg fan-outAsignación y explosión de piernas allocate() · debitAllocations · collectionReferences

O builder itera draft.allocate(): cada PaymentMethodAllocationEntity repartiu o valor de um método (draft.methods[allocation.methodIndex]) entre os débitos, gerando porções (PaymentDebitAllocationEntity).The builder iterates draft.allocate(): each PaymentMethodAllocationEntity has split one method's amount (draft.methods[allocation.methodIndex]) across the debits, producing portions (PaymentDebitAllocationEntity).El builder itera draft.allocate(): cada PaymentMethodAllocationEntity repartió el monto de un método (draft.methods[allocation.methodIndex]) entre las deudas, generando porciones (PaymentDebitAllocationEntity).
Loop triplo → uma perna por combinação: por método × por porção de débito (allocation.debitAllocations) × por referência de cobrança (entry.collectionReferences).Triple loop → one leg per combination: per method × per debit portion (allocation.debitAllocations) × per collection reference (entry.collectionReferences).Loop triple → una pierna por combinación: por método × por porción de deuda (allocation.debitAllocations) × por referencia de cobro (entry.collectionReferences).
entry.collectionReferences é um getter: para nota de crédito, é a lista de creditNote.creditNoteSfid; para os demais, é [collectionReference.trim()] — ou lista vazia se a referência estiver em branco. Referência vazia num método comum ⇒ nenhuma perna emitida para aquele método.entry.collectionReferences is a getter: for a credit note it's the list of creditNote.creditNoteSfid; for the rest it's [collectionReference.trim()] — or an empty list if the reference is blank. A blank reference on a regular method ⇒ no leg emitted for that method.entry.collectionReferences es un getter: para nota de crédito es la lista de creditNote.creditNoteSfid; para los demás es [collectionReference.trim()] — o lista vacía si la referencia está en blanco. Referencia vacía en un método común ⇒ ninguna pierna emitida para ese método.

Nota de crédito vs método comumCredit note vs regular methodNota de crédito vs método común requiresCreditNoteSelection · amount · creditNoteSfid

isCreditNote = entry.method.requiresCreditNoteSelection — true apenas para PaymentMethod.creditNote (code Z9, apiName "Credit Note").isCreditNote = entry.method.requiresCreditNoteSelection — true only for PaymentMethod.creditNote (code Z9, apiName "Credit Note").isCreditNote = entry.method.requiresCreditNoteSelection — true solo para PaymentMethod.creditNote (code Z9, apiName "Credit Note").
Nota de crédito: amount = entry.amountForCollectionReference(cr) (o valor da NC casada por creditNoteSfid); creditNoteSfid = a própria collectionReference da perna.Credit note: amount = entry.amountForCollectionReference(cr) (the matched CN's value by creditNoteSfid); creditNoteSfid = the leg's own collectionReference.Nota de crédito: amount = entry.amountForCollectionReference(cr) (el valor de la NC casada por creditNoteSfid); creditNoteSfid = la propia collectionReference de la pierna.
Método comum: amount = debitAllocation.amount (a porção alocada àquele débito); creditNoteSfid = "".Regular method: amount = debitAllocation.amount (the portion allocated to that debit); creditNoteSfid = "".Método común: amount = debitAllocation.amount (la porción asignada a esa deuda); creditNoteSfid = "".

Rep, datas e moedaRep, dates & moneyRep, fechas y moneda resourceSfid · paymentDate · chequeDate · roundToTwoDecimals

resourceSfid: primary vs secondary decidido por resource.isPrimaryResource — o builder deriva o sfid do rep (nunca pré-resolvido no notifier, §25/§36).resourceSfid: primary vs secondary decided by resource.isPrimaryResource — the builder derives the rep sfid (never pre-resolved in the notifier, §25/§36).resourceSfid: primary vs secondary decidido por resource.isPrimaryResource — el builder deriva el sfid del rep (nunca pre-resuelto en el notifier, §25/§36).
Duas datas distintas: paymentDate = data do envio (submittedAt, igual em todas as pernas); chequeDate = data do método (entry.paymentDate, ex.: data do cheque), "" quando null. Ambas yyyy-MM-dd via DateTimeUtils (§14).Two distinct dates: paymentDate = the submission date (submittedAt, same on every leg); chequeDate = the method's date (entry.paymentDate, e.g. the cheque date), "" when null. Both yyyy-MM-dd via DateTimeUtils (§14).Dos fechas distintas: paymentDate = fecha del envío (submittedAt, igual en todas las piernas); chequeDate = fecha del método (entry.paymentDate, p. ej. la fecha del cheque), "" cuando null. Ambas yyyy-MM-dd vía DateTimeUtils (§14).
amount é a única aritmética monetária: arredondado com CurrencyUtils.roundToTwoDecimals (§15). Este build() não carrega cash fee nem lógica de pagamento à vista (à vista/cash fee são concerns do Envio de pedido, não da coleta).amount is the only monetary arithmetic: rounded with CurrencyUtils.roundToTwoDecimals (§15). This build() carries no cash fee nor pay-at-sight logic (pay-at-sight/cash fee are Order placement concerns, not collection).amount es la única aritmética monetaria: redondeado con CurrencyUtils.roundToTwoDecimals (§15). Este build() no lleva cash fee ni lógica de pago al contado (pago al contado/cash fee son concerns de Envío de pedido, no del cobro).
serviceName: fixo PaymentCollectionAPI — o builder chama type.resolveServiceName(hasPromotion: false), então nunca há prefixo Promo_. transactionReference e dateReference do envelope = draft.groupId e submissionDate.serviceName: fixed PaymentCollectionAPI — the builder calls type.resolveServiceName(hasPromotion: false), so there's never a Promo_ prefix. The envelope's transactionReference and dateReference = draft.groupId and submissionDate.serviceName: fijo PaymentCollectionAPI — el builder llama type.resolveServiceName(hasPromotion: false), así que nunca hay prefijo Promo_. El transactionReference y dateReference del envelope = draft.groupId y submissionDate.

Enum PaymentMethod (paymentMode)PaymentMethod enum (paymentMode)Enum PaymentMethod (paymentMode) code · apiName

paymentMode emite o apiName (não o code). Valores possíveis do enum PaymentMethod (code → apiName):paymentMode emits the apiName (not the code). Possible values of the PaymentMethod enum (code → apiName):paymentMode emite el apiName (no el code). Valores posibles del enum PaymentMethod (code → apiName):

case	`code`	`apiName`
`bankSlip`	`ZG`	`Bank Slip`
`electronicFundsTransfer`	`ZE`	`Electronic Funds Transfer`
`bankDeposit`	`ZB`	`Bank Deposit`
`paymentButton`	`PB`	`""`
`cash`	`ZH`	`Cash`
`cheque`	`ZC`	`Cheque`
`promissoryNote`	`ZI`	`Promissory Note`
`creditNote`	`Z9`	`Credit Note`
`pix`	`ZX`	`Pix`
`creditCard`	`Z1`	`Credit Card`
`debitCard`	`Z2`	`Debit Card`
`paymentOrder`	`ZP`	`Payment Order`
`directDebit`	`ZJ`	`Direct Debit`
`mobilePayment`	`ZM`	`Mobile Payment`
`unknown`	`""`	`""`

Pendências / roadmapPending / roadmapPendientes / roadmap

O que o builder ainda não preenche ou envia inerte, documentado fiel ao estado atual do código (nunca descrito como se já existisse):What the builder does not yet fill, or ships inert, documented faithfully to the current code state (never described as already existing):Lo que el builder aún no completa, o envía inerte, documentado fiel al estado actual del código (nunca descrito como si ya existiera):

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

A evidência do pagamento (foto/anexo) presente no PaymentMethodEntryEntity (evidenceImageBase64, evidenceFileBase64, evidenceFileName) não entra neste payload — a prova viaja pela transação irmã 22 · Comprovante de pagamento.The payment evidence (photo/attachment) held in PaymentMethodEntryEntity (evidenceImageBase64, evidenceFileBase64, evidenceFileName) is not part of this payload — the proof travels via the sister transaction 22 · Proof of payment.La evidencia del pago (foto/adjunto) presente en PaymentMethodEntryEntity (evidenceImageBase64, evidenceFileBase64, evidenceFileName) no entra en este payload — la prueba viaja por la transacción hermana 22 · Comprobante de pago.
Método comum com collectionReference vazia é silenciosamente pulado (getter collectionReferences devolve lista vazia) — não há log nem erro; a validação de referência obrigatória fica a cargo da UI.A regular method with a blank collectionReference is silently skipped (the collectionReferences getter returns an empty list) — no log or error; enforcing a required reference is left to the UI.Un método común con collectionReference vacía se omite silenciosamente (el getter collectionReferences devuelve lista vacía) — sin log ni error; la validación de referencia obligatoria queda a cargo de la UI.
Sem campo de tipo/variante e sem suporte a Promo_: hasPromotion é sempre false no build().No type/variant field and no Promo_ support: hasPromotion is always false in build().Sin campo de tipo/variante y sin soporte a Promo_: hasPromotion siempre es false en build().
Transporte: deviceUuid vai como literal provisório no gateway (pendência conhecida do Dispatcher, comum a todas as transações).Transport: deviceUuid ships as a provisional literal in the gateway (known Dispatcher pending item, common to all transactions).Transporte: deviceUuid va como literal provisional en el gateway (pendiente conocido del Dispatcher, común a todas las transacciones).

Feature donaOwning featureFeature dueña O envio parte da Criação de pagamentos e da Gestão financeira — veja essas features para o contexto de UI. O fechamento de caixa relacionado é a 24 · Relatório de caixa. The send comes from Payment creation and Financial management — see those features for the UI context. The related cash close-out is 24 · Cash payment report. El envío parte de Creación de pagos y de Gestión financiera — vea esas features para el contexto de UI. El cierre de caja relacionado es el 24 · Informe de caja.

★

MercadosMarketsMercados

A disponibilidade da transação vem do DispatcherType.payment.enabledMarkets — BR/CL. O payload é uniforme: não há divergência de campos por mercado. ZA e AR/PY/PE não têm esta transação.Transaction availability comes from DispatcherType.payment.enabledMarkets — BR/CL. The payload is uniform: there's no per-market field divergence. ZA and AR/PY/PE don't have this transaction.La disponibilidad de la transacción viene de DispatcherType.payment.enabledMarkets — BR/CL. El payload es uniforme: no hay divergencia de campos por mercado. ZA y AR/PY/PE no tienen esta transacción.

BRx CLx ZA— AR— PY— PE—

disponívelavailabledisponible presente, desligadopresent, offpresente, apagado ausenteabsentausente

BRCL

Mesmo contratoSame contractMismo contrato Nos dois mercados o payload é idêntico — os mesmos 12 campos por perna de Payment, mesmo serviceName e mesmo destino salesforce. Os métodos de pagamento disponíveis (via PaymentMethod) podem variar por mercado na UI, mas a forma do payload não. In both markets the payload is identical — the same 12 Payment fields per leg, same serviceName and same salesforce destination. The available payment methods (via PaymentMethod) may vary per market in the UI, but the payload shape does not. En ambos mercados el payload es idéntico — los mismos 12 campos por pierna de Payment, mismo serviceName y mismo destino salesforce. Los métodos de pago disponibles (vía PaymentMethod) pueden variar por mercado en la UI, pero la forma del payload no.

ZA · AR · PY · PE Existem como mercados do app, mas não têm esta transação — enabledMarkets lista só BR e CL. Diferente do Comprovante de pagamento (BR/CL/ZA), a Coleta de pagamento não inclui a África do Sul. AR/PY/PE seguem com config PANGEA mínima. They exist as app markets, but don't have this transaction — enabledMarkets lists only BR and CL. Unlike Proof of payment (BR/CL/ZA), Payment collection does not include South Africa. AR/PY/PE remain on minimal PANGEA config. Existen como mercados de la app, pero no tienen esta transacción — enabledMarkets lista solo BR y CL. A diferencia del Comprobante de pago (BR/CL/ZA), el Cobro de pago no incluye Sudáfrica. AR/PY/PE siguen con config PANGEA mínima.