Criação de pagamentosPayment creationCreación de pagos
A tela onde o representante de vendas registra o dinheiro que recebeu do varejo: um ou mais documentos em aberto, uma a três formas de pagamento, banco, agência, número de referência, data e comprovante. O envio é remote-first (PaymentCollectionAPI) e, só depois do sucesso, o débito local é abatido. A mesma tela atende cinco entradas (quatro origens) — gestão financeira, detalhe do documento, gestão de cobranças, pedido prompt "a vista" e entrega que exige pagamento.
The screen where the sales rep records the money collected from the retail: one or more open documents, one to three payment methods, bank, branch, reference number, date and proof. The send is remote-first (PaymentCollectionAPI) and only after success is the local debit written down. The same screen serves five entry points (four origins) — financial management, document detail, collections management, prompt cash order and a delivery that requires payment.
La pantalla donde el representante de ventas registra el dinero que recibió del punto de venta: uno o más documentos abiertos, de uno a tres métodos de pago, banco, sucursal, número de referencia, fecha y comprobante. El envío es remote-first (PaymentCollectionAPI) y solo después del éxito se descuenta el débito local. La misma pantalla atiende cinco entradas (cuatro orígenes) — gestión financiera, detalle del documento, gestión de cobranzas, pedido prompt "al contado" y entrega que exige pago.
O que é e para que serveWhat it is and what it's forQué es y para qué sirve
Um pagamento é o registro de um valor recebido do varejo e aplicado a um ou mais documentos em aberto (DPI — débitos). O representante escolhe os documentos, informa como recebeu (efetivo, transferência, depósito, cheque, cheque a fecha, nota de crédito…), quanto, quando e anexa o comprovante. Ao confirmar, o pagamento vai ao backend e o saldo do documento cai na hora no aplicativo. A payment is the record of an amount collected from the retail and applied to one or more open documents (DPI — debits). The rep picks the documents, states how the money came in (cash, transfer, deposit, cheque, post-dated cheque, credit note…), how much, when, and attaches the proof. On confirm the payment goes to the backend and the document balance drops right away in the app. Un pago es el registro de un monto recibido del punto de venta y aplicado a uno o más documentos abiertos (DPI — débitos). El representante elige los documentos, informa cómo recibió (efectivo, transferencia, depósito, cheque, cheque a fecha, nota de crédito…), cuánto, cuándo y adjunta el comprobante. Al confirmar, el pago va al backend y el saldo del documento baja al instante en la aplicación.
Uma tela, cinco entradasOne screen, five entry pointsUna pantalla, cinco entradas
O formulário é o mesmo; o que muda é o que já vem preenchido e se o pagamento é enviado na hora ou guardado.The form is the same; what changes is what comes pre-filled and whether the payment is sent right away or held.El formulario es el mismo; lo que cambia es qué viene precargado y si el pago se envía al instante o se guarda.
Até 3 formas de pagamentoUp to 3 payment methodsHasta 3 métodos de pago
O valor é digitado por forma de pagamento e distribuído entre os documentos, do mais antigo ao mais novo.The amount is typed per payment method and spread across the documents, oldest to newest.El monto se ingresa por método de pago y se distribuye entre los documentos, del más antiguo al más nuevo.
ComprovanteProof of paymentComprobante
Foto e/ou arquivo por forma de pagamento, enviados numa transação própria após o pagamento.Photo and/or file per payment method, sent in their own transaction after the payment.Foto y/o archivo por método de pago, enviados en su propia transacción después del pago.
Só no ChileChile onlySolo Chile
A criação de pagamentos é habilitada pelo módulo financial_management_payment_creation, visível apenas no Chile (CL). Nos outros mercados a seleção de documentos e os botões de pagar não aparecem (ver Mercados).
Payment creation is enabled by the financial_management_payment_creation module, visible only in Chile (CL). In the other markets the document selection and the pay buttons don't show (see Markets).
La creación de pagos se habilita por el módulo financial_management_payment_creation, visible solo en Chile (CL). En los demás mercados la selección de documentos y los botones de pagar no aparecen (ver Mercados).
Como acessar — as cinco entradasHow to open — the five entry pointsCómo acceder — las cinco entradas
| OrigemOriginOrigen | CaminhoPathCamino | O que já vem prontoWhat comes readyQué viene listo | Ao confirmarOn confirmAl confirmar |
|---|---|---|---|
| Gestão financeiraFinancial managementGestión financiera | Detalhe da visita → Gestão financeira → marcar 1+ documentos → "Pagar selecionados"Visit detail → Financial management → tick 1+ documents → "Pay selected"Detalle de la visita → Gestión financiera → marcar 1+ documentos → "Pagar seleccionados" | Os documentos marcados e o totalThe ticked documents and the totalLos documentos marcados y el total | Envia na horaSends right awayEnvía al instante |
| Detalhe do documentoDocument detailDetalle del documento | Gestão financeira → abrir um documento → "Pagar documento"Financial management → open a document → "Pay document"Gestión financiera → abrir un documento → "Pagar documento" | Aquele único documentoThat single documentEse único documento | Envia na horaSends right awayEnvía al instante |
| Gestão de cobrançasCollections managementGestión de cobranzas | Home → Gestão de cobranças → varejo → (cai na gestão financeira)Home → Collections management → retail → (lands on financial management)Home → Gestión de cobranzas → punto de venta → (cae en gestión financiera) | Idem gestão financeira, mas sem exigir visita iniciada e com a forma preferida do varejo pré-selecionadaSame as financial management, but no started visit required and with the retail's preferred method pre-selectedIgual que gestión financiera, pero sin exigir visita iniciada y con el método preferido del punto de venta preseleccionado | Envia na horaSends right awayEnvía al instante |
| Pedido prompt "a vista"Prompt cash orderPedido prompt "al contado" | Carrinho → "Pago al Contado" → tela de pagamento do pedido → "Configurar pagamento"Cart → "Pago al Contado" → order payment screen → "Configure payment"Carrito → "Pago al Contado" → pantalla de pago del pedido → "Configurar pago" | Um documento sintético com o total do pedido; valor fixo e uma única formaA synthetic document with the order total; fixed amount and a single methodUn documento sintético con el total del pedido; monto fijo y un único método | Guarda e envia depois (ver 04)Holds and sends later (see 04)Guarda y envía después (ver 04) |
| Entrega que exige pagamentoDelivery requiring paymentEntrega que exige pago | Entregas do dia → selecionar → "Confirmar" → "Configurar pagamento"Deliveries of the day → select → "Confirm" → "Configure payment"Entregas del día → seleccionar → "Confirmar" → "Configurar pago" | O documento do pedido que vence hoje; exige cobrir o totalThe order document due today; must cover the full totalEl documento del pedido que vence hoy; exige cubrir el total | Envia depois da entrega ser confirmadaSends after the delivery is confirmedEnvía después de que la entrega se confirme |
Visita iniciadaStarted visitVisita iniciada Quando o pagamento é aberto dentro de uma visita, a visita precisa estar iniciada — o app oferece iniciá-la. Vindo da gestão de cobranças (Home) essa exigência não existe. When the payment is opened inside a visit, the visit must be started — the app offers to start it. Coming from collections management (Home) that requirement doesn't apply. Cuando el pago se abre dentro de una visita, la visita debe estar iniciada — la app ofrece iniciarla. Viniendo de gestión de cobranzas (Home) esa exigencia no aplica.
Estrutura da telaScreen structureEstructura de la pantalla
Uma coluna rolável com a barra de resumo fixa no rodapé:A scrollable column with the summary bar pinned to the footer:Una columna desplazable con la barra de resumen fija al pie:
- Cartão do varejoRetail cardTarjeta del punto de venta
- Nome, código do cliente e o indicador de inadimplência — só leitura.Name, customer code and the overdue indicator — read only.Nombre, código de cliente y el indicador de mora — solo lectura.
- Documentos a pagarDocuments to payDocumentos a pagar
- Um card com a lista dos documentos escolhidos (número, nota fiscal, vencimento e valor). Só leitura: quem escolhe é a tela anterior.One card listing the chosen documents (number, invoice, due date and amount). Read only: the previous screen is where you pick them.Un card con la lista de los documentos elegidos (número, factura, vencimiento y monto). Solo lectura: la pantalla anterior es donde se eligen.
- Link de pagamento (ETPay)Payment link (ETPay)Link de pago (ETPay)
- Botão pagar por link + divisor "OU", quando o mercado tem o módulo de link de pagamento habilitado. É um fluxo funcional: tocar leva a uma tela de seleção de banco e, ao confirmar, gera um QR + URL de pagamento (ver Link de pagamento).Pay-by-link button + "OR" divider, when the market has the payment link module enabled. It's a functional flow: tapping opens a bank selection screen and, on confirm, generates a payment QR + URL (see Payment link).Botón pagar por link + divisor "O", cuando el mercado tiene el módulo de link de pago habilitado. Es un flujo funcional: tocar abre una pantalla de selección de banco y, al confirmar, genera un QR + URL de pago (ver Link de pago).
- Forma de pagamento (1 a 3)Payment method (1 to 3)Método de pago (1 a 3)
- Um card por forma: seletor da forma, número de referência, data, banco, agência e valor — mais os botões de comprovante. Com mais de uma forma, cada card ganha o número e um x para remover.One card per method: method picker, reference number, date, bank, branch and amount — plus the proof buttons. With more than one method each card gets its number and an x to remove it.Un card por método: selector del método, número de referencia, fecha, banco, sucursal y monto — más los botones de comprobante. Con más de un método, cada card recibe su número y una x para quitarlo.
- Adicionar forma de pagamentoAdd payment methodAgregar método de pago
- Só aparece se o mercado permite mais de uma forma e o teto (3) não foi atingido.Only shows if the market allows more than one method and the cap (3) hasn't been reached.Solo aparece si el mercado permite más de un método y el tope (3) no se alcanzó.
- Barra de resumoSummary barBarra de resumen
- Fixa no rodapé, com Total a pagar, Informado e Restante atualizando a cada dígito, e o botão de confirmar/salvar. Arrastando para cima, expande com o resumo.Pinned to the footer with Total to pay, Entered and Remaining updating on every keystroke, plus the confirm/save button. Dragging up expands the summary.Fija al pie con Total a pagar, Ingresado y Restante actualizando con cada dígito, y el botón de confirmar/guardar. Arrastrando hacia arriba, expande el resumen.
Estados do pagamentoPayment statesEstados del pago
Todo pagamento criado no app fica registrado e visível no detalhe do documento e na aba Pagamentos do Data Center. Quando o documento já existe (gestão financeira, cobranças, entrega) o pagamento nasce sincronizado. No pedido prompt "a vista" o débito ainda não existe, então o pagamento espera:Every payment created in the app is recorded and visible in the document detail and in the Data Center's Payments tab. When the document already exists (financial management, collections, delivery) the payment is born synced. In the prompt cash order the debit doesn't exist yet, so the payment waits:Todo pago creado en la app queda registrado y visible en el detalle del documento y en la pestaña Pagos del Data Center. Cuando el documento ya existe (gestión financiera, cobranzas, entrega) el pago nace sincronizado. En el pedido prompt "al contado" el débito aún no existe, así que el pago espera:
- Aguardando aprovação do pedidoAwaiting order approvalEsperando aprobación del pedido
- O pedido a vista foi para aprovação. O pagamento está guardado no aparelho, com os comprovantes.The cash order went to approval. The payment is held on the device, with its proofs.El pedido al contado fue a aprobación. El pago está guardado en el dispositivo, con sus comprobantes.
- Aguardando débito do pedidoAwaiting order debitEsperando el débito del pedido
- O pedido foi faturado, mas o documento (DPI) ainda não voltou do backend. Sem ele, o pagamento não tem onde ser aplicado.The order was invoiced but the document (DPI) hasn't come back from the backend yet. Without it the payment has nowhere to land.El pedido se facturó pero el documento (DPI) aún no volvió del backend. Sin él el pago no tiene dónde aplicarse.
- Pronto para sincronizarReady to syncListo para sincronizar
- O documento chegou e o app já o casou com o pagamento. Basta tocar em Sincronizar na aba Pagamentos do Data Center.The document arrived and the app matched it to the payment. Just tap Sync in the Data Center's Payments tab.El documento llegó y la app ya lo emparejó con el pago. Basta tocar Sincronizar en la pestaña Pagos del Data Center.
- SincronizadoSyncedSincronizado
- O backend recebeu o pagamento. O saldo do documento já foi abatido no app.The backend received the payment. The document balance has already been written down in the app.El backend recibió el pago. El saldo del documento ya fue descontado en la app.
Ações e regrasActions & rulesAcciones y reglas
- Escolher a forma de pagamentoPick the payment methodElegir el método de pago
- A lista vem do varejo (as formas que ele aceita). Trocar a forma limpa referência, data, banco, agência e notas de crédito, porque as regras de cada forma são diferentes. O botão de pagamento (link) nunca aparece como forma selecionável.The list comes from the retail (the methods it accepts). Changing the method clears reference, date, bank, branch and credit notes, because each method has its own rules. The payment button (link) never shows as a selectable method.La lista viene del punto de venta (los métodos que acepta). Cambiar el método limpia referencia, fecha, banco, sucursal y notas de crédito, porque las reglas de cada método son distintas. El botón de pago (link) nunca aparece como método seleccionable.
- Data do pagamentoPayment dateFecha del pago
- A janela permitida depende da forma: transferência e depósito aceitam até 8 semanas atrás (inclusive fim de semana); cheque e efetivo, só hoje; cheque a fecha, do próximo dia útil até 28 dias; nota de crédito, do dia útil anterior ao próximo.The allowed window depends on the method: transfer and deposit accept up to 8 weeks back (weekends included); cheque and cash, today only; post-dated cheque, from the next business day up to 28 days; credit note, from the previous business day to the next.La ventana permitida depende del método: transferencia y depósito aceptan hasta 8 semanas atrás (fines de semana incluidos); cheque y efectivo, solo hoy; cheque a fecha, del próximo día hábil hasta 28 días; nota de crédito, del día hábil anterior al siguiente.
- Nota de créditoCredit noteNota de crédito
- Escolhendo "nota de crédito", em vez de referência/banco aparece o seletor de notas disponíveis do varejo. O valor é a soma das notas e não pode ser editado. Depois do envio, as notas usadas ficam indisponíveis.Choosing "credit note", instead of reference/bank you get the picker of the retail's available notes. The amount is the sum of the notes and can't be edited. After the send, the used notes become unavailable.Al elegir "nota de crédito", en lugar de referencia/banco aparece el selector de notas disponibles del punto de venta. El monto es la suma de las notas y no se puede editar. Tras el envío, las notas usadas quedan no disponibles.
- Valor e valor restanteAmount and remainingMonto y monto restante
- O valor é por forma de pagamento. Se ainda falta cobrir o total, um atalho "Usar valor restante" preenche a diferença. Pagando mais de um documento, a soma precisa cobrir o total; pagando um só, é permitido pagar parcialmente.The amount is per payment method. If the total isn't covered yet, a "Use remaining amount" shortcut fills the gap. When paying more than one document the sum must cover the total; with a single document a partial payment is allowed.El monto es por método de pago. Si aún falta cubrir el total, un atajo "Usar monto restante" completa la diferencia. Pagando más de un documento, la suma debe cubrir el total; con un solo documento se permite pago parcial.
- ComprovanteProofComprobante
- Uma foto e/ou um arquivo por forma de pagamento. Se faltar comprovante, o app pergunta antes de confirmar; quando o backend informa que o comprovante é obrigatório para aquele representante, não há como seguir sem ele.One photo and/or one file per payment method. If the proof is missing the app asks before confirming; when the backend says the proof is mandatory for that rep, there's no way to continue without it.Una foto y/o un archivo por método de pago. Si falta el comprobante la app pregunta antes de confirmar; cuando el backend informa que el comprobante es obligatorio para ese representante, no se puede seguir sin él.
- Valor excedenteExcess amountMonto excedente
- Informando mais do que o total, o app oferece aplicar o excedente ao documento aberto mais antigo do varejo, mostrando qual e quanto. Recusando, o excedente fica no último documento pago.Entering more than the total, the app offers to apply the excess to the retail's oldest open document, showing which and how much. If refused, the excess stays on the last paid document.Al ingresar más que el total, la app ofrece aplicar el excedente al documento abierto más antiguo del punto de venta, mostrando cuál y cuánto. Si se rechaza, el excedente queda en el último documento pagado.
- Pagamento integral obrigatórioFull payment requiredPago integral obligatorio
- Para os tipos de representante configurados no mercado (no Chile, Pre-sales Rep), um documento sem prazo de um varejo sem dias de crédito precisa ser pago integralmente.For the rep types configured in the market (in Chile, Pre-sales Rep), a document with no credit period from a retail with no credit days must be paid in full.Para los tipos de representante configurados en el mercado (en Chile, Pre-sales Rep), un documento sin plazo de un punto de venta sin días de crédito debe pagarse íntegramente.
Como o valor é distribuídoHow the amount is spreadCómo se distribuye el monto Cada forma de pagamento preenche os documentos em cascata, do mais antigo ao mais novo: enche o primeiro até o saldo dele, o que sobra escorre para o segundo, e assim por diante. Sobrando dinheiro depois de todos cobertos, a sobra fica no último documento tocado — é aí que entra a oferta de redirecionar o excedente. Each payment method fills the documents in a waterfall, oldest to newest: it fills the first up to its balance, the leftover flows to the second, and so on. If money is left after everything is covered, it stays on the last document touched — that's where the excess-redirect offer comes in. Cada método de pago llena los documentos en cascada, del más antiguo al más nuevo: llena el primero hasta su saldo, lo que sobra pasa al segundo, y así. Si sobra dinero después de cubrir todo, queda en el último documento tocado — ahí entra la oferta de redirigir el excedente.
Arquitetura e fluxo de dadosArchitecture & data flowArquitectura y flujo de datos
Clean Architecture + Riverpod + Freezed + ObjectBox. São três fluxos: a leitura do que alimenta o formulário (cache do aggregate de gestão financeira), a escrita imediata (origens com DPI existente) e a escrita diferida (pedido prompt a vista, sem DPI).Clean Architecture + Riverpod + Freezed + ObjectBox. There are three flows: the read that feeds the form (cache of the financial management aggregate), the immediate write (origins with an existing DPI) and the deferred write (prompt cash order, no DPI).Clean Architecture + Riverpod + Freezed + ObjectBox. Hay tres flujos: la lectura que alimenta el formulario (caché del aggregate de gestión financiera), la escritura inmediata (orígenes con DPI existente) y la escritura diferida (pedido prompt al contado, sin DPI).
Leitura · só cacheRead · cache-onlyLectura · solo caché
A tela não chama RPC próprio. Bancos, agências e notas de crédito vêm do aggregate de gestão financeira já gravado no ObjectBox; o rascunho dos documentos vem semeado pela tela de origem via paymentDraftProvider; as formas de pagamento vêm do varejo (retails, com fallback na visita).The screen calls no RPC of its own. Banks, branches and credit notes come from the financial management aggregate already written to ObjectBox; the document draft is seeded by the origin screen via paymentDraftProvider; the payment methods come from the retail (retails, falling back to the visit).La pantalla no llama RPC propio. Bancos, sucursales y notas de crédito vienen del aggregate de gestión financiera ya grabado en ObjectBox; el borrador de los documentos lo siembra la pantalla de origen vía paymentDraftProvider; los métodos de pago vienen del punto de venta (retails, con fallback en la visita).
- FinancialManagementModelObjectBox · cache
- getCachedFinancialManagementRepository
- banks · creditNotesGetFinancialManagementUseCase
- + ResolveAccountPaymentMethodsUseCasePaymentCreationNotifier · _load+ paymentDraftProvider (seed)
- → UIPaymentCreationPage
- + ResolveAccountPaymentMethodsUseCasePaymentCreationNotifier · _load+ paymentDraftProvider (seed)
- banks · creditNotesGetFinancialManagementUseCase
- getCachedFinancialManagementRepository
Escrita imediata · DPI existenteImmediate write · existing DPIEscritura inmediata · DPI existente
Origens financialManagement e collections. O Notifier valida, gera os identificadores, resolve os base64 dos comprovantes e entrega o input cru ao orquestrador, que despacha e só então aplica os efeitos locais (§36 remote-first).Origins financialManagement and collections. The Notifier validates, generates the identifiers, resolves the proofs' base64 and hands the raw input to the orchestrator, which dispatches and only then applies the local effects (§36 remote-first).Orígenes financialManagement y collections. El Notifier valida, genera los identificadores, resuelve los base64 de los comprobantes y entrega el input crudo al orquestador, que despacha y solo entonces aplica los efectos locales (§36 remote-first).
- PaymentCreationFooterWidgetUI · confirmar
- submit()PaymentCreationNotifierValidatePaymentDraftUseCase + PaymentIdentifierUtils
- submit(input)PaymentSubmissionOrchestrator
- build + dispatchPaymentCollectionAPIDispatcherOrchestrator
- on successmarkCreditNotesUsed · applyPaymentAllocationsObjectBox
- + registro localPaymentRegisterRepositorystatus sent
- se houver comprovante / entregaFinancialProofPaymentAPI · CashPaymentReportAPI
- + registro localPaymentRegisterRepositorystatus sent
- on successmarkCreditNotesUsed · applyPaymentAllocationsObjectBox
- build + dispatchPaymentCollectionAPIDispatcherOrchestrator
- submit(input)PaymentSubmissionOrchestrator
- submit()PaymentCreationNotifierValidatePaymentDraftUseCase + PaymentIdentifierUtils
Escrita diferida · sem DPIDeferred write · no DPIEscritura diferida · sin DPI
Origem promptOrder. A tela só salva o rascunho (com os comprovantes já em base64, porque os arquivos capturados não sobrevivem ao fim da sessão). Depois do pedido ser enviado, o registro é persistido como pendente; quando o débito chega, ele é promovido e o usuário sincroniza pelo Data Center.Origin promptOrder. The screen only saves the draft (with proofs already as base64, because captured files don't survive the session end). After the order is submitted the register is persisted as pending; once the debit arrives it's promoted and the user syncs from the Data Center.Origen promptOrder. La pantalla solo guarda el borrador (con los comprobantes ya en base64, porque los archivos capturados no sobreviven al fin de la sesión). Tras enviar el pedido, el registro se persiste como pendiente; cuando llega el débito se promueve y el usuario sincroniza desde el Data Center.
- OrderPaymentConfigurePaymentWidgetUI · configurar pagamento
- save(draft)paymentDraftProviderpor split · base64 resolvido
- pedido enviadoOrderSubmission · _registerDeferredPayments
- isDeferred: truePaymentSubmissionOrchestratorsem despacho
- savePaymentRegisterRepositoryORDER_PA · CREATED
- débito chegou (refresh do Data Center)ResolvePendingPaymentRegistersUseCase→ READY
- SincronizarSyncPaymentRegisterUseCase→ PaymentCollectionAPI
- débito chegou (refresh do Data Center)ResolvePendingPaymentRegistersUseCase→ READY
- savePaymentRegisterRepositoryORDER_PA · CREATED
- isDeferred: truePaymentSubmissionOrchestratorsem despacho
- pedido enviadoOrderSubmission · _registerDeferredPayments
- save(draft)paymentDraftProviderpor split · base64 resolvido
Por que o registro tem box próprioWhy the register has its own boxPor qué el registro tiene box propio
saveFinancialManagement limpa todos os boxes do aggregate (incluindo PaymentModel) a cada sincronização. Um pagamento pendente guardado ali desapareceria no primeiro refresh. Por isso os pagamentos criados no app vivem em PaymentRegisterModel, box próprio, e o payments do aggregate segue sendo o espelho read-only do backend. O detalhe do documento exibe as duas fontes.
saveFinancialManagement wipes every box of the aggregate (including PaymentModel) on each sync. A pending payment stored there would vanish on the first refresh. That's why payments created in the app live in PaymentRegisterModel, its own box, and the aggregate's payments stays the read-only mirror of the backend. The document detail shows both sources.
saveFinancialManagement limpia todos los boxes del aggregate (incluido PaymentModel) en cada sincronización. Un pago pendiente guardado ahí desaparecería en el primer refresh. Por eso los pagos creados en la app viven en PaymentRegisterModel, box propio, y el payments del aggregate sigue siendo el espejo read-only del backend. El detalle del documento muestra ambas fuentes.
Link de pagamento · pay-by-link (ETPay)Payment link · pay-by-link (ETPay)Link de pago · pay-by-link (ETPay)
Alternativa ao registro manual: em vez de digitar forma/valor, o representante gera um link de pagamento (QR + URL) para o varejo pagar sozinho. É um fluxo navegável próprio (pasta presentation/payment_link/), aberto pelo botão ETPay do PaymentCreationPaymentLinkWidget. A entrada só aparece quando state.showPaymentLinkEntry é true — ou seja, a origem envia na confirmação (origin.sendsOnConfirm: financialManagement/collections) e o módulo financial_management_payment_link está presente e visível no mercado. Documentos cujo paymentLinkStatus já é success são excluídos da lista.An alternative to the manual register: instead of typing method/amount, the rep generates a payment link (QR + URL) for the retail to pay on its own. It's its own navigable flow (folder presentation/payment_link/), opened by the ETPay button in PaymentCreationPaymentLinkWidget. The entry only shows when state.showPaymentLinkEntry is true — i.e. the origin sends on confirm (origin.sendsOnConfirm: financialManagement/collections) and the financial_management_payment_link module is present and visible in the market. Documents whose paymentLinkStatus is already success are excluded from the list.Alternativa al registro manual: en lugar de digitar método/monto, el representante genera un link de pago (QR + URL) para que el punto de venta pague solo. Es su propio flujo navegable (carpeta presentation/payment_link/), abierto por el botón ETPay del PaymentCreationPaymentLinkWidget. La entrada solo aparece cuando state.showPaymentLinkEntry es true — es decir, el origen envía al confirmar (origin.sendsOnConfirm: financialManagement/collections) y el módulo financial_management_payment_link está presente y visible en el mercado. Documentos cuyo paymentLinkStatus ya es success se excluyen de la lista.
- PaymentCreationPaymentLinkWidgetUI · botão ETPay + divisor "OU"
- goToPaymentLinkBankSelection(accountSfid, debitOpenItemSfids)PaymentLinkBankSelectionPageDataLoadInfo · AccountHeaderCard · PaymentDebitsSummary · tiles de banco
- _load · getBanks + retail + debitsPaymentLinkNotifier · PaymentLinkStatefamily (accountSfid, debitOpenItemSfids)
- selectBank → "Confirmar" → generate()CreatePaymentLinkUseCase.execute
- createPaymentLink (RPC)FinancialManagementConectaRepService→ CreatePaymentLinkReply (url)
- goToPaymentLinkResult(link, totalAmount)PaymentLinkResultPageQR (QrImageView) + URL · Copiar/Compartilhar
- createPaymentLink (RPC)FinancialManagementConectaRepService→ CreatePaymentLinkReply (url)
- selectBank → "Confirmar" → generate()CreatePaymentLinkUseCase.execute
- _load · getBanks + retail + debitsPaymentLinkNotifier · PaymentLinkStatefamily (accountSfid, debitOpenItemSfids)
- goToPaymentLinkBankSelection(accountSfid, debitOpenItemSfids)PaymentLinkBankSelectionPageDataLoadInfo · AccountHeaderCard · PaymentDebitsSummary · tiles de banco
- Seleção de bancoBank selectionSelección de banco
PaymentLinkBankSelectionPage(ConsumerWidget) observapaymentLinkProvider(accountSfid:, debitOpenItemSfids:). Dentro doAppPageShell(com voltar):DataLoadInfo(state.lastSyncAt),AccountHeaderCard(nome em maiúsculas ·accountCode),PaymentDebitsSummary(state.debits), título e ou oCustomEmptyState(sem bancos) ou uma lista dePaymentLinkBankTileWidget(seleção única viaCustomRadio→selectBank). No rodapé, umCustomSummaryBarcom nº de documentos + Total a pagar e a ação Confirmar (isLoading: isGenerating, habilitada porcanConfirm). Loading →CustomLoadingIndicator; erro →FailureStateViewcomrefresh().PaymentLinkBankSelectionPage(ConsumerWidget) watchespaymentLinkProvider(accountSfid:, debitOpenItemSfids:). InsideAppPageShell(with back):DataLoadInfo(state.lastSyncAt),AccountHeaderCard(uppercased name ·accountCode),PaymentDebitsSummary(state.debits), a title and eitherCustomEmptyState(no banks) or a list ofPaymentLinkBankTileWidget(single-select viaCustomRadio→selectBank). In the footer, aCustomSummaryBarwith document count + Total to pay and the Confirm action (isLoading: isGenerating, enabled bycanConfirm). Loading →CustomLoadingIndicator; error →FailureStateViewwithrefresh().PaymentLinkBankSelectionPage(ConsumerWidget) observapaymentLinkProvider(accountSfid:, debitOpenItemSfids:). Dentro delAppPageShell(con volver):DataLoadInfo(state.lastSyncAt),AccountHeaderCard(nombre en mayúsculas ·accountCode),PaymentDebitsSummary(state.debits), un título y o elCustomEmptyState(sin bancos) o una lista dePaymentLinkBankTileWidget(selección única víaCustomRadio→selectBank). En el pie, unCustomSummaryBarcon nº de documentos + Total a pagar y la acción Confirmar (isLoading: isGenerating, habilitada porcanConfirm). Loading →CustomLoadingIndicator; error →FailureStateViewconrefresh().- Tile de bancoBank tileTile de banco
PaymentLinkBankTileWidget(StatelessWidget:bank,isSelected,market,onTap): ícone do banco (Image.memorydobankIconBase64, só sehasIcon), nome, rótulo conta empresa/pessoal (isCompany), limite de transação quandohasTransactionLimit(CurrencyUtils.format), e umCustomRadio. A borda usabrandPrimaryquando selecionado.PaymentLinkBankTileWidget(StatelessWidget:bank,isSelected,market,onTap): bank icon (Image.memoryofbankIconBase64, only ifhasIcon), name, company/personal account label (isCompany), transaction limit whenhasTransactionLimit(CurrencyUtils.format), and aCustomRadio. Border usesbrandPrimarywhen selected.PaymentLinkBankTileWidget(StatelessWidget:bank,isSelected,market,onTap): ícono del banco (Image.memorydelbankIconBase64, solo sihasIcon), nombre, etiqueta cuenta empresa/personal (isCompany), límite de transacción cuandohasTransactionLimit(CurrencyUtils.format), y unCustomRadio. El borde usabrandPrimarycuando está seleccionado.- ResultadoResultResultado
PaymentLinkResultPage(StatelessWidget:link,totalAmount): título de sucesso, o total (CustomText.currency), o QR dolink.urlviaQrImageView(qr_flutter, tamanhoxxl280), o card com a URL em texto e dois botões — Copiar (filled→Clipboard+ConectaNotice.success) e Compartilhar (outlined→SharePlus). Não há botão de "abrir URL".PaymentLinkResultPage(StatelessWidget:link,totalAmount): a success title, the total (CustomText.currency), the QR oflink.urlviaQrImageView(qr_flutter, sizexxl280), the card with the URL as text and two buttons — Copy (filled→Clipboard+ConectaNotice.success) and Share (outlined→SharePlus). There's no "open URL" button.PaymentLinkResultPage(StatelessWidget:link,totalAmount): un título de éxito, el total (CustomText.currency), el QR dellink.urlvíaQrImageView(qr_flutter, tamañoxxl280), el card con la URL en texto y dos botones — Copiar (filled→Clipboard+ConectaNotice.success) y Compartir (outlined→SharePlus). No hay botón de "abrir URL".- Notifier & StateNotifier & StateNotifier & State
PaymentLinkNotifier(@riverpod, family por(accountSfid, debitOpenItemSfids), mixinAsyncGuard):build → guardedBuild(_load);_loadresolve o representante,getBanks(resourceSfid), o varejo (getCachedByAccountSfid) e os débitos (getCachedDebitOpenItemBySfidpor sfid), autoselecionando o banco se só houver um;refresh();selectBank(toggle de seleção única);generate()→PaymentLinkResult(record({link, failure})). OPaymentLinkStateguardabanks,items,debits,accountName/accountCode/customerTaxId,selectedBankName,isGenerating,lastSyncAt, e os getterstotalAmount(soma dositems),hasBanks,canConfirmeisSelected.PaymentLinkNotifier(@riverpod, family by(accountSfid, debitOpenItemSfids),AsyncGuardmixin):build → guardedBuild(_load);_loadresolves the rep,getBanks(resourceSfid), the retail (getCachedByAccountSfid) and the debits (getCachedDebitOpenItemBySfidper sfid), auto-selecting the bank if there's only one;refresh();selectBank(single-select toggle);generate()→PaymentLinkResult(record({link, failure})).PaymentLinkStateholdsbanks,items,debits,accountName/accountCode/customerTaxId,selectedBankName,isGenerating,lastSyncAt, and the getterstotalAmount(sum ofitems),hasBanks,canConfirmandisSelected.PaymentLinkNotifier(@riverpod, family por(accountSfid, debitOpenItemSfids), mixinAsyncGuard):build → guardedBuild(_load);_loadresuelve el representante,getBanks(resourceSfid), el punto de venta (getCachedByAccountSfid) y los débitos (getCachedDebitOpenItemBySfidpor sfid), autoseleccionando el banco si solo hay uno;refresh();selectBank(toggle de selección única);generate()→PaymentLinkResult(record({link, failure})). ElPaymentLinkStateguardabanks,items,debits,accountName/accountCode/customerTaxId,selectedBankName,isGenerating,lastSyncAt, y los getterstotalAmount(suma de lositems),hasBanks,canConfirmeisSelected.- Entities, UseCase e RPCEntities, UseCase & RPCEntities, UseCase y RPC
PaymentLinkBankEntity(bankName·bankIconBase64·isCompany·transactionLimit; gettershasIcon/hasTransactionLimit),PaymentLinkItemEntity(debitOpenItemSfid·paymentAmount·invoiceLegalNumber·orderSfid) ePaymentLinkEntity(url·bankOrderId·bankName; getterhasUrl).CreatePaymentLinkUseCaseexpõegetBanks(resourceSfid)eexecute(...)— este chama o repository e, no sucesso, marca os documentos como payment-link pending. As RPCsgetBankListecreatePaymentLinkficam noFinancialManagementConectaRepService(FinancialManagementConectaRep.proto); o reply trazurl,bankOrderId,bankName(e umhtmlResponsenão usado).PaymentLinkBankEntity(bankName·bankIconBase64·isCompany·transactionLimit; gettershasIcon/hasTransactionLimit),PaymentLinkItemEntity(debitOpenItemSfid·paymentAmount·invoiceLegalNumber·orderSfid) andPaymentLinkEntity(url·bankOrderId·bankName; getterhasUrl).CreatePaymentLinkUseCaseexposesgetBanks(resourceSfid)andexecute(...)— the latter calls the repository and, on success, marks the documents as payment-link pending. ThegetBankListandcreatePaymentLinkRPCs live onFinancialManagementConectaRepService(FinancialManagementConectaRep.proto); the reply carriesurl,bankOrderId,bankName(and an unusedhtmlResponse).PaymentLinkBankEntity(bankName·bankIconBase64·isCompany·transactionLimit; gettershasIcon/hasTransactionLimit),PaymentLinkItemEntity(debitOpenItemSfid·paymentAmount·invoiceLegalNumber·orderSfid) yPaymentLinkEntity(url·bankOrderId·bankName; getterhasUrl).CreatePaymentLinkUseCaseexponegetBanks(resourceSfid)yexecute(...)— este llama al repository y, en éxito, marca los documentos como payment-link pending. Las RPCgetBankListycreatePaymentLinkviven enFinancialManagementConectaRepService(FinancialManagementConectaRep.proto); el reply traeurl,bankOrderId,bankName(y unhtmlResponseno usado).
Modelo de dadosData modelModelo de datos
O pagamento tem duas famílias de estruturas: as do rascunho (domínio puro, client-side, sem proto/DTO/Model) e as do registro persistido (Entity + Model ObjectBox). O que a tela consome de leitura (bancos, notas de crédito, documentos) pertence ao aggregate de gestão financeira e está documentado lá.The payment has two families of structures: the draft ones (pure domain, client-side, no proto/DTO/Model) and the persisted register ones (Entity + ObjectBox Model). What the screen reads (banks, credit notes, documents) belongs to the financial management aggregate and is documented there.El pago tiene dos familias de estructuras: las del borrador (dominio puro, client-side, sin proto/DTO/Model) y las del registro persistido (Entity + Model ObjectBox). Lo que la pantalla lee (bancos, notas de crédito, documentos) pertenece al aggregate de gestión financiera y está documentado allí.
Rascunho (client-side)Draft (client-side)Borrador (client-side)
PaymentDraftEntity paymentDraftProvider 3 camposfieldscampos
Campo Entity NotaNoteNota groupIdString identifica o pagamento inteiro; gerado na confirmaçãoidentifies the whole payment; generated on confirmidentifica el pago completo; generado al confirmar debitsList<PaymentDebitEntity> semeado pela tela de origemseeded by the origin screensembrado por la pantalla de origen methodsList<PaymentMethodEntryEntity> 1 a maxPaymentMethodsPerPayment1 tomaxPaymentMethodsPerPayment1 amaxPaymentMethodsPerPaymentPaymentDebitEntity draft.debits[] 6 camposfieldscampos
Campo Entity NotaNoteNota debitOpenItemSfidString vazio no pedido prompt (DPI ainda não existe)empty in the prompt order (DPI doesn't exist yet)vacío en el pedido prompt (el DPI aún no existe) nameString — invoiceNumberString — totalAmountdouble saldo em aberto do documentodocument outstanding balancesaldo abierto del documento creditPerioddouble -1no pedido prompt-1in the prompt order-1en el pedido promptdueDateDateTime? — PaymentMethodEntryEntity draft.methods[] 12 camposfieldscampos
Campo Entity NotaNoteNota methodPaymentMethod enum; PBnunca é selecionávelenum;PBis never selectableenum;PBnunca es seleccionablebankSfid·bankBranchSfidString obrigatórios fora de nota de créditorequired except for credit noteobligatorios excepto nota de crédito collectionReferenceString número digitado (transferência/depósito/cheque/…)typed number (transfer/deposit/cheque/…)número ingresado (transferencia/depósito/cheque/…) paymentDateDateTime? janela por forma (ver 10)window per method (see 10)ventana por método (ver 10) amountdouble valor da forma, não do documentothe method's amount, not the document'smonto del método, no del documento creditNotesList<PaymentCreditNoteSelectionEntity> só nota de crédito; define o valorcredit note only; defines the amountsolo nota de crédito; define el monto evidencePhoto·evidenceAttachmentCapturedFileEntity? arquivos da sessão de capturafiles from the capture sessionarchivos de la sesión de captura evidenceImageBase64·evidenceFileBase64·evidenceFileNameString preenchidos ao salvar um rascunho diferidofilled when saving a deferred draftcompletados al guardar un borrador diferido paymentIdMobileString identifica a forma dentro do pagamentoidentifies the method inside the paymentidentifica el método dentro del pago
PaymentDraftEntity concentra a matemática: totalDebitAmount, totalMethodAmount, remainingBalance, excessAmount e o allocate() que produz PaymentMethodAllocationEntity → PaymentDebitAllocationEntity (a cascata). Toda soma e arredondamento passam por CurrencyUtils.PaymentDraftEntity holds the math: totalDebitAmount, totalMethodAmount, remainingBalance, excessAmount and the allocate() that produces PaymentMethodAllocationEntity → PaymentDebitAllocationEntity (the waterfall). Every sum and rounding goes through CurrencyUtils.PaymentDraftEntity concentra la matemática: totalDebitAmount, totalMethodAmount, remainingBalance, excessAmount y el allocate() que produce PaymentMethodAllocationEntity → PaymentDebitAllocationEntity (la cascada). Toda suma y redondeo pasa por CurrencyUtils.
Registro persistidoPersisted registerRegistro persistido
PaymentRegisterEntity PaymentRegisterModel · ObjectBox 28 camposfieldscampos
Campo Entity Model NotaNoteNota localIdint idid do ObjectBoxObjectBox idid de ObjectBox groupId·paymentIdMobileString String idempotência no reenvioidempotency on resendidempotencia en el reenvío originPaymentCreationOrigin String — statusPaymentRegisterStatus String ORDER_PA·CREATED·READY·SENTaccountSfid·accountSapCode·accountNameString String — debitOpenItemSfid·debitOpenItemNameString String preenchidos quando o DPI é casadofilled when the DPI is matchedcompletados cuando el DPI se empareja invoiceLegalNumber·orderSfid·purchaseOrderNumberString String chaves de casamento do DPIDPI matching keysclaves de emparejamiento del DPI methodPaymentMethod String (code) — bankSfid·bankBranchSfid·collectionReferenceString String — creditNotesList<…SelectionEntity> 3 × List<String/double> sfid, referência e valor em listas paralelassfid, reference and amount in parallel listssfid, referencia y monto en listas paralelas documentAmount·payedAmount·creditPeriod·orderAmountdouble double — paymentDate·documentDate·createdAtDateTime? DateTime? — evidenceImageBase64·evidenceFileBase64·evidenceFileNameString String o comprovante sobrevive ao restartthe proof survives a restartel comprobante sobrevive al reinicio evidenceStatusPaymentEvidenceStatus String NONE·PENDING·SENT·ERRORerrorMessageString String código da falha do último enviolast send's failure codecódigo de la falla del último envío
toDraft() reconstrói um PaymentDraftEntity de uma forma só a partir do registro — é assim que a sincronização manual reaproveita o mesmo builder de payload.toDraft() rebuilds a single-method PaymentDraftEntity from the register — that's how the manual sync reuses the same payload builder.toDraft() reconstruye un PaymentDraftEntity de un solo método a partir del registro — así la sincronización manual reutiliza el mismo builder de payload.
TransaçõesTransactionsTransacciones
| DispatcherType | serviceName | QuandoWhenCuándo | BuilderBuilderBuilder |
|---|---|---|---|
payment | PaymentCollectionAPI | sempre (na hora ou na sincronização manual)always (right away or on manual sync)siempre (al instante o en la sincronización manual) | BuildPaymentCollectionDispatcherPayloadUseCase |
financialProofOfPayment | FinancialProofPaymentAPI | se houver comprovante · 1 por documentoif there's a proof · 1 per documentsi hay comprobante · 1 por documento | BuildFinancialProofPaymentDispatcherPayloadUseCase |
cashPaymentReport | CashPaymentReportAPI | origens entrega e pedido promptdelivery and prompt order originsorígenes entrega y pedido prompt | BuildCashPaymentReportDispatcherPayloadUseCase |
O payload do PaymentCollectionAPI é uma lista: o rascunho é achatado em forma × documento alocado × referência. Detalhe campo-a-campo em docs_old/dispatcher/NN_PaymentCollectionAPI/ e NN_CashPaymentReportAPI/.The PaymentCollectionAPI payload is a list: the draft is flattened into method × allocated document × reference. Field-by-field detail in docs_old/dispatcher/NN_PaymentCollectionAPI/ and NN_CashPaymentReportAPI/.El payload de PaymentCollectionAPI es una lista: el borrador se aplana en método × documento asignado × referencia. Detalle campo a campo en docs_old/dispatcher/NN_PaymentCollectionAPI/ y NN_CashPaymentReportAPI/.
Duas datas, dois contratosTwo dates, two contractsDos fechas, dos contratos
No PaymentCollectionAPI, paymentDate é a data de envio e chequeDate é a data escolhida pelo representante — contrato pedido pelo time de API do Salesforce, reproduzido do legado. Além disso, paymentMode leva o nome de API da forma (Cash, Cheque…), enquanto o CashPaymentReportAPI leva o code (ZH, ZC…).
In PaymentCollectionAPI, paymentDate is the submission date and chequeDate is the date the rep chose — a contract requested by the Salesforce API team, reproduced from the legacy app. Also, paymentMode carries the method's API name (Cash, Cheque…), while CashPaymentReportAPI carries the code (ZH, ZC…).
En PaymentCollectionAPI, paymentDate es la fecha de envío y chequeDate es la fecha elegida por el representante — contrato pedido por el equipo de API de Salesforce, reproducido del legado. Además, paymentMode lleva el nombre de API del método (Cash, Cheque…), mientras CashPaymentReportAPI lleva el code (ZH, ZC…).
Repository
| Repository | MétodoMethodMétodo | O que fazWhat it doesQué hace |
|---|---|---|
PaymentRegisterRepository | getPaymentRegisters | lista os registros locais (mais recentes primeiro)lists the local registers (newest first)lista los registros locales (más recientes primero) |
savePaymentRegister | grava/atualiza um registrowrites/updates one registergraba/actualiza un registro | |
savePaymentRegisters | grava em lote (um por forma × documento)batch write (one per method × document)grabado en lote (uno por método × documento) | |
removePaymentRegister | remove por id localremoves by local idelimina por id local | |
FinancialManagementRepository | applyPaymentAllocations | abate o valor pago do saldo do DPI; zera e marca collected (e limpa overdue) quando o saldo acabawrites the paid amount down the DPI balance; zeroes it and marks collected (clearing overdue) when the balance runs outdescuenta el monto pagado del saldo del DPI; lo pone en cero y marca collected (limpiando overdue) cuando el saldo se agota |
markCreditNotesUsed | marca as notas usadas (isUsed, valor zerado)marks the used notes (isUsed, amount zeroed)marca las notas usadas (isUsed, monto en cero) |
Enums e regras de campoEnums & field rulesEnums y reglas de campo
As regras de cada forma de pagamento vivem no próprio PaymentMethod (domínio) e na sua extension de UX (labels), nunca espalhadas em widgets:Each method's rules live on PaymentMethod itself (domain) and on its UX extension (labels), never scattered across widgets:Las reglas de cada método viven en PaymentMethod mismo (dominio) y en su extension de UX (labels), nunca dispersas en widgets:
| FormaMethodMétodo | code | apiName | ReferênciaReferenceReferencia | BancoBankBanco | Janela de dataDate windowVentana de fecha |
|---|---|---|---|---|---|
| TransferênciaTransferTransferencia | ZE | Electronic Funds Transfer | nº da transferênciatransfer no.nº de transferencia | ✓ | 8 semanas atrás → hoje (fim de semana ok)8 weeks back → today (weekends ok)8 semanas atrás → hoy (fines de semana ok) |
| DepósitoDepositDepósito | ZB | Bank Deposit | nº do depósitodeposit no.nº de depósito | ✓ | 8 semanas atrás → hoje (fim de semana ok)8 weeks back → today (weekends ok)8 semanas atrás → hoy (fines de semana ok) |
| ChequeChequeCheque | ZC | Cheque | nº do chequecheque no.nº de cheque | ✓ | só hojetoday onlysolo hoy |
| Cheque a fechaPost-dated chequeCheque a fecha | ZI | Promissory Note | nº do chequecheque no.nº de cheque | ✓ | próximo dia útil → +28 diasnext business day → +28 dayspróximo día hábil → +28 días |
| Nota de créditoCredit noteNota de crédito | Z9 | Credit Note | — (seleção de notas)— (note selection)— (selección de notas) | — | dia útil anterior → próximoprevious business day → nextdía hábil anterior → siguiente |
| EfetivoCashEfectivo | ZH | Cash | númeronumbernúmero | ✓ | só hojetoday onlysolo hoy |
| Botão de pagamentoPayment buttonBotón de pago | PB | — | não selecionável — só define ícone/ordenação e a entrada de linknot selectable — only drives icon/ordering and the link entryno seleccionable — solo define ícono/orden y la entrada de link | ||
Outros enums: PaymentCreationOrigin (4 origens — financialManagement, collections, promptOrder, delivery — mais o fallback unknown; as 5 entradas mapeiam em 4 origens porque "Detalhe do documento" reusa a origem financialManagement. Cada valor expõe getters de regra: requiresStartedVisit, sendsOnConfirm, hasEditableAmount, requiresDebitOpenItem, requiresFullAmountCoverage, reportsCashPayment…), PaymentRegisterStatus, PaymentEvidenceStatus, PaymentValidationIssue (+ extension que mapeia cada erro para sua chave de tradução).Other enums: PaymentCreationOrigin (4 origins — financialManagement, collections, promptOrder, delivery — plus the unknown fallback; the 5 entry points map onto 4 origins because "Document detail" reuses the financialManagement origin. Each value exposes rule getters: requiresStartedVisit, sendsOnConfirm, hasEditableAmount, requiresDebitOpenItem, requiresFullAmountCoverage, reportsCashPayment…), PaymentRegisterStatus, PaymentEvidenceStatus, PaymentValidationIssue (+ the extension mapping each error to its translation key).Otros enums: PaymentCreationOrigin (4 orígenes — financialManagement, collections, promptOrder, delivery — más el fallback unknown; las 5 entradas mapean en 4 orígenes porque "Detalle del documento" reutiliza el origen financialManagement. Cada valor expone getters de regla: requiresStartedVisit, sendsOnConfirm, hasEditableAmount, requiresDebitOpenItem, requiresFullAmountCoverage, reportsCashPayment…), PaymentRegisterStatus, PaymentEvidenceStatus, PaymentValidationIssue (+ la extension que mapea cada error a su clave de traducción).
UseCases
| UseCase | ResponsabilidadeResponsibilityResponsabilidad |
|---|---|
ValidatePaymentDraftUseCase | todas as regras de campo e de valor, por origem/mercado/tipo de rep; devolve erros gerais + erros por formaevery field and amount rule, per origin/market/rep type; returns general issues + per-method issuestodas las reglas de campo y de monto, por origen/mercado/tipo de rep; devuelve errores generales + errores por método |
ResolvePaymentDateRangeUseCase | janela de data de cada forma (dias úteis via DateTimeUtils)each method's date window (business days via DateTimeUtils)ventana de fecha de cada método (días hábiles vía DateTimeUtils) |
ResolveAccountPaymentMethodsUseCase | opções do varejo sem PB + qual vem pré-selecionada (preferido em cobranças; ZE/ZB em qualquer origem; senão o primeiro da lista)the retail's options without PB + which comes pre-selected (preferred in collections; ZE/ZB in any origin; otherwise the list's first)opciones del punto de venta sin PB + cuál viene preseleccionada (preferido en cobranzas; ZE/ZB en cualquier origen; si no, el primero de la lista) |
GetPaymentRegistersUseCase | todos · por documento · não sincronizadosall · by document · unsettledtodos · por documento · no sincronizados |
ResolvePendingPaymentRegistersUseCase | casa o DPI que chegou (por orderSfid, com fallback no nº legal da nota fiscal) e promove o registro a READYmatches the arrived DPI (by orderSfid, falling back to the invoice legal number) and promotes the register to READYempareja el DPI que llegó (por orderSfid, con fallback en el nº legal de la factura) y promueve el registro a READY |
SyncPaymentRegisterUseCase | reúne DPI/pedido/visita e delega ao orquestrador a sincronização de um registro READYgathers DPI/order/visit and delegates the sync of a READY register to the orchestratorreúne DPI/pedido/visita y delega al orquestador la sincronización de un registro READY |
PaymentSubmissionOrchestrator | o coração da escrita: submit (imediato ou diferido) e syncRegister — despacho, efeitos locais, comprovante e relatório de pagamento em dinheirothe write's heart: submit (immediate or deferred) and syncRegister — dispatch, local effects, proof and cash payment reportel corazón de la escritura: submit (inmediato o diferido) y syncRegister — despacho, efectos locales, comprobante y reporte de pago en efectivo |
Notifier & State
PaymentCreationNotifier é uma família por (draftKey, origin, accountSfid) — só identificadores, nunca entidades pela rota. O _load lê o rascunho semeado no paymentDraftProvider, o EMC, o representante, as formas do varejo, bancos e notas de crédito; se não houver rascunho, falha com BusinessFailure.PaymentCreationNotifier is a family keyed by (draftKey, origin, accountSfid) — identifiers only, never entities through the route. _load reads the draft seeded in paymentDraftProvider, the EMC, the rep, the retail's methods, banks and credit notes; with no draft it fails with BusinessFailure.PaymentCreationNotifier es una familia por (draftKey, origin, accountSfid) — solo identificadores, nunca entidades por la ruta. _load lee el borrador sembrado en paymentDraftProvider, el EMC, el representante, los métodos del punto de venta, bancos y notas de crédito; sin borrador falla con BusinessFailure.
| MétodoMethodMétodo | EfeitoEffectEfecto |
|---|---|
selectMethod | troca a forma e limpa os campos dependentesswitches the method and clears the dependent fieldscambia el método y limpia los campos dependientes |
selectBank · selectBankBranch | banco limpa a agênciabank clears the branchbanco limpia la sucursal |
setCollectionReference · setPaymentDate · setAmount | campos simples; valor só quando a origem permite editarplain fields; amount only when the origin allows editingcampos simples; monto solo cuando el origen permite editar |
useRemainingAmount | preenche a forma com o que falta cobrirfills the method with what's left to covercompleta el método con lo que falta cubrir |
setCreditNotes | define as notas e trava o valor na soma delassets the notes and locks the amount to their sumdefine las notas y fija el monto en su suma |
addMethod · removeMethod | respeita o teto do mercado; ao remover, apaga os arquivos daquela formarespects the market cap; removing deletes that method's filesrespeta el tope del mercado; al quitar, borra los archivos de ese método |
captureEvidencePhoto · pickEvidenceFile · remove… | sessão de captura própria, limpa no disposeown capture session, cleaned on disposesesión de captura propia, limpiada en dispose |
waiveEvidence | o representante escolheu seguir sem comprovante (só quando não é obrigatório)the rep chose to continue without proof (only when not mandatory)el representante eligió seguir sin comprobante (solo cuando no es obligatorio) |
resolveExcessTargetDebit · applyExcessRedirect | acha o documento aberto mais antigo e injeta o excedentefinds the oldest open document and injects the excessencuentra el documento abierto más antiguo e inyecta el excedente |
submit | valida → gera ids → envia (ou salva) → devolve PaymentCreationOutcomevalidates → generates ids → sends (or saves) → returns a PaymentCreationOutcomevalida → genera ids → envía (o guarda) → devuelve un PaymentCreationOutcome |
O PaymentCreationState guarda o rascunho + o contexto (formas, bancos, notas, EMC, tipo de rep) e expõe os derivados que a UI consome: totalDebitAmount, remainingBalance, canAddMethod, isEvidenceMandatory, canRedirectExcess, methodOptionsFor (não repete a forma já usada em outro card) e issuesForMethod.PaymentCreationState holds the draft + the context (methods, banks, notes, EMC, rep type) and exposes the derived values the UI consumes: totalDebitAmount, remainingBalance, canAddMethod, isEvidenceMandatory, canRedirectExcess, methodOptionsFor (doesn't repeat a method already used in another card) and issuesForMethod.PaymentCreationState guarda el borrador + el contexto (métodos, bancos, notas, EMC, tipo de rep) y expone los derivados que la UI consume: totalDebitAmount, remainingBalance, canAddMethod, isEvidenceMandatory, canRedirectExcess, methodOptionsFor (no repite un método ya usado en otro card) y issuesForMethod.
Page e widgetsPage & widgetsPage y widgets
| ArquivoFileArchivo | PapelRoleRol |
|---|---|
payment_creation_page.dart | lista os filhos e empilha a barra de resumo; nenhuma decisão de visibilidadelists the children and stacks the summary bar; no visibility decisionlista los hijos y apila la barra de resumen; ninguna decisión de visibilidad |
PaymentDebitsSummary (shared)(shared)(shared) | card só-leitura dos documentos (widget compartilhado shared/widgets/payment_debits_summary/)read-only documents card (shared widget shared/widgets/payment_debits_summary/)card de solo lectura de los documentos (widget compartido shared/widgets/payment_debits_summary/) |
payment_creation_payment_link_widget.dart | botão ETPay + divisor "OU"; navega ao subfluxo de link (goToPaymentLinkBankSelection) — ver Link de pagamentoETPay button + "OR" divider; navigates to the link subflow (goToPaymentLinkBankSelection) — see Payment linkbotón ETPay + divisor "O"; navega al subflujo de link (goToPaymentLinkBankSelection) — ver Link de pago |
payment_creation_method_form_widget.dart | o formulário de uma forma; controllers de referência/valor/data e erros inlineone method's form; reference/amount/date controllers and inline errorsel formulario de un método; controllers de referencia/monto/fecha y errores inline |
payment_creation_evidence_row_widget.dart | botões de foto/arquivo + miniaturasphoto/file buttons + thumbnailsbotones de foto/archivo + miniaturas |
payment_creation_add_method_widget.dart | adicionar forma (avisa se o total já foi alcançado)add method (warns if the total was already reached)agregar método (avisa si el total ya se alcanzó) |
payment_creation_footer_widget.dart | totais, confirmar/salvar e a sequência de modais (comprovante ausente → excedente → envio)totals, confirm/save and the modal sequence (missing proof → excess → send)totales, confirmar/guardar y la secuencia de modales (comprobante ausente → excedente → envío) |
modals/payment_credit_note_picker_modal_content.dart | seleção múltipla de notas de crédito com totalmulti-select of credit notes with totalselección múltiple de notas de crédito con total |
Entradas nas outras features: financial_management_sticky_footer_widget, debit_open_item_detail_pay_button_widget + …_payments_widget, order_payment_configure_payment_widget e delivery_action_buttons_widget. Todas semeiam o rascunho, navegam e, na volta, recarregam o que mudou.Entry points in the other features: financial_management_sticky_footer_widget, debit_open_item_detail_pay_button_widget + …_payments_widget, order_payment_configure_payment_widget and delivery_action_buttons_widget. All seed the draft, navigate and, on return, reload what changed.Entradas en las otras features: financial_management_sticky_footer_widget, debit_open_item_detail_pay_button_widget + …_payments_widget, order_payment_configure_payment_widget y delivery_action_buttons_widget. Todas siembran el borrador, navegan y, al volver, recargan lo que cambió.
MercadosMarketsMercados
A criação de pagamentos é dirigida pelo End Market Configuration: o módulo financial_management_payment_creation só é declarado no Chile. Onde ele não existe, a seleção de documentos e os botões de pagar não aparecem.Payment creation is driven by the End Market Configuration: the financial_management_payment_creation module is declared only in Chile. Where it doesn't exist, the document selection and the pay buttons don't show.La creación de pagos es dirigida por el End Market Configuration: el módulo financial_management_payment_creation solo se declara en Chile. Donde no existe, la selección de documentos y los botones de pagar no aparecen.
Config por mercado (BR/CL/ZA; AR/PY/PE seguem o default PANGEA — módulo ausente):Per-market config (BR/CL/ZA; AR/PY/PE follow the PANGEA default — module absent):Config por mercado (BR/CL/ZA; AR/PY/PE siguen el default PANGEA — módulo ausente):
| ConfigConfigConfig | BR | CL | ZA | EfeitoEffectEfecto |
|---|---|---|---|---|
financial_management_payment_creation | — | ✓ | — | habilita a feature inteira (seleção, botões, aba do Data Center)enables the whole feature (selection, buttons, Data Center tab)habilita toda la feature (selección, botones, pestaña del Data Center) |
financial_management_payment_link | — | ✓ | — | habilita a entrada ETPay + o subfluxo de link de pagamento (ver Link de pagamento)enables the ETPay entry + the payment link subflow (see Payment link)habilita la entrada ETPay + el subflujo de link de pago (ver Link de pago) |
allowMultiplePaymentMethodsPerDpi | false | true | false | permite mais de uma forma no mesmo pagamentoallows more than one method in the same paymentpermite más de un método en el mismo pago |
maxPaymentMethodsPerPayment | 1 | 3 | 1 | teto de formasmethod captope de métodos |
allowPaymentExcessRedirect | false | true | false | oferece redirecionar o excedenteoffers to redirect the excessofrece redirigir el excedente |
fullPaymentRequiredResourceTypes | [] | ["Pre-sales Rep"] | [] | tipos de rep obrigados a pagar o documento integralmenterep types required to pay the document in fulltipos de rep obligados a pagar el documento íntegramente |
A obrigatoriedade do comprovante não é configuração de EMC: o cliente a define no admin por resource type e o backend resolve, enviando isProofOfPaymentMandatory (booleano) no FinancialManagementConectaRep.proto. O app apenas lê a flag da FinancialManagementEntity — quando ela vem true, o envio fica bloqueado enquanto algum método estiver sem comprovante.
The proof requirement is not EMC configuration: the client sets it per resource type in the admin and the backend resolves it, sending isProofOfPaymentMandatory (boolean) in FinancialManagementConectaRep.proto. The app only reads the flag from FinancialManagementEntity — when it comes back true, submitting stays blocked while any method has no proof attached.
La obligatoriedad del comprobante no es configuración de EMC: el cliente la define en el admin por resource type y el backend la resuelve, enviando isProofOfPaymentMandatory (booleano) en FinancialManagementConectaRep.proto. La app solo lee la flag de FinancialManagementEntity — cuando llega true, el envío queda bloqueado mientras algún método no tenga comprobante.