@fiado/type-kit 3.631.0 → 3.632.0

package/_test_/unit/retailIntegration/retailSaleContracts.test.ts

@@ -145,6 +145,18 @@ describe('RetailSystemSale.payments', () => {
         expect(await errorsOf(RetailSystemSale, { ...sale, payments: [cashPayment, { ...wirePayment, senderClabe: null }] })).toEqual([]);
     });
 
+    it('acepta CARD y WIRE sin comprobante', async () => {
+        const card = { ...cardPayment, cardLast4: null, authCode: null };
+        const wire = { ...wirePayment, speiTrackingKey: null, senderClabe: null };
+        expect(await errorsOf(RetailSystemSale, { ...sale, payments: [cashPayment, card] })).toEqual([]);
+        expect(await errorsOf(RetailSystemSale, { ...sale, payments: [cashPayment, wire] })).toEqual([]);
+    });
+
+    it('acepta tarjeta repetida y tres medios', async () => {
+        const cards = [{ ...cardPayment, amount: '100.00' }, { ...cardPayment, amount: '100.00', cardLast4: null }];
+        expect(await errorsOf(RetailSystemSale, { ...sale, payments: [cashPayment, ...cards] })).toEqual([]);
+    });
+
     it('acepta speiTrackingKey de 1 a 30 alfanuméricos', async () => {
         expect(await errorsOf(RetailSystemSale, { ...sale, payments: [cashPayment, { ...wirePayment, speiTrackingKey: '7' }] })).toEqual([]);
         expect(await errorsOf(RetailSystemSale, { ...sale, payments: [cashPayment, { ...wirePayment, speiTrackingKey: 'A'.repeat(30) }] })).toEqual([]);
@@ -174,9 +186,9 @@ describe('RetailSystemSale.payments', () => {
     });
 
     it.each([
-        ['cardLast4', { cardLast4: null }],
+        ['cardLast4', { cardLast4: undefined }],
         ['cardLast4', { cardLast4: '424' }],
-        ['authCode', { authCode: null }],
+        ['authCode', { authCode: undefined }],
         ['authCode', { authCode: ' ' }],
         ['authCode', { authCode: 'A'.repeat(65) }],
         ['speiTrackingKey', { speiTrackingKey: '123456789012345678' }],
@@ -186,7 +198,7 @@ describe('RetailSystemSale.payments', () => {
     });
 
     it.each([
-        ['speiTrackingKey', { speiTrackingKey: null }],
+        ['speiTrackingKey', { speiTrackingKey: undefined }],
         ['speiTrackingKey', { speiTrackingKey: '' }],
         ['speiTrackingKey', { speiTrackingKey: 'A'.repeat(31) }],
         ['speiTrackingKey', { speiTrackingKey: 'MBAN-0100-2610' }],

package/_test_/unit/retailWizard/accessorySaleRequests.test.ts

@@ -45,9 +45,9 @@ describe('CreateAccessorySaleRequest', () => {
     expect(errorsOf(CreateAccessorySaleRequest, { ...validSale, amountCents: 10.5 })).toContain('amountCents');
   });
 
-  it('exige el comprobante del cobro', () => {
+  it('acepta el cobro sin comprobante', () => {
     const { paymentDetail: _omit, ...rest } = validSale;
-    expect(errorsOf(CreateAccessorySaleRequest, rest)).toContain('paymentDetail');
+    expect(errorsOf(CreateAccessorySaleRequest, rest)).toEqual([]);
   });
 
   it('no lleva aviso de privacidad: privacyNoticeAccepted y privacyNoticeVersion se descartan', () => {

package/_test_/unit/retailWizard/salePayments.test.ts

@@ -0,0 +1,140 @@
+import 'reflect-metadata';
+import { plainToInstance } from 'class-transformer';
+import { validateSync, type ValidationError } from 'class-validator';
+import { SalePayment } from '../../../src/retailWizard/dtos/SalePayment';
+import { WizardPayment } from '../../../src/retailWizard/dtos/WizardPayment';
+import { RegisterPaymentRequest } from '../../../src/retailWizard/dtos/requests/RegisterPaymentRequest';
+import { DownPaymentRequest } from '../../../src/retailWizard/dtos/requests/DownPaymentRequest';
+import { CreateAccessorySaleRequest } from '../../../src/retailWizard/dtos/requests/CreateAccessorySaleRequest';
+import { RetailPromotionInboundMessage } from '../../../src/retailWizard/events/RetailPromotionInboundMessage';
+import { MAX_SALE_PAYMENTS, SINGLE_USE_PAYMENT_METHODS } from '../../../src/retailWizard/constants/retailWizardValidation';
+import { SalePaymentMethodEnum } from '../../../src/retailWizard/enums/SalePaymentMethodEnum';
+import * as RetailWizard from '../../../src/retailWizard';
+
+const { CASH, CARD, WIRE } = SalePaymentMethodEnum;
+
+function paths(errors: ValidationError[], prefix = ''): string[] {
+  return errors.flatMap((e) => {
+    const path = `${prefix}${e.property}`;
+    return e.children?.length ? paths(e.children, `${path}.`) : [path];
+  });
+}
+
+function errorsOf<T extends object>(cls: new () => T, payload: Record<string, unknown>): string[] {
+  return paths(validateSync(plainToInstance(cls, payload, { excludeExtraneousValues: true })));
+}
+
+const cash = { method: CASH, amountCents: 10000, cashConfirmedInRegister: true };
+const card = { method: CARD, amountCents: 5000, cardLast4: '4242', authCode: 'A1B2C3' };
+const wire = { method: WIRE, amountCents: 5000, speiTrackingKey: 'MBAN01002610', senderClabe: '012180001234567897' };
+
+describe('SalePayment', () => {
+  it('acepta cada medio con comprobante', () => {
+    expect(errorsOf(SalePayment, cash)).toEqual([]);
+    expect(errorsOf(SalePayment, card)).toEqual([]);
+    expect(errorsOf(SalePayment, wire)).toEqual([]);
+  });
+
+  it('acepta tarjeta y SPEI sin comprobante, ausente o en null', () => {
+    expect(errorsOf(SalePayment, { method: CARD, amountCents: 5000 })).toEqual([]);
+    expect(errorsOf(SalePayment, { method: WIRE, amountCents: 5000, speiTrackingKey: null, senderClabe: null })).toEqual([]);
+    expect(errorsOf(SalePayment, { method: CASH, amountCents: 5000, cashConfirmedInRegister: null })).toEqual([]);
+  });
+
+  it.each([
+    ['cardLast4', { ...card, cardLast4: '424' }],
+    ['authCode', { ...card, authCode: ' ' }],
+    ['authCode', { ...card, authCode: 'A'.repeat(65) }],
+    ['speiTrackingKey', { ...wire, speiTrackingKey: 'MBAN-01' }],
+    ['senderClabe', { ...wire, senderClabe: '0121' }],
+    ['cashConfirmedInRegister', { ...cash, cashConfirmedInRegister: 'yes' }],
+  ])('rechaza %s con formato inválido', (field, payload) => {
+    expect(errorsOf(SalePayment, payload)).toEqual([field]);
+  });
+
+  it.each([
+    ['cardLast4', { ...cash, cardLast4: '4242' }],
+    ['speiTrackingKey', { ...card, speiTrackingKey: 'MBAN01' }],
+    ['cashConfirmedInRegister', { ...wire, cashConfirmedInRegister: true }],
+  ])('rechaza %s en un medio que no le corresponde', (field, payload) => {
+    expect(errorsOf(SalePayment, payload)).toEqual([field]);
+  });
+
+  it('rechaza un medio fuera del enum y un monto no positivo', () => {
+    expect(errorsOf(SalePayment, { method: 'FIADO', amountCents: 100 })).toEqual(['method']);
+    expect(errorsOf(SalePayment, { ...cash, amountCents: 0 })).toEqual(['amountCents']);
+    expect(errorsOf(SalePayment, { ...cash, amountCents: 10.5 })).toEqual(['amountCents']);
+  });
+});
+
+describe('payments en RegisterPaymentRequest', () => {
+  it('acepta solo payments, sin method ni detail', () => {
+    expect(errorsOf(RegisterPaymentRequest, { amountCents: 20000, payments: [cash, card, wire] })).toEqual([]);
+  });
+
+  it('acepta tarjeta repetida', () => {
+    expect(errorsOf(RegisterPaymentRequest, { amountCents: 20000, payments: [cash, card, card] })).toEqual([]);
+  });
+
+  it('sigue aceptando el formato viejo', () => {
+    expect(errorsOf(RegisterPaymentRequest, { method: CASH, amountCents: 20000, detail: { cashConfirmedInRegister: true } })).toEqual([]);
+  });
+
+  it('exige method si no vienen payments', () => {
+    expect(errorsOf(RegisterPaymentRequest, { amountCents: 20000 })).toEqual(['method']);
+  });
+
+  it('rechaza efectivo o SPEI repetidos', () => {
+    expect(errorsOf(RegisterPaymentRequest, { amountCents: 20000, payments: [cash, cash] })).toEqual(['payments']);
+    expect(errorsOf(RegisterPaymentRequest, { amountCents: 10000, payments: [wire, wire] })).toEqual(['payments']);
+  });
+
+  it(`rechaza más de ${MAX_SALE_PAYMENTS} pagos o una lista vacía`, () => {
+    expect(errorsOf(RegisterPaymentRequest, { amountCents: 25000, payments: [cash, card, card, wire] })).toEqual(['payments']);
+    expect(errorsOf(RegisterPaymentRequest, { amountCents: 0, payments: [] })).toEqual(['payments']);
+  });
+
+  it('rechaza que la suma no cuadre con amountCents', () => {
+    expect(errorsOf(RegisterPaymentRequest, { amountCents: 20001, payments: [cash, card, wire] })).toEqual(['payments']);
+  });
+
+  it('reporta el campo del pago inválido', () => {
+    expect(errorsOf(RegisterPaymentRequest, { amountCents: 15000, payments: [cash, { ...card, cardLast4: '1' }] })).toEqual([
+      'payments.1.cardLast4',
+    ]);
+  });
+});
+
+describe('payments en los demás contratos', () => {
+  it('DownPaymentRequest acepta solo payments y valida la suma', () => {
+    expect(errorsOf(DownPaymentRequest, { amountCents: 15000, payments: [cash, wire] })).toEqual([]);
+    expect(errorsOf(DownPaymentRequest, { amountCents: 1, payments: [cash, wire] })).toEqual(['payments']);
+  });
+
+  it('CreateAccessorySaleRequest acepta solo payments y ya no exige paymentDetail', () => {
+    const lines = [{ sku: 'ACC-1', qty: 1 }];
+    expect(errorsOf(CreateAccessorySaleRequest, { lines, amountCents: 15000, payments: [cash, card] })).toEqual([]);
+    expect(errorsOf(CreateAccessorySaleRequest, { lines, amountCents: 15000 })).toEqual(['paymentMethod']);
+    expect(errorsOf(CreateAccessorySaleRequest, { lines, amountCents: 20000, payments: [cash, cash] })).toEqual(['payments']);
+  });
+
+  it('WizardPayment guarda payments tipados', () => {
+    const base = { method: CASH, amountCents: 15000, paidAt: '2026-11-03T10:00:00.000Z' };
+    expect(errorsOf(WizardPayment, { ...base, payments: [cash, card] })).toEqual([]);
+    expect(errorsOf(WizardPayment, base)).toEqual([]);
+    expect(errorsOf(WizardPayment, { ...base, payments: [cash, cash] })).toEqual(['payments']);
+  });
+
+  it('RetailPromotionInboundMessage acepta paymentMethods y rechaza valores fuera del enum', () => {
+    const plain = { paymentMethods: [CASH, CARD] };
+    const dto = plainToInstance(RetailPromotionInboundMessage, plain);
+    expect(paths(validateSync(dto)).filter((p) => p === 'paymentMethods')).toEqual([]);
+    const bad = plainToInstance(RetailPromotionInboundMessage, { paymentMethods: ['FIADO'] });
+    expect(paths(validateSync(bad))).toContain('paymentMethods');
+  });
+
+  it('el barrel exporta los tipos nuevos', () => {
+    expect(RetailWizard.SalePayment).toBe(SalePayment);
+    expect(SINGLE_USE_PAYMENT_METHODS).toEqual([CASH, WIRE]);
+  });
+});

package/bin/retailIntegration/models/RetailSystemSale.d.ts

@@ -22,7 +22,7 @@ export declare class RetailSystemSaleCredit {
     totalToPay: string;
     firstPaymentDate: string;
 }
-/** Un medio de pago de `amountPaid`; las seis llaves van siempre, en `null` las que no aplican. */
+/** Un medio de pago de `amountPaid`; las seis llaves van siempre. El comprobante es opcional (`null`) en su medio y `null` en los demás. */
 export declare class RetailSystemSalePayment {
     method: RetailPaymentMethod;
     amount: string;

package/bin/retailIntegration/models/RetailSystemSale.js

@@ -79,7 +79,7 @@ __decorate([
     (0, class_validator_1.Validate)(IsCalendarDate_1.IsCalendarDate),
     __metadata("design:type", String)
 ], RetailSystemSaleCredit.prototype, "firstPaymentDate", void 0);
-/** Un medio de pago de `amountPaid`; las seis llaves van siempre, en `null` las que no aplican. */
+/** Un medio de pago de `amountPaid`; las seis llaves van siempre. El comprobante es opcional (`null`) en su medio y `null` en los demás. */
 class RetailSystemSalePayment {
 }
 exports.RetailSystemSalePayment = RetailSystemSalePayment;
@@ -93,15 +93,15 @@ __decorate([
     __metadata("design:type", String)
 ], RetailSystemSalePayment.prototype, "amount", void 0);
 __decorate([
-    (0, class_validator_1.Validate)(saleValidators_1.MatchesForPaymentMethod, [CARD, retailIntegrationLimits_1.RETAIL_CARD_LAST4_PATTERN]),
+    (0, class_validator_1.Validate)(saleValidators_1.MatchesForPaymentMethod, [CARD, retailIntegrationLimits_1.RETAIL_CARD_LAST4_PATTERN, true]),
     __metadata("design:type", String)
 ], RetailSystemSalePayment.prototype, "cardLast4", void 0);
 __decorate([
-    (0, class_validator_1.Validate)(saleValidators_1.MatchesForPaymentMethod, [CARD, retailIntegrationLimits_1.RETAIL_SALE_ID_TEXT_PATTERN]),
+    (0, class_validator_1.Validate)(saleValidators_1.MatchesForPaymentMethod, [CARD, retailIntegrationLimits_1.RETAIL_SALE_ID_TEXT_PATTERN, true]),
     __metadata("design:type", String)
 ], RetailSystemSalePayment.prototype, "authCode", void 0);
 __decorate([
-    (0, class_validator_1.Validate)(saleValidators_1.MatchesForPaymentMethod, [WIRE, retailIntegrationLimits_1.RETAIL_SPEI_TRACKING_KEY_PATTERN]),
+    (0, class_validator_1.Validate)(saleValidators_1.MatchesForPaymentMethod, [WIRE, retailIntegrationLimits_1.RETAIL_SPEI_TRACKING_KEY_PATTERN, true]),
     __metadata("design:type", String)
 ], RetailSystemSalePayment.prototype, "speiTrackingKey", void 0);
 __decorate([

package/bin/retailIntegration/validators/saleValidators.d.ts

@@ -1,5 +1,5 @@
 import { ValidationArguments, ValidatorConstraintInterface } from 'class-validator';
-/** Campo de un pago que solo aplica a un medio: con ese medio cumple el patrón; con los demás es `null`. */
+/** Campo de un pago que solo aplica a un medio: con ese medio cumple el patrón (o es `null` si es nulable); con los demás es `null`. */
 export declare class MatchesForPaymentMethod implements ValidatorConstraintInterface {
     validate(value: unknown, args: ValidationArguments): boolean;
     defaultMessage(args: ValidationArguments): string;

package/bin/retailIntegration/validators/saleValidators.js

@@ -13,7 +13,7 @@ const enums_1 = require("../enums");
 function decimalToCents(value) {
     return Number(value.replace('.', ''));
 }
-/** Campo de un pago que solo aplica a un medio: con ese medio cumple el patrón; con los demás es `null`. */
+/** Campo de un pago que solo aplica a un medio: con ese medio cumple el patrón (o es `null` si es nulable); con los demás es `null`. */
 let MatchesForPaymentMethod = class MatchesForPaymentMethod {
     validate(value, args) {
         const [method, pattern, nullable] = args.constraints;
@@ -24,7 +24,8 @@ let MatchesForPaymentMethod = class MatchesForPaymentMethod {
         return typeof value === 'string' && pattern.test(value);
     }
     defaultMessage(args) {
-        return `${args.property} es obligatorio y válido en ${args.constraints[0]} y null en los demás medios`;
+        const nullable = args.constraints[2] === true;
+        return `${args.property} debe ser ${nullable ? 'null o válido' : 'válido'} en ${args.constraints[0]} y null en los demás medios`;
     }
 };
 exports.MatchesForPaymentMethod = MatchesForPaymentMethod;

package/bin/retailWizard/constants/retailWizardValidation.d.ts

@@ -1,2 +1,7 @@
+import { SalePaymentMethodEnum } from '../enums/SalePaymentMethodEnum';
 /** Nombre de lambda en kebab-case, p. ej. `reconciliation-engine-business`. */
 export declare const RETAIL_WIZARD_CALLER_SERVICE_PATTERN: RegExp;
+/** Tope de pagos con los que se cobra una venta, un enganche o una venta de mostrador. */
+export declare const MAX_SALE_PAYMENTS = 3;
+/** Medios que aparecen a lo más una vez por cobro; la tarjeta se puede repetir. */
+export declare const SINGLE_USE_PAYMENT_METHODS: readonly SalePaymentMethodEnum[];

package/bin/retailWizard/constants/retailWizardValidation.js

@@ -1,5 +1,10 @@
 "use strict";
 Object.defineProperty(exports, "__esModule", { value: true });
-exports.RETAIL_WIZARD_CALLER_SERVICE_PATTERN = void 0;
+exports.SINGLE_USE_PAYMENT_METHODS = exports.MAX_SALE_PAYMENTS = exports.RETAIL_WIZARD_CALLER_SERVICE_PATTERN = void 0;
+const SalePaymentMethodEnum_1 = require("../enums/SalePaymentMethodEnum");
 /** Nombre de lambda en kebab-case, p. ej. `reconciliation-engine-business`. */
 exports.RETAIL_WIZARD_CALLER_SERVICE_PATTERN = /^[a-z0-9-]{1,64}$/;
+/** Tope de pagos con los que se cobra una venta, un enganche o una venta de mostrador. */
+exports.MAX_SALE_PAYMENTS = 3;
+/** Medios que aparecen a lo más una vez por cobro; la tarjeta se puede repetir. */
+exports.SINGLE_USE_PAYMENT_METHODS = [SalePaymentMethodEnum_1.SalePaymentMethodEnum.CASH, SalePaymentMethodEnum_1.SalePaymentMethodEnum.WIRE];

package/bin/retailWizard/dtos/Sale.d.ts

@@ -7,6 +7,7 @@ import type { CentralSyncStatusEnum } from '../enums/CentralSyncStatusEnum';
 import type { CentralCancelStatusEnum } from '../enums/CentralCancelStatusEnum';
 import type { CentralLiveCheckEnum } from '../enums/CentralLiveCheckEnum';
 import type { SalePaymentDetail } from './SalePaymentDetail';
+import type { SalePayment } from './SalePayment';
 import type { SaleLine } from './SaleLine';
 import type { SalePromotionRef } from '../../retailPromotions/dtos/SalePromotionRef';
 import type { SaleCancellation } from './SaleCancellation';
@@ -56,10 +57,14 @@ export interface Sale {
     downPaymentCents: number | null;
     /** Puntero al crédito SOFOM en loan-credit (solo ventas CREDIT; `null` en contado/externa). */
     creditId: string | null;
+    /** @deprecated Usa `payments`; con varios pagos lleva el método del primero. */
     paymentMethod: SalePaymentMethodEnum | null;
     /** `LG-T{storeCode}-VTA-{5hex}-{YYYY}W{ww}` (D11) — único vía `UNIQ#FOLIO`. */
     folio: string;
+    /** @deprecated Usa el comprobante de cada elemento de `payments`. */
     paymentDetail: SalePaymentDetail | null;
+    /** Pagos con que se cobró `amountCents` (1 a 3); `null` sin cobro, ausente en ventas anteriores al campo. */
+    payments?: SalePayment[] | null;
     soldAt: string;
     /** Puntero a la entrega de la tarjeta física en `retail-cards-business`. */
     cardDeliveryId: string | null;

package/bin/retailWizard/dtos/SalePayment.d.ts

@@ -0,0 +1,11 @@
+import { SalePaymentMethodEnum } from '../enums/SalePaymentMethodEnum';
+/** Un pago del cobro. El comprobante es opcional: si viene se valida y solo en su medio; si no, `null` o ausente. */
+export declare class SalePayment {
+    method: SalePaymentMethodEnum;
+    amountCents: number;
+    cashConfirmedInRegister?: boolean | null;
+    cardLast4?: string | null;
+    authCode?: string | null;
+    speiTrackingKey?: string | null;
+    senderClabe?: string | null;
+}

package/bin/retailWizard/dtos/SalePayment.js

@@ -0,0 +1,69 @@
+"use strict";
+var __decorate = (this && this.__decorate) || function (decorators, target, key, desc) {
+    var c = arguments.length, r = c < 3 ? target : desc === null ? desc = Object.getOwnPropertyDescriptor(target, key) : desc, d;
+    if (typeof Reflect === "object" && typeof Reflect.decorate === "function") r = Reflect.decorate(decorators, target, key, desc);
+    else for (var i = decorators.length - 1; i >= 0; i--) if (d = decorators[i]) r = (c < 3 ? d(r) : c > 3 ? d(target, key, r) : d(target, key)) || r;
+    return c > 3 && r && Object.defineProperty(target, key, r), r;
+};
+var __metadata = (this && this.__metadata) || function (k, v) {
+    if (typeof Reflect === "object" && typeof Reflect.metadata === "function") return Reflect.metadata(k, v);
+};
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.SalePayment = void 0;
+const class_transformer_1 = require("class-transformer");
+const class_validator_1 = require("class-validator");
+const retailIntegrationLimits_1 = require("../../retailIntegration/constants/retailIntegrationLimits");
+const SalePaymentMethodEnum_1 = require("../enums/SalePaymentMethodEnum");
+const OnlyForPaymentMethodConstraint_1 = require("../validators/OnlyForPaymentMethodConstraint");
+const { CASH, CARD, WIRE } = SalePaymentMethodEnum_1.SalePaymentMethodEnum;
+const hasValue = (field) => (o) => o[field] != null;
+/** Un pago del cobro. El comprobante es opcional: si viene se valida y solo en su medio; si no, `null` o ausente. */
+class SalePayment {
+}
+exports.SalePayment = SalePayment;
+__decorate([
+    (0, class_transformer_1.Expose)(),
+    (0, class_validator_1.IsEnum)(SalePaymentMethodEnum_1.SalePaymentMethodEnum),
+    __metadata("design:type", String)
+], SalePayment.prototype, "method", void 0);
+__decorate([
+    (0, class_transformer_1.Expose)(),
+    (0, class_validator_1.IsInt)(),
+    (0, class_validator_1.Min)(1),
+    __metadata("design:type", Number)
+], SalePayment.prototype, "amountCents", void 0);
+__decorate([
+    (0, class_transformer_1.Expose)(),
+    (0, class_validator_1.ValidateIf)(hasValue('cashConfirmedInRegister')),
+    (0, class_validator_1.IsBoolean)(),
+    (0, class_validator_1.Validate)(OnlyForPaymentMethodConstraint_1.OnlyForPaymentMethodConstraint, [CASH]),
+    __metadata("design:type", Boolean)
+], SalePayment.prototype, "cashConfirmedInRegister", void 0);
+__decorate([
+    (0, class_transformer_1.Expose)(),
+    (0, class_validator_1.ValidateIf)(hasValue('cardLast4')),
+    (0, class_validator_1.Matches)(retailIntegrationLimits_1.RETAIL_CARD_LAST4_PATTERN),
+    (0, class_validator_1.Validate)(OnlyForPaymentMethodConstraint_1.OnlyForPaymentMethodConstraint, [CARD]),
+    __metadata("design:type", String)
+], SalePayment.prototype, "cardLast4", void 0);
+__decorate([
+    (0, class_transformer_1.Expose)(),
+    (0, class_validator_1.ValidateIf)(hasValue('authCode')),
+    (0, class_validator_1.Matches)(retailIntegrationLimits_1.RETAIL_SALE_ID_TEXT_PATTERN),
+    (0, class_validator_1.Validate)(OnlyForPaymentMethodConstraint_1.OnlyForPaymentMethodConstraint, [CARD]),
+    __metadata("design:type", String)
+], SalePayment.prototype, "authCode", void 0);
+__decorate([
+    (0, class_transformer_1.Expose)(),
+    (0, class_validator_1.ValidateIf)(hasValue('speiTrackingKey')),
+    (0, class_validator_1.Matches)(retailIntegrationLimits_1.RETAIL_SPEI_TRACKING_KEY_PATTERN),
+    (0, class_validator_1.Validate)(OnlyForPaymentMethodConstraint_1.OnlyForPaymentMethodConstraint, [WIRE]),
+    __metadata("design:type", String)
+], SalePayment.prototype, "speiTrackingKey", void 0);
+__decorate([
+    (0, class_transformer_1.Expose)(),
+    (0, class_validator_1.ValidateIf)(hasValue('senderClabe')),
+    (0, class_validator_1.Matches)(retailIntegrationLimits_1.RETAIL_CLABE_PATTERN),
+    (0, class_validator_1.Validate)(OnlyForPaymentMethodConstraint_1.OnlyForPaymentMethodConstraint, [WIRE]),
+    __metadata("design:type", String)
+], SalePayment.prototype, "senderClabe", void 0);

package/bin/retailWizard/dtos/SalePaymentDetail.d.ts

@@ -2,6 +2,7 @@
  * Detalle del pago según el medio (`Sale.paymentDetail`): efectivo `{cashConfirmedInRegister}` ·
  * tarjeta `{cardLast4, authCode}` · SPEI `{speiTrackingKey, senderClabe?}`. SureKeep Fase 2 — pista Retail.
  */
+/** @deprecated Usa `SalePayment`, un elemento por pago. */
 export declare class SalePaymentDetail {
     cashConfirmedInRegister?: boolean;
     cardLast4?: string;

package/bin/retailWizard/dtos/SalePaymentDetail.js

@@ -16,6 +16,7 @@ const class_validator_1 = require("class-validator");
  * Detalle del pago según el medio (`Sale.paymentDetail`): efectivo `{cashConfirmedInRegister}` ·
  * tarjeta `{cardLast4, authCode}` · SPEI `{speiTrackingKey, senderClabe?}`. SureKeep Fase 2 — pista Retail.
  */
+/** @deprecated Usa `SalePayment`, un elemento por pago. */
 class SalePaymentDetail {
 }
 exports.SalePaymentDetail = SalePaymentDetail;

package/bin/retailWizard/dtos/SellerPendingRefundItem.d.ts

@@ -1,5 +1,6 @@
 import { RefundStatusEnum } from '../enums/RefundStatusEnum';
 import { SalePaymentMethodEnum } from '../enums/SalePaymentMethodEnum';
+import type { SalePayment } from './SalePayment';
 /** Un reembolso de enganche de la tienda en el Portal Vendedor (GET /portal/pending-refunds). */
 export interface SellerPendingRefundItem {
     sessionId: string;
@@ -9,8 +10,12 @@ export interface SellerPendingRefundItem {
     creditId: string | null;
     folio: string | null;
     refundPendingCents: number;
-    /** `null` = el registro no guardó con qué se cobró el enganche; no se puede marcar entregado. */
+    /**
+     * @deprecated Usa `payments`. `null` = el registro no guardó con qué se cobró el enganche; no se puede marcar entregado.
+     */
     paymentMethod: SalePaymentMethodEnum | null;
+    /** Pagos con que se cobró el enganche; ausente en registros anteriores al campo. */
+    payments?: SalePayment[] | null;
     status: RefundStatusEnum;
     /** `true` si el vendedor puede marcarlo entregado: efectivo y pendiente. */
     deliverable: boolean;

package/bin/retailWizard/dtos/WizardPayment.d.ts

@@ -1,8 +1,13 @@
 import { SalePaymentMethodEnum } from '../enums/SalePaymentMethodEnum';
+import { SalePayment } from './SalePayment';
 /** Registro del pago de contado dentro de la sesión (`WizardSession.payment`). SureKeep Fase 2 — pista Retail. */
 export declare class WizardPayment {
+    /** @deprecated Usa `payments`; con varios pagos lleva el método del primero. */
     method: SalePaymentMethodEnum;
     amountCents: number;
+    /** @deprecated Usa `payments`; es el comprobante como texto JSON. */
     detail?: string;
+    /** Pagos del cobro (1 a 3); ausente en sesiones anteriores al campo. */
+    payments?: SalePayment[];
     paidAt: string;
 }

package/bin/retailWizard/dtos/WizardPayment.js

@@ -14,6 +14,7 @@ const class_transformer_1 = require("class-transformer");
 const class_validator_1 = require("class-validator");
 const regex_1 = require("../../helpers/constans/regex");
 const SalePaymentMethodEnum_1 = require("../enums/SalePaymentMethodEnum");
+const IsSalePaymentList_1 = require("../validators/IsSalePaymentList");
 /** Registro del pago de contado dentro de la sesión (`WizardSession.payment`). SureKeep Fase 2 — pista Retail. */
 class WizardPayment {
 }
@@ -35,6 +36,12 @@ __decorate([
     (0, class_validator_1.IsString)(),
     __metadata("design:type", String)
 ], WizardPayment.prototype, "detail", void 0);
+__decorate([
+    (0, class_transformer_1.Expose)(),
+    (0, class_validator_1.IsOptional)(),
+    (0, IsSalePaymentList_1.IsSalePaymentList)(),
+    __metadata("design:type", Array)
+], WizardPayment.prototype, "payments", void 0);
 __decorate([
     (0, class_transformer_1.Expose)(),
     (0, class_validator_1.IsString)(),

package/bin/retailWizard/dtos/requests/CreateAccessorySaleRequest.d.ts

@@ -1,13 +1,18 @@
 import { SalePaymentMethodEnum } from '../../enums/SalePaymentMethodEnum';
 import { SalePaymentDetail } from '../SalePaymentDetail';
 import { AccessorySaleLine } from '../AccessorySaleLine';
+import { SalePayment } from '../SalePayment';
 /**
  * POST /wizard/accessory-sales — cierra la venta de mostrador, sin cliente.
- * `amountCents` es lo cobrado en caja y debe igualar la suma del catálogo.
+ * `amountCents` es lo cobrado en caja: iguala la suma del catálogo y la de `payments`.
  */
 export declare class CreateAccessorySaleRequest {
     lines: AccessorySaleLine[];
-    paymentMethod: SalePaymentMethodEnum;
+    /** @deprecated Usa `payments`; obligatorio solo si `payments` no viene. */
+    paymentMethod?: SalePaymentMethodEnum;
     amountCents: number;
-    paymentDetail: SalePaymentDetail;
+    /** @deprecated Usa el comprobante de cada elemento de `payments`. */
+    paymentDetail?: SalePaymentDetail;
+    /** Pagos del cobro (1 a 3); si viene, manda sobre `paymentMethod` y `paymentDetail`. */
+    payments?: SalePayment[];
 }

package/bin/retailWizard/dtos/requests/CreateAccessorySaleRequest.js

@@ -15,9 +15,10 @@ const class_validator_1 = require("class-validator");
 const SalePaymentMethodEnum_1 = require("../../enums/SalePaymentMethodEnum");
 const SalePaymentDetail_1 = require("../SalePaymentDetail");
 const AccessorySaleLine_1 = require("../AccessorySaleLine");
+const IsSalePaymentList_1 = require("../../validators/IsSalePaymentList");
 /**
  * POST /wizard/accessory-sales — cierra la venta de mostrador, sin cliente.
- * `amountCents` es lo cobrado en caja y debe igualar la suma del catálogo.
+ * `amountCents` es lo cobrado en caja: iguala la suma del catálogo y la de `payments`.
  */
 class CreateAccessorySaleRequest {
 }
@@ -33,6 +34,7 @@ __decorate([
 ], CreateAccessorySaleRequest.prototype, "lines", void 0);
 __decorate([
     (0, class_transformer_1.Expose)(),
+    (0, class_validator_1.ValidateIf)((o) => o.payments == null || o.paymentMethod !== undefined),
     (0, class_validator_1.IsEnum)(SalePaymentMethodEnum_1.SalePaymentMethodEnum),
     __metadata("design:type", String)
 ], CreateAccessorySaleRequest.prototype, "paymentMethod", void 0);
@@ -44,8 +46,14 @@ __decorate([
 ], CreateAccessorySaleRequest.prototype, "amountCents", void 0);
 __decorate([
     (0, class_transformer_1.Expose)(),
-    (0, class_validator_1.IsDefined)(),
+    (0, class_validator_1.IsOptional)(),
     (0, class_validator_1.ValidateNested)(),
     (0, class_transformer_1.Type)(() => SalePaymentDetail_1.SalePaymentDetail),
     __metadata("design:type", SalePaymentDetail_1.SalePaymentDetail)
 ], CreateAccessorySaleRequest.prototype, "paymentDetail", void 0);
+__decorate([
+    (0, class_transformer_1.Expose)(),
+    (0, class_validator_1.IsOptional)(),
+    (0, IsSalePaymentList_1.IsSalePaymentList)(),
+    __metadata("design:type", Array)
+], CreateAccessorySaleRequest.prototype, "payments", void 0);

package/bin/retailWizard/dtos/requests/DownPaymentRequest.d.ts

@@ -1,16 +1,21 @@
 import { SalePaymentMethodEnum } from '../../enums/SalePaymentMethodEnum';
 import { SalePaymentDetail } from '../SalePaymentDetail';
+import { SalePayment } from '../SalePayment';
 /**
  * POST /wizard/sessions/:id/down-payment — cobro del ENGANCHE de la venta a crédito (paso 07,
  * pista SOFOM). Endpoint propio, separado del cobro de contado (`/payment`): acá la regla dura es
  * `amountCents == downPaymentCents` del crédito (`loan-credit GET /credits/{id}`), NO el precio
  * full. Idempotente por sesión. El folio `SK-…-ENG-…` lo genera el server (no viaja en el body).
  * Al confirmar, el wizard marca la condición 1 del checklist (`activate-check { downPayment }`).
- * SPEI: el vendedor captura el comprobante (`speiTrackingKey`+`senderClabe`) y avanza.
+ * El comprobante de tarjeta y SPEI es opcional; `amountCents` es la suma de `payments`.
  * SureKeep Fase 2 — pista SOFOM.
  */
 export declare class DownPaymentRequest {
-    method: SalePaymentMethodEnum;
+    /** @deprecated Usa `payments`; obligatorio solo si `payments` no viene. */
+    method?: SalePaymentMethodEnum;
     amountCents: number;
+    /** @deprecated Usa el comprobante de cada elemento de `payments`. */
     detail?: SalePaymentDetail;
+    /** Pagos del cobro (1 a 3); si viene, manda sobre `method` y `detail`. */
+    payments?: SalePayment[];
 }

package/bin/retailWizard/dtos/requests/DownPaymentRequest.js

@@ -14,13 +14,14 @@ const class_transformer_1 = require("class-transformer");
 const class_validator_1 = require("class-validator");
 const SalePaymentMethodEnum_1 = require("../../enums/SalePaymentMethodEnum");
 const SalePaymentDetail_1 = require("../SalePaymentDetail");
+const IsSalePaymentList_1 = require("../../validators/IsSalePaymentList");
 /**
  * POST /wizard/sessions/:id/down-payment — cobro del ENGANCHE de la venta a crédito (paso 07,
  * pista SOFOM). Endpoint propio, separado del cobro de contado (`/payment`): acá la regla dura es
  * `amountCents == downPaymentCents` del crédito (`loan-credit GET /credits/{id}`), NO el precio
  * full. Idempotente por sesión. El folio `SK-…-ENG-…` lo genera el server (no viaja en el body).
  * Al confirmar, el wizard marca la condición 1 del checklist (`activate-check { downPayment }`).
- * SPEI: el vendedor captura el comprobante (`speiTrackingKey`+`senderClabe`) y avanza.
+ * El comprobante de tarjeta y SPEI es opcional; `amountCents` es la suma de `payments`.
  * SureKeep Fase 2 — pista SOFOM.
  */
 class DownPaymentRequest {
@@ -28,6 +29,7 @@ class DownPaymentRequest {
 exports.DownPaymentRequest = DownPaymentRequest;
 __decorate([
     (0, class_transformer_1.Expose)(),
+    (0, class_validator_1.ValidateIf)((o) => o.payments == null || o.method !== undefined),
     (0, class_validator_1.IsEnum)(SalePaymentMethodEnum_1.SalePaymentMethodEnum),
     __metadata("design:type", String)
 ], DownPaymentRequest.prototype, "method", void 0);
@@ -44,3 +46,9 @@ __decorate([
     (0, class_validator_1.ValidateNested)(),
     __metadata("design:type", SalePaymentDetail_1.SalePaymentDetail)
 ], DownPaymentRequest.prototype, "detail", void 0);
+__decorate([
+    (0, class_transformer_1.Expose)(),
+    (0, class_validator_1.IsOptional)(),
+    (0, IsSalePaymentList_1.IsSalePaymentList)(),
+    __metadata("design:type", Array)
+], DownPaymentRequest.prototype, "payments", void 0);

package/bin/retailWizard/dtos/requests/RegisterPaymentRequest.d.ts

@@ -1,12 +1,17 @@
 import { SalePaymentMethodEnum } from '../../enums/SalePaymentMethodEnum';
 import { SalePaymentDetail } from '../SalePaymentDetail';
+import { SalePayment } from '../SalePayment';
 /**
  * POST /wizard/sessions/:id/payment — registra el cobro de contado (idempotente por sesión). Regla
  * dura: `amountCents == cashPrice` de la reserva. `POST /payment/folio` genera el folio server-side
  * (D11) ANTES del registro; el folio no viaja en el body (lo posee el server). SureKeep Fase 2 — pista Retail.
  */
 export declare class RegisterPaymentRequest {
-    method: SalePaymentMethodEnum;
+    /** @deprecated Usa `payments`; obligatorio solo si `payments` no viene. */
+    method?: SalePaymentMethodEnum;
     amountCents: number;
+    /** @deprecated Usa el comprobante de cada elemento de `payments`. */
     detail?: SalePaymentDetail;
+    /** Pagos del cobro (1 a 3); si viene, manda sobre `method` y `detail`. */
+    payments?: SalePayment[];
 }

package/bin/retailWizard/dtos/requests/RegisterPaymentRequest.js

@@ -14,6 +14,7 @@ const class_transformer_1 = require("class-transformer");
 const class_validator_1 = require("class-validator");
 const SalePaymentMethodEnum_1 = require("../../enums/SalePaymentMethodEnum");
 const SalePaymentDetail_1 = require("../SalePaymentDetail");
+const IsSalePaymentList_1 = require("../../validators/IsSalePaymentList");
 /**
  * POST /wizard/sessions/:id/payment — registra el cobro de contado (idempotente por sesión). Regla
  * dura: `amountCents == cashPrice` de la reserva. `POST /payment/folio` genera el folio server-side
@@ -24,6 +25,7 @@ class RegisterPaymentRequest {
 exports.RegisterPaymentRequest = RegisterPaymentRequest;
 __decorate([
     (0, class_transformer_1.Expose)(),
+    (0, class_validator_1.ValidateIf)((o) => o.payments == null || o.method !== undefined),
     (0, class_validator_1.IsEnum)(SalePaymentMethodEnum_1.SalePaymentMethodEnum),
     __metadata("design:type", String)
 ], RegisterPaymentRequest.prototype, "method", void 0);
@@ -40,3 +42,9 @@ __decorate([
     (0, class_validator_1.ValidateNested)(),
     __metadata("design:type", SalePaymentDetail_1.SalePaymentDetail)
 ], RegisterPaymentRequest.prototype, "detail", void 0);
+__decorate([
+    (0, class_transformer_1.Expose)(),
+    (0, class_validator_1.IsOptional)(),
+    (0, IsSalePaymentList_1.IsSalePaymentList)(),
+    __metadata("design:type", Array)
+], RegisterPaymentRequest.prototype, "payments", void 0);