@fiado/type-kit 3.631.0 → 3.632.0

package/bin/retailWizard/events/RetailPromotionInboundMessage.d.ts

@@ -50,8 +50,10 @@ export declare class RetailPromotionInboundMessage {
     lines: RetailPromotionInboundLine[];
     /** Forma de pago; ausente en mensajes viejos. */
     saleType?: SaleTypeEnum;
-    /** Medio de cobro, solo en contado. */
+    /** @deprecated Usa `paymentMethods`. Medio de cobro, solo en contado. */
     paymentMethod?: SalePaymentMethodEnum | null;
+    /** Medios con que se cobró, uno por pago; solo en contado. */
+    paymentMethods?: SalePaymentMethodEnum[] | null;
     /** Financiera externa, solo en `EXTERNAL_REFERRAL`. */
     externalProvider?: ExternalProviderEnum | null;
     /** Precio del equipo en centavos; en crédito no es el enganche. */

package/bin/retailWizard/events/RetailPromotionInboundMessage.js

@@ -199,6 +199,12 @@ __decorate([
     (0, class_validator_1.IsEnum)(SalePaymentMethodEnum_1.SalePaymentMethodEnum),
     __metadata("design:type", String)
 ], RetailPromotionInboundMessage.prototype, "paymentMethod", void 0);
+__decorate([
+    (0, class_validator_1.IsOptional)(),
+    (0, class_validator_1.IsArray)(),
+    (0, class_validator_1.IsEnum)(SalePaymentMethodEnum_1.SalePaymentMethodEnum, { each: true }),
+    __metadata("design:type", Array)
+], RetailPromotionInboundMessage.prototype, "paymentMethods", void 0);
 __decorate([
     (0, class_validator_1.IsOptional)(),
     (0, class_validator_1.IsEnum)(ExternalProviderEnum_1.ExternalProviderEnum),

package/bin/retailWizard/index.d.ts

@@ -40,6 +40,11 @@ export * from './dtos/WizardProduct';
 export * from './dtos/WizardWelcome';
 export * from './dtos/WizardCreditPromotionBonus';
 export * from './dtos/SalePaymentDetail';
+export * from './dtos/SalePayment';
+export * from './validators/IsSalePaymentList';
+export * from './validators/OnlyForPaymentMethodConstraint';
+export * from './validators/PaymentsHaveSingleUseMethodsConstraint';
+export * from './validators/PaymentsMatchAmountCentsConstraint';
 export * from './dtos/ProspectNewCustomer';
 export * from './dtos/WizardBeneficiary';
 export * from './dtos/WizardLoan';

package/bin/retailWizard/index.js

@@ -60,6 +60,11 @@ __exportStar(require("./dtos/WizardProduct"), exports);
 __exportStar(require("./dtos/WizardWelcome"), exports);
 __exportStar(require("./dtos/WizardCreditPromotionBonus"), exports);
 __exportStar(require("./dtos/SalePaymentDetail"), exports);
+__exportStar(require("./dtos/SalePayment"), exports);
+__exportStar(require("./validators/IsSalePaymentList"), exports);
+__exportStar(require("./validators/OnlyForPaymentMethodConstraint"), exports);
+__exportStar(require("./validators/PaymentsHaveSingleUseMethodsConstraint"), exports);
+__exportStar(require("./validators/PaymentsMatchAmountCentsConstraint"), exports);
 __exportStar(require("./dtos/ProspectNewCustomer"), exports);
 __exportStar(require("./dtos/WizardBeneficiary"), exports);
 __exportStar(require("./dtos/WizardLoan"), exports);

package/bin/retailWizard/validators/IsSalePaymentList.d.ts

@@ -0,0 +1,2 @@
+/** Reglas de `payments`: 1 a 3 pagos válidos, efectivo y SPEI una vez, y la suma igual a `amountCents`. */
+export declare function IsSalePaymentList(): PropertyDecorator;

package/bin/retailWizard/validators/IsSalePaymentList.js

@@ -0,0 +1,22 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.IsSalePaymentList = IsSalePaymentList;
+const class_transformer_1 = require("class-transformer");
+const class_validator_1 = require("class-validator");
+const retailWizardValidation_1 = require("../constants/retailWizardValidation");
+const SalePayment_1 = require("../dtos/SalePayment");
+const PaymentsHaveSingleUseMethodsConstraint_1 = require("./PaymentsHaveSingleUseMethodsConstraint");
+const PaymentsMatchAmountCentsConstraint_1 = require("./PaymentsMatchAmountCentsConstraint");
+/** Reglas de `payments`: 1 a 3 pagos válidos, efectivo y SPEI una vez, y la suma igual a `amountCents`. */
+function IsSalePaymentList() {
+    const decorators = [
+        (0, class_validator_1.IsArray)(),
+        (0, class_validator_1.ArrayMinSize)(1),
+        (0, class_validator_1.ArrayMaxSize)(retailWizardValidation_1.MAX_SALE_PAYMENTS),
+        (0, class_validator_1.ValidateNested)({ each: true }),
+        (0, class_transformer_1.Type)(() => SalePayment_1.SalePayment),
+        (0, class_validator_1.Validate)(PaymentsHaveSingleUseMethodsConstraint_1.PaymentsHaveSingleUseMethodsConstraint),
+        (0, class_validator_1.Validate)(PaymentsMatchAmountCentsConstraint_1.PaymentsMatchAmountCentsConstraint),
+    ];
+    return (target, propertyKey) => decorators.forEach((decorate) => decorate(target, propertyKey));
+}

package/bin/retailWizard/validators/OnlyForPaymentMethodConstraint.d.ts

@@ -0,0 +1,6 @@
+import { type ValidationArguments, type ValidatorConstraintInterface } from 'class-validator';
+/** Un campo de comprobante con valor solo se acepta en el medio de pago al que pertenece. */
+export declare class OnlyForPaymentMethodConstraint implements ValidatorConstraintInterface {
+    validate(value: unknown, args: ValidationArguments): boolean;
+    defaultMessage(args: ValidationArguments): string;
+}

package/bin/retailWizard/validators/OnlyForPaymentMethodConstraint.js

@@ -0,0 +1,25 @@
+"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;
+};
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.OnlyForPaymentMethodConstraint = void 0;
+const class_validator_1 = require("class-validator");
+/** Un campo de comprobante con valor solo se acepta en el medio de pago al que pertenece. */
+let OnlyForPaymentMethodConstraint = class OnlyForPaymentMethodConstraint {
+    validate(value, args) {
+        if (value == null)
+            return true;
+        return args.object.method === args.constraints[0];
+    }
+    defaultMessage(args) {
+        return `${args.property} solo aplica a pagos ${args.constraints[0]}`;
+    }
+};
+exports.OnlyForPaymentMethodConstraint = OnlyForPaymentMethodConstraint;
+exports.OnlyForPaymentMethodConstraint = OnlyForPaymentMethodConstraint = __decorate([
+    (0, class_validator_1.ValidatorConstraint)({ name: 'onlyForPaymentMethod', async: false })
+], OnlyForPaymentMethodConstraint);

package/bin/retailWizard/validators/PaymentsHaveSingleUseMethodsConstraint.d.ts

@@ -0,0 +1,6 @@
+import { type ValidationArguments, type ValidatorConstraintInterface } from 'class-validator';
+/** Efectivo y SPEI aparecen a lo más una vez en `payments`; la tarjeta se puede repetir. */
+export declare class PaymentsHaveSingleUseMethodsConstraint implements ValidatorConstraintInterface {
+    validate(value: unknown, _args: ValidationArguments): boolean;
+    defaultMessage(): string;
+}

package/bin/retailWizard/validators/PaymentsHaveSingleUseMethodsConstraint.js

@@ -0,0 +1,27 @@
+"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;
+};
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.PaymentsHaveSingleUseMethodsConstraint = void 0;
+const class_validator_1 = require("class-validator");
+const retailWizardValidation_1 = require("../constants/retailWizardValidation");
+/** Efectivo y SPEI aparecen a lo más una vez en `payments`; la tarjeta se puede repetir. */
+let PaymentsHaveSingleUseMethodsConstraint = class PaymentsHaveSingleUseMethodsConstraint {
+    validate(value, _args) {
+        if (!Array.isArray(value))
+            return true;
+        const methods = value.map((p) => p?.method);
+        return retailWizardValidation_1.SINGLE_USE_PAYMENT_METHODS.every((m) => methods.filter((x) => x === m).length <= 1);
+    }
+    defaultMessage() {
+        return `payments admite a lo más un pago de cada medio ${retailWizardValidation_1.SINGLE_USE_PAYMENT_METHODS.join(' y ')}`;
+    }
+};
+exports.PaymentsHaveSingleUseMethodsConstraint = PaymentsHaveSingleUseMethodsConstraint;
+exports.PaymentsHaveSingleUseMethodsConstraint = PaymentsHaveSingleUseMethodsConstraint = __decorate([
+    (0, class_validator_1.ValidatorConstraint)({ name: 'paymentsHaveSingleUseMethods', async: false })
+], PaymentsHaveSingleUseMethodsConstraint);

package/bin/retailWizard/validators/PaymentsMatchAmountCentsConstraint.d.ts

@@ -0,0 +1,6 @@
+import { type ValidationArguments, type ValidatorConstraintInterface } from 'class-validator';
+/** La suma de `payments[].amountCents` es el `amountCents` del cobro. */
+export declare class PaymentsMatchAmountCentsConstraint implements ValidatorConstraintInterface {
+    validate(value: unknown, args: ValidationArguments): boolean;
+    defaultMessage(): string;
+}

package/bin/retailWizard/validators/PaymentsMatchAmountCentsConstraint.js

@@ -0,0 +1,29 @@
+"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;
+};
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.PaymentsMatchAmountCentsConstraint = void 0;
+const class_validator_1 = require("class-validator");
+/** La suma de `payments[].amountCents` es el `amountCents` del cobro. */
+let PaymentsMatchAmountCentsConstraint = class PaymentsMatchAmountCentsConstraint {
+    validate(value, args) {
+        const total = args.object.amountCents;
+        if (!Array.isArray(value) || !Number.isInteger(total))
+            return true;
+        const amounts = value.map((p) => p?.amountCents);
+        if (!amounts.every((a) => Number.isInteger(a)))
+            return true;
+        return amounts.reduce((sum, a) => sum + a, 0) === total;
+    }
+    defaultMessage() {
+        return 'la suma de payments[].amountCents debe ser amountCents';
+    }
+};
+exports.PaymentsMatchAmountCentsConstraint = PaymentsMatchAmountCentsConstraint;
+exports.PaymentsMatchAmountCentsConstraint = PaymentsMatchAmountCentsConstraint = __decorate([
+    (0, class_validator_1.ValidatorConstraint)({ name: 'paymentsMatchAmountCents', async: false })
+], PaymentsMatchAmountCentsConstraint);

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@fiado/type-kit",
-  "version": "3.631.0",
+  "version": "3.632.0",
   "description": "",
   "main": "bin/index.js",
   "types": "bin/index.d.ts",

package/src/retailIntegration/models/RetailSystemSale.ts

@@ -53,13 +53,13 @@ export class RetailSystemSaleCredit {
     @Validate(IsCalendarDate) 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 class RetailSystemSalePayment {
     @IsIn(Object.values(RetailPaymentMethodEnum)) method!: RetailPaymentMethod;
     @IsString() @Matches(RETAIL_SALE_POSITIVE_DECIMAL_PATTERN) amount!: string;
-    @Validate(MatchesForPaymentMethod, [CARD, RETAIL_CARD_LAST4_PATTERN]) cardLast4!: string | null;
-    @Validate(MatchesForPaymentMethod, [CARD, RETAIL_SALE_ID_TEXT_PATTERN]) authCode!: string | null;
-    @Validate(MatchesForPaymentMethod, [WIRE, RETAIL_SPEI_TRACKING_KEY_PATTERN]) speiTrackingKey!: string | null;
+    @Validate(MatchesForPaymentMethod, [CARD, RETAIL_CARD_LAST4_PATTERN, true]) cardLast4!: string | null;
+    @Validate(MatchesForPaymentMethod, [CARD, RETAIL_SALE_ID_TEXT_PATTERN, true]) authCode!: string | null;
+    @Validate(MatchesForPaymentMethod, [WIRE, RETAIL_SPEI_TRACKING_KEY_PATTERN, true]) speiTrackingKey!: string | null;
     @Validate(MatchesForPaymentMethod, [WIRE, RETAIL_CLABE_PATTERN, true]) senderClabe!: string | null;
 }
 

package/src/retailIntegration/validators/saleValidators.ts

@@ -6,7 +6,7 @@ function decimalToCents(value: string): number {
     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`. */
 @ValidatorConstraint({ name: 'matchesForPaymentMethod', async: false })
 export class MatchesForPaymentMethod implements ValidatorConstraintInterface {
     validate(value: unknown, args: ValidationArguments): boolean {
@@ -17,7 +17,8 @@ export class MatchesForPaymentMethod implements ValidatorConstraintInterface {
     }
 
     defaultMessage(args: ValidationArguments): string {
-        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`;
     }
 }
 

package/src/retailWizard/constants/retailWizardValidation.ts

@@ -1,2 +1,10 @@
+import { SalePaymentMethodEnum } from '../enums/SalePaymentMethodEnum';
+
 /** Nombre de lambda en kebab-case, p. ej. `reconciliation-engine-business`. */
 export const 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. */
+export const MAX_SALE_PAYMENTS = 3;
+
+/** Medios que aparecen a lo más una vez por cobro; la tarjeta se puede repetir. */
+export const SINGLE_USE_PAYMENT_METHODS: readonly SalePaymentMethodEnum[] = [SalePaymentMethodEnum.CASH, SalePaymentMethodEnum.WIRE];

package/src/retailWizard/dtos/Sale.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';
@@ -57,10 +58,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/src/retailWizard/dtos/SalePayment.ts

@@ -0,0 +1,55 @@
+import { Expose } from 'class-transformer';
+import { IsBoolean, IsEnum, IsInt, Matches, Min, Validate, ValidateIf } from 'class-validator';
+import {
+    RETAIL_CARD_LAST4_PATTERN,
+    RETAIL_CLABE_PATTERN,
+    RETAIL_SALE_ID_TEXT_PATTERN,
+    RETAIL_SPEI_TRACKING_KEY_PATTERN,
+} from '../../retailIntegration/constants/retailIntegrationLimits';
+import { SalePaymentMethodEnum } from '../enums/SalePaymentMethodEnum';
+import { OnlyForPaymentMethodConstraint } from '../validators/OnlyForPaymentMethodConstraint';
+
+const { CASH, CARD, WIRE } = SalePaymentMethodEnum;
+const hasValue = (field: keyof SalePayment) => (o: SalePayment) => 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. */
+export class SalePayment {
+    @Expose()
+    @IsEnum(SalePaymentMethodEnum)
+    method!: SalePaymentMethodEnum;
+
+    @Expose()
+    @IsInt()
+    @Min(1)
+    amountCents!: number;
+
+    @Expose()
+    @ValidateIf(hasValue('cashConfirmedInRegister'))
+    @IsBoolean()
+    @Validate(OnlyForPaymentMethodConstraint, [CASH])
+    cashConfirmedInRegister?: boolean | null;
+
+    @Expose()
+    @ValidateIf(hasValue('cardLast4'))
+    @Matches(RETAIL_CARD_LAST4_PATTERN)
+    @Validate(OnlyForPaymentMethodConstraint, [CARD])
+    cardLast4?: string | null;
+
+    @Expose()
+    @ValidateIf(hasValue('authCode'))
+    @Matches(RETAIL_SALE_ID_TEXT_PATTERN)
+    @Validate(OnlyForPaymentMethodConstraint, [CARD])
+    authCode?: string | null;
+
+    @Expose()
+    @ValidateIf(hasValue('speiTrackingKey'))
+    @Matches(RETAIL_SPEI_TRACKING_KEY_PATTERN)
+    @Validate(OnlyForPaymentMethodConstraint, [WIRE])
+    speiTrackingKey?: string | null;
+
+    @Expose()
+    @ValidateIf(hasValue('senderClabe'))
+    @Matches(RETAIL_CLABE_PATTERN)
+    @Validate(OnlyForPaymentMethodConstraint, [WIRE])
+    senderClabe?: string | null;
+}

package/src/retailWizard/dtos/SalePaymentDetail.ts

@@ -5,6 +5,7 @@ import { IsBoolean, IsOptional, IsString } from '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. */
 export class SalePaymentDetail {
     @Expose()
     @IsOptional()

package/src/retailWizard/dtos/SellerPendingRefundItem.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 {
@@ -10,8 +11,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/src/retailWizard/dtos/WizardPayment.ts

@@ -2,9 +2,12 @@ import { Expose } from 'class-transformer';
 import { IsEnum, IsInt, IsOptional, IsString, Matches, Min } from 'class-validator';
 import { regexIso8601 } from '../../helpers/constans/regex';
 import { SalePaymentMethodEnum } from '../enums/SalePaymentMethodEnum';
+import { IsSalePaymentList } from '../validators/IsSalePaymentList';
+import { SalePayment } from './SalePayment';
 
 /** Registro del pago de contado dentro de la sesión (`WizardSession.payment`). SureKeep Fase 2 — pista Retail. */
 export class WizardPayment {
+    /** @deprecated Usa `payments`; con varios pagos lleva el método del primero. */
     @Expose()
     @IsEnum(SalePaymentMethodEnum)
     method!: SalePaymentMethodEnum;
@@ -14,11 +17,18 @@ export class WizardPayment {
     @Min(0)
     amountCents!: number;
 
+    /** @deprecated Usa `payments`; es el comprobante como texto JSON. */
     @Expose()
     @IsOptional()
     @IsString()
     detail?: string;
 
+    /** Pagos del cobro (1 a 3); ausente en sesiones anteriores al campo. */
+    @Expose()
+    @IsOptional()
+    @IsSalePaymentList()
+    payments?: SalePayment[];
+
     @Expose()
     @IsString()
     @Matches(regexIso8601, { message: 'paidAt debe ser una fecha ISO 8601' })

package/src/retailWizard/dtos/requests/CreateAccessorySaleRequest.ts

@@ -3,19 +3,22 @@ import {
   ArrayMaxSize,
   ArrayMinSize,
   IsArray,
-  IsDefined,
   IsEnum,
   IsInt,
+  IsOptional,
   Min,
+  ValidateIf,
   ValidateNested,
 } from 'class-validator';
 import { SalePaymentMethodEnum } from '../../enums/SalePaymentMethodEnum';
 import { SalePaymentDetail } from '../SalePaymentDetail';
 import { AccessorySaleLine } from '../AccessorySaleLine';
+import { SalePayment } from '../SalePayment';
+import { IsSalePaymentList } from '../../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`.
  */
 export class CreateAccessorySaleRequest {
   @Expose()
@@ -26,18 +29,27 @@ export class CreateAccessorySaleRequest {
   @Type(() => AccessorySaleLine)
   lines!: AccessorySaleLine[];
 
+  /** @deprecated Usa `payments`; obligatorio solo si `payments` no viene. */
   @Expose()
+  @ValidateIf((o: { payments?: unknown; paymentMethod?: unknown }) => o.payments == null || o.paymentMethod !== undefined)
   @IsEnum(SalePaymentMethodEnum)
-  paymentMethod!: SalePaymentMethodEnum;
+  paymentMethod?: SalePaymentMethodEnum;
 
   @Expose()
   @IsInt()
   @Min(0)
   amountCents!: number;
 
+  /** @deprecated Usa el comprobante de cada elemento de `payments`. */
   @Expose()
-  @IsDefined()
+  @IsOptional()
   @ValidateNested()
   @Type(() => SalePaymentDetail)
-  paymentDetail!: SalePaymentDetail;
+  paymentDetail?: SalePaymentDetail;
+
+  /** Pagos del cobro (1 a 3); si viene, manda sobre `paymentMethod` y `paymentDetail`. */
+  @Expose()
+  @IsOptional()
+  @IsSalePaymentList()
+  payments?: SalePayment[];
 }

package/src/retailWizard/dtos/requests/DownPaymentRequest.ts

@@ -1,7 +1,9 @@
 import { Expose, Type } from 'class-transformer';
-import { IsEnum, IsInt, IsOptional, Min, ValidateNested } from 'class-validator';
+import { IsEnum, IsInt, IsOptional, Min, ValidateIf, ValidateNested } from 'class-validator';
 import { SalePaymentMethodEnum } from '../../enums/SalePaymentMethodEnum';
 import { SalePaymentDetail } from '../SalePaymentDetail';
+import { SalePayment } from '../SalePayment';
+import { IsSalePaymentList } from '../../validators/IsSalePaymentList';
 
 /**
  * POST /wizard/sessions/:id/down-payment — cobro del ENGANCHE de la venta a crédito (paso 07,
@@ -9,22 +11,31 @@ import { SalePaymentDetail } from '../SalePaymentDetail';
  * `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 class DownPaymentRequest {
+    /** @deprecated Usa `payments`; obligatorio solo si `payments` no viene. */
     @Expose()
+    @ValidateIf((o: { payments?: unknown; method?: unknown }) => o.payments == null || o.method !== undefined)
     @IsEnum(SalePaymentMethodEnum)
-    method!: SalePaymentMethodEnum;
+    method?: SalePaymentMethodEnum;
 
     @Expose()
     @IsInt()
     @Min(0)
     amountCents!: number;
 
+    /** @deprecated Usa el comprobante de cada elemento de `payments`. */
     @Expose()
     @IsOptional()
     @Type(() => SalePaymentDetail)
     @ValidateNested()
     detail?: SalePaymentDetail;
+
+    /** Pagos del cobro (1 a 3); si viene, manda sobre `method` y `detail`. */
+    @Expose()
+    @IsOptional()
+    @IsSalePaymentList()
+    payments?: SalePayment[];
 }

package/src/retailWizard/dtos/requests/RegisterPaymentRequest.ts

@@ -1,7 +1,9 @@
 import { Expose, Type } from 'class-transformer';
-import { IsEnum, IsInt, IsOptional, ValidateNested, Min } from 'class-validator';
+import { IsEnum, IsInt, IsOptional, ValidateIf, ValidateNested, Min } from 'class-validator';
 import { SalePaymentMethodEnum } from '../../enums/SalePaymentMethodEnum';
 import { SalePaymentDetail } from '../SalePaymentDetail';
+import { SalePayment } from '../SalePayment';
+import { IsSalePaymentList } from '../../validators/IsSalePaymentList';
 
 /**
  * POST /wizard/sessions/:id/payment — registra el cobro de contado (idempotente por sesión). Regla
@@ -9,18 +11,27 @@ import { SalePaymentDetail } from '../SalePaymentDetail';
  * (D11) ANTES del registro; el folio no viaja en el body (lo posee el server). SureKeep Fase 2 — pista Retail.
  */
 export class RegisterPaymentRequest {
+  /** @deprecated Usa `payments`; obligatorio solo si `payments` no viene. */
   @Expose()
+  @ValidateIf((o: { payments?: unknown; method?: unknown }) => o.payments == null || o.method !== undefined)
   @IsEnum(SalePaymentMethodEnum)
-  method!: SalePaymentMethodEnum;
+  method?: SalePaymentMethodEnum;
 
   @Expose()
   @IsInt()
   @Min(0)
   amountCents!: number;
 
+  /** @deprecated Usa el comprobante de cada elemento de `payments`. */
   @Expose()
   @IsOptional()
   @Type(() => SalePaymentDetail)
   @ValidateNested()
   detail?: SalePaymentDetail;
+
+  /** Pagos del cobro (1 a 3); si viene, manda sobre `method` y `detail`. */
+  @Expose()
+  @IsOptional()
+  @IsSalePaymentList()
+  payments?: SalePayment[];
 }

package/src/retailWizard/events/RetailPromotionInboundMessage.ts

@@ -174,11 +174,17 @@ export class RetailPromotionInboundMessage {
     @IsEnum(SaleTypeEnum)
     saleType?: SaleTypeEnum;
 
-    /** Medio de cobro, solo en contado. */
+    /** @deprecated Usa `paymentMethods`. Medio de cobro, solo en contado. */
     @IsOptional()
     @IsEnum(SalePaymentMethodEnum)
     paymentMethod?: SalePaymentMethodEnum | null;
 
+    /** Medios con que se cobró, uno por pago; solo en contado. */
+    @IsOptional()
+    @IsArray()
+    @IsEnum(SalePaymentMethodEnum, { each: true })
+    paymentMethods?: SalePaymentMethodEnum[] | null;
+
     /** Financiera externa, solo en `EXTERNAL_REFERRAL`. */
     @IsOptional()
     @IsEnum(ExternalProviderEnum)

package/src/retailWizard/index.ts

@@ -45,6 +45,11 @@ export * from './dtos/WizardProduct';
 export * from './dtos/WizardWelcome';
 export * from './dtos/WizardCreditPromotionBonus';
 export * from './dtos/SalePaymentDetail';
+export * from './dtos/SalePayment';
+export * from './validators/IsSalePaymentList';
+export * from './validators/OnlyForPaymentMethodConstraint';
+export * from './validators/PaymentsHaveSingleUseMethodsConstraint';
+export * from './validators/PaymentsMatchAmountCentsConstraint';
 export * from './dtos/ProspectNewCustomer';
 export * from './dtos/WizardBeneficiary';
 export * from './dtos/WizardLoan';

package/src/retailWizard/validators/IsSalePaymentList.ts

@@ -0,0 +1,20 @@
+import { Type } from 'class-transformer';
+import { ArrayMaxSize, ArrayMinSize, IsArray, Validate, ValidateNested } from 'class-validator';
+import { MAX_SALE_PAYMENTS } from '../constants/retailWizardValidation';
+import { SalePayment } from '../dtos/SalePayment';
+import { PaymentsHaveSingleUseMethodsConstraint } from './PaymentsHaveSingleUseMethodsConstraint';
+import { PaymentsMatchAmountCentsConstraint } from './PaymentsMatchAmountCentsConstraint';
+
+/** Reglas de `payments`: 1 a 3 pagos válidos, efectivo y SPEI una vez, y la suma igual a `amountCents`. */
+export function IsSalePaymentList(): PropertyDecorator {
+    const decorators: PropertyDecorator[] = [
+        IsArray(),
+        ArrayMinSize(1),
+        ArrayMaxSize(MAX_SALE_PAYMENTS),
+        ValidateNested({ each: true }),
+        Type(() => SalePayment),
+        Validate(PaymentsHaveSingleUseMethodsConstraint),
+        Validate(PaymentsMatchAmountCentsConstraint),
+    ];
+    return (target, propertyKey) => decorators.forEach((decorate) => decorate(target, propertyKey));
+}

package/src/retailWizard/validators/OnlyForPaymentMethodConstraint.ts

@@ -0,0 +1,18 @@
+import {
+    ValidatorConstraint,
+    type ValidationArguments,
+    type ValidatorConstraintInterface,
+} from 'class-validator';
+
+/** Un campo de comprobante con valor solo se acepta en el medio de pago al que pertenece. */
+@ValidatorConstraint({ name: 'onlyForPaymentMethod', async: false })
+export class OnlyForPaymentMethodConstraint implements ValidatorConstraintInterface {
+    validate(value: unknown, args: ValidationArguments): boolean {
+        if (value == null) return true;
+        return (args.object as { method?: unknown }).method === args.constraints[0];
+    }
+
+    defaultMessage(args: ValidationArguments): string {
+        return `${args.property} solo aplica a pagos ${args.constraints[0]}`;
+    }
+}

package/src/retailWizard/validators/PaymentsHaveSingleUseMethodsConstraint.ts

@@ -0,0 +1,20 @@
+import {
+    ValidatorConstraint,
+    type ValidationArguments,
+    type ValidatorConstraintInterface,
+} from 'class-validator';
+import { SINGLE_USE_PAYMENT_METHODS } from '../constants/retailWizardValidation';
+
+/** Efectivo y SPEI aparecen a lo más una vez en `payments`; la tarjeta se puede repetir. */
+@ValidatorConstraint({ name: 'paymentsHaveSingleUseMethods', async: false })
+export class PaymentsHaveSingleUseMethodsConstraint implements ValidatorConstraintInterface {
+    validate(value: unknown, _args: ValidationArguments): boolean {
+        if (!Array.isArray(value)) return true;
+        const methods = value.map((p) => (p as { method?: unknown } | null)?.method);
+        return SINGLE_USE_PAYMENT_METHODS.every((m) => methods.filter((x) => x === m).length <= 1);
+    }
+
+    defaultMessage(): string {
+        return `payments admite a lo más un pago de cada medio ${SINGLE_USE_PAYMENT_METHODS.join(' y ')}`;
+    }
+}