@fiado/type-kit 3.602.0 → 3.603.0

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

@@ -23,6 +23,12 @@ async function errorsOf(cls: new () => object, plain: object): Promise<string[]>
     return paths(await validate(plainToInstance(cls, plain)));
 }
 
+const cashPayment = { method: 'CASH', amount: '400.00', cardLast4: null, authCode: null, speiTrackingKey: null, senderClabe: null } as const;
+const cardPayment = { method: 'CARD', amount: '200.00', cardLast4: '4242', authCode: 'A1B2C3', speiTrackingKey: null, senderClabe: null } as const;
+const wirePayment = {
+    method: 'WIRE', amount: '200.00', cardLast4: null, authCode: null, speiTrackingKey: '123456789012345678', senderClabe: '012180001234567897',
+} as const;
+
 // Literal tipado: prueba en compilación que la clase sigue aceptando objetos planos.
 const sale: RetailSystemSale = {
     saleId: '7f0c2a52-1b7e-4f0e-9d7a-2a1d3c4b5e6f',
@@ -33,30 +39,39 @@ const sale: RetailSystemSale = {
     saleType: 'CREDIT',
     financier: 'SUREKEEP',
     creditId: 'CR-991',
+    credit: {
+        paymentFrequency: 'WEEKLY', installments: 16, installmentAmount: '260.67', downPayment: '600.00', totalToPay: '4170.72', firstPaymentDate: '2026-10-30',
+    },
     currencyId: 'MXN',
     customer: { customerId: 'C-1', names: 'Ana', paternalLastName: 'López', maternalLastName: null, phone: '7221234567' },
     equipmentPrice: '5999.00',
     amountPaid: '600.00',
-    paymentMethod: 'CASH',
+    payments: [cashPayment, cardPayment],
     lines: [
         {
             lineId: 'L1', sku: 'IPH-15', qty: 1, basePrice: '5999.00', discount: '0.00', paymentType: 'CREDIT',
-            financedAmount: '5399.00', role: null, components: [{ sku: 'IPH-15', qty: 1, identifiers: ['356789012345678'] }],
+            financedAmount: '5399.00', role: null, promotionId: null, components: [{ sku: 'IPH-15', qty: 1, identifiers: ['356789012345678'] }],
         },
         {
             lineId: 'L2', sku: 'FUNDA-1', qty: 1, basePrice: '0.00', discount: '0.00', paymentType: 'CASH',
-            financedAmount: '0.00', role: 'GIFT', components: [],
+            financedAmount: '0.00', role: 'GIFT', promotionId: 'PRM-0012', components: [],
         },
     ],
 };
 
+const cashSale = { ...sale, saleType: 'CASH', financier: 'NONE', creditId: null, credit: null };
+
 describe('RetailSystemSale (body de privateRegisterRetailSale)', () => {
-    it('acepta una venta completa', async () => {
+    it('acepta una venta a crédito SureKeep completa', async () => {
         expect(await errorsOf(RetailSystemSale, sale)).toEqual([]);
     });
 
-    it('acepta los nullables en null', async () => {
-        expect(await errorsOf(RetailSystemSale, { ...sale, creditId: null, paymentMethod: null })).toEqual([]);
+    it('acepta una venta de contado con creditId y credit en null', async () => {
+        expect(await errorsOf(RetailSystemSale, cashSale)).toEqual([]);
+    });
+
+    it('acepta una referida sin creditId ni credit', async () => {
+        expect(await errorsOf(RetailSystemSale, { ...sale, financier: 'PAYJOY', creditId: null, credit: null })).toEqual([]);
     });
 
     it.each([
@@ -67,14 +82,19 @@ describe('RetailSystemSale (body de privateRegisterRetailSale)', () => {
         ['financier', { financier: 'OTRO' }],
         ['currencyId', { currencyId: 'EUR' }],
         ['equipmentPrice', { equipmentPrice: '5999' }],
-        ['amountPaid', { amountPaid: '-1.00' }],
-        ['paymentMethod', { paymentMethod: 'BITCOIN' }],
+        ['equipmentPrice', { equipmentPrice: '1234567890123.00' }],
         ['creditId', { creditId: undefined }],
+        ['credit', { credit: undefined }],
+        ['payments', { payments: undefined }],
         ['lines', { lines: [] }],
     ])('rechaza %s inválido', async (field, patch) => {
         expect(await errorsOf(RetailSystemSale, { ...sale, ...patch })).toEqual([field]);
     });
 
+    it.each(['722123456', '72212345678', '+527221234567', '722-123-4567'])('rechaza customer.phone %s', async (phone) => {
+        expect(await errorsOf(RetailSystemSale, { ...sale, customer: { ...sale.customer, phone } })).toEqual(['customer.phone']);
+    });
+
     it('valida el cliente anidado', async () => {
         expect(await errorsOf(RetailSystemSale, { ...sale, customer: { ...sale.customer, names: '' } })).toEqual(['customer.names']);
     });
@@ -90,11 +110,130 @@ describe('RetailSystemSale (body de privateRegisterRetailSale)', () => {
     });
 });
 
+describe('RetailSystemSale.credit', () => {
+    it('SUREKEEP exige credit y creditId', async () => {
+        expect(await errorsOf(RetailSystemSale, { ...sale, credit: null })).toEqual(['financier']);
+        expect(await errorsOf(RetailSystemSale, { ...sale, creditId: null })).toEqual(['financier']);
+    });
+
+    it('contado exige credit y creditId en null', async () => {
+        expect(await errorsOf(RetailSystemSale, { ...cashSale, credit: sale.credit })).toEqual(['financier']);
+        expect(await errorsOf(RetailSystemSale, { ...cashSale, creditId: 'CR-1' })).toEqual(['financier']);
+    });
+
+    it.each([
+        ['paymentFrequency', { paymentFrequency: 'DAILY' }],
+        ['installments', { installments: 0 }],
+        ['installments', { installments: 1.5 }],
+        ['installmentAmount', { installmentAmount: '260.6' }],
+        ['downPayment', { downPayment: undefined }],
+        ['totalToPay', { totalToPay: '1234567890123.00' }],
+        ['firstPaymentDate', { firstPaymentDate: '2026-02-30' }],
+        ['firstPaymentDate', { firstPaymentDate: '2026-10-30T00:00:00Z' }],
+    ])('rechaza credit.%s inválido', async (field, patch) => {
+        expect(await errorsOf(RetailSystemSale, { ...sale, credit: { ...sale.credit, ...patch } })).toEqual([`credit.${field}`]);
+    });
+});
+
+describe('RetailSystemSale.payments', () => {
+    it('acepta [] cuando amountPaid es 0.00', async () => {
+        expect(await errorsOf(RetailSystemSale, { ...sale, amountPaid: '0.00', payments: [] })).toEqual([]);
+    });
+
+    it('acepta WIRE con y sin senderClabe', async () => {
+        expect(await errorsOf(RetailSystemSale, { ...sale, payments: [cashPayment, wirePayment] })).toEqual([]);
+        expect(await errorsOf(RetailSystemSale, { ...sale, payments: [cashPayment, { ...wirePayment, senderClabe: null }] })).toEqual([]);
+    });
+
+    it('acepta FIADO sin detalle', async () => {
+        expect(await errorsOf(RetailSystemSale, { ...sale, payments: [{ ...cashPayment, method: 'FIADO', amount: '600.00' }] })).toEqual([]);
+    });
+
+    it('rechaza que la suma no cuadre con amountPaid', async () => {
+        expect(await errorsOf(RetailSystemSale, { ...sale, payments: [cashPayment] })).toEqual(['payments']);
+        expect(await errorsOf(RetailSystemSale, { ...sale, payments: [] })).toEqual(['payments']);
+    });
+
+    it.each([
+        ['method', { method: 'SPEI' }],
+        ['amount', { amount: '0.00' }],
+        ['amount', { amount: '400' }],
+        ['cardLast4', { cardLast4: '4242' }],
+        ['cardLast4', { cardLast4: undefined }],
+        ['authCode', { authCode: 'X' }],
+        ['speiTrackingKey', { speiTrackingKey: undefined }],
+        ['senderClabe', { senderClabe: undefined }],
+    ])('rechaza %s fuera de regla en CASH', async (field, patch) => {
+        const payments = [{ ...cashPayment, ...patch }, cardPayment];
+        expect(await errorsOf(RetailSystemSale, { ...sale, payments })).toEqual([`payments.0.${field}`]);
+    });
+
+    it.each([
+        ['cardLast4', { cardLast4: null }],
+        ['cardLast4', { cardLast4: '424' }],
+        ['authCode', { authCode: null }],
+        ['authCode', { authCode: ' ' }],
+        ['authCode', { authCode: 'A'.repeat(65) }],
+        ['speiTrackingKey', { speiTrackingKey: '123456789012345678' }],
+    ])('rechaza %s fuera de regla en CARD', async (field, patch) => {
+        const payments = [cashPayment, { ...cardPayment, ...patch }];
+        expect(await errorsOf(RetailSystemSale, { ...sale, payments })).toEqual([`payments.1.${field}`]);
+    });
+
+    it.each([
+        ['speiTrackingKey', { speiTrackingKey: null }],
+        ['speiTrackingKey', { speiTrackingKey: '12345' }],
+        ['senderClabe', { senderClabe: '0121' }],
+        ['cardLast4', { cardLast4: '4242' }],
+    ])('rechaza %s fuera de regla en WIRE', async (field, patch) => {
+        const payments = [cashPayment, { ...wirePayment, ...patch }];
+        expect(await errorsOf(RetailSystemSale, { ...sale, payments })).toEqual([`payments.1.${field}`]);
+    });
+});
+
+describe('RetailSystemSale.lines[].promotionId', () => {
+    it('la llave es obligatoria aunque sea null', async () => {
+        const lines = [{ ...sale.lines[0], promotionId: undefined }, sale.lines[1]];
+        expect(await errorsOf(RetailSystemSale, { ...sale, lines })).toEqual(['lines.0.promotionId']);
+    });
+
+    it('acepta una promoción en una línea con descuento', async () => {
+        const lines = [{ ...sale.lines[0], discount: '500.00', promotionId: 'PRM-1' }, sale.lines[1]];
+        expect(await errorsOf(RetailSystemSale, { ...sale, lines })).toEqual([]);
+    });
+
+    it.each([
+        ['vacío', ' '],
+        ['más de 64', 'P'.repeat(65)],
+    ])('rechaza promotionId %s', async (_case, promotionId) => {
+        const lines = [{ ...sale.lines[0], promotionId }, sale.lines[1]];
+        expect(await errorsOf(RetailSystemSale, { ...sale, lines })).toEqual(['lines.0.promotionId']);
+    });
+
+    it('un regalo exige promotionId', async () => {
+        const lines = [sale.lines[0], { ...sale.lines[1], promotionId: null }];
+        expect(await errorsOf(RetailSystemSale, { ...sale, lines })).toEqual(['lines.1.promotionId']);
+    });
+});
+
 describe('CancelRetailSaleRequest', () => {
-    const cancel = { saleId: sale.saleId, cancelledAt: '2026-10-25T19:00:00-06:00', reason: 'Cliente desistió' };
+    const cancel: CancelRetailSaleRequest = {
+        saleId: sale.saleId,
+        cancelledAt: '2026-10-25T19:00:00-06:00',
+        reason: 'Cliente desistió',
+        damaged: [
+            { sku: 'IPH-15', identifier: '356789012345678', qty: 1 },
+            { sku: 'FUNDA-1', identifier: null, qty: 3 },
+        ],
+    };
 
-    it('acepta la cancelación', async () => {
+    it('acepta la cancelación con y sin dañados', async () => {
         expect(await errorsOf(CancelRetailSaleRequest, cancel)).toEqual([]);
+        expect(await errorsOf(CancelRetailSaleRequest, { ...cancel, damaged: [] })).toEqual([]);
+    });
+
+    it('acepta reason de 200 caracteres', async () => {
+        expect(await errorsOf(CancelRetailSaleRequest, { ...cancel, reason: 'r'.repeat(200) })).toEqual([]);
     });
 
     it.each([
@@ -102,10 +241,23 @@ describe('CancelRetailSaleRequest', () => {
         ['cancelledAt', { cancelledAt: '2026-02-31T10:00:00Z' }],
         ['reason', { reason: '' }],
         ['reason', { reason: undefined }],
+        ['reason', { reason: 'r'.repeat(201) }],
+        ['damaged', { damaged: undefined }],
     ])('rechaza %s inválido', async (field, patch) => {
         expect(await errorsOf(CancelRetailSaleRequest, { ...cancel, ...patch })).toEqual([field]);
     });
 
+    it.each([
+        ['sku', { sku: 'a/b' }],
+        ['identifier', { identifier: undefined }],
+        ['identifier', { identifier: ' ' }],
+        ['qty', { qty: 0 }],
+        ['qty', { qty: 2 }],
+    ])('rechaza damaged[].%s inválido', async (field, patch) => {
+        const damaged = [{ ...cancel.damaged[0], ...patch }];
+        expect(await errorsOf(CancelRetailSaleRequest, { ...cancel, damaged })).toEqual([`damaged.0.${field}`]);
+    });
+
     it('la respuesta trae el saleId', () => {
         const response: CancelRetailSaleResponse = { saleId: cancel.saleId };
         expect(response.saleId).toBe(cancel.saleId);

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

@@ -5,6 +5,7 @@ import {
     RetailFinancierEnum,
     RetailLinePaymentTypeEnum,
     RetailMdmProviderEnum,
+    RetailPaymentFrequencyEnum,
     RetailPaymentMethodEnum,
     RetailPieceReasonEnum,
     RetailPieceStatusEnum,
@@ -35,7 +36,8 @@ describe('enums de los objetos del retailer', () => {
         [RetailUserAccessStatusEnum, ['ACTIVE', 'SUSPENDED', 'INACTIVE']],
         [RetailSaleTypeEnum, ['CASH', 'CREDIT', 'EXTERNAL_REFERRAL']],
         [RetailSaleFinancierEnum, ['NONE', 'SUREKEEP', 'PAYJOY', 'CREDIYA', 'LESPAGO', 'INNOVA']],
-        [RetailPaymentMethodEnum, ['CASH', 'CARD', 'SPEI']],
+        [RetailPaymentMethodEnum, ['CASH', 'CARD', 'WIRE', 'FIADO']],
+        [RetailPaymentFrequencyEnum, ['WEEKLY', 'BIWEEKLY', 'MONTHLY']],
         [RetailLinePaymentTypeEnum, ['CASH', 'CREDIT']],
     ])('%p trae exactamente los valores del contrato', (enumObject, values) => {
         expect(Object.values(enumObject)).toEqual(values);

package/bin/retailIntegration/constants/retailIntegrationLimits.d.ts

@@ -45,3 +45,18 @@ export declare const RETAIL_LINE_INDEX_MIN = 0;
 export declare const RETAIL_LINE_INDEX_MAX = 999;
 /** Rango máximo de `GET /inventory/movements`: 7 días en milisegundos. */
 export declare const RETAIL_MOVEMENTS_RANGE_MAX_MS: number;
+/** Decimal de la venta y la cancelación: hasta 12 enteros y dos decimales, nunca negativo. */
+export declare const RETAIL_SALE_DECIMAL_PATTERN: RegExp;
+/** Decimal de la venta mayor que cero, como `payments[].amount`. */
+export declare const RETAIL_SALE_POSITIVE_DECIMAL_PATTERN: RegExp;
+/** Texto libre corto de la venta, como `authCode` y `promotionId`: no vacío y de a lo más 64. */
+export declare const RETAIL_SALE_ID_TEXT_PATTERN: RegExp;
+/** Últimos 4 dígitos de la tarjeta en un pago `CARD`. */
+export declare const RETAIL_CARD_LAST4_PATTERN: RegExp;
+/** Clave de rastreo SPEI y CLABE de un pago `WIRE`: 18 dígitos. */
+export declare const RETAIL_SPEI_TRACKING_KEY_PATTERN: RegExp;
+export declare const RETAIL_CLABE_PATTERN: RegExp;
+/** Tope del motivo de cancelación de una venta. */
+export declare const RETAIL_CANCEL_REASON_MAX_LENGTH = 200;
+/** Teléfono del cliente en la venta: 10 dígitos. */
+export declare const RETAIL_CUSTOMER_PHONE_PATTERN: RegExp;

package/bin/retailIntegration/constants/retailIntegrationLimits.js

@@ -1,6 +1,6 @@
 "use strict";
 Object.defineProperty(exports, "__esModule", { value: true });
-exports.RETAIL_MOVEMENTS_RANGE_MAX_MS = exports.RETAIL_LINE_INDEX_MAX = exports.RETAIL_LINE_INDEX_MIN = exports.RETAIL_ERROR_CODE_MAX_LENGTH = exports.RETAIL_EXTERNAL_ID_PATTERN = exports.RETAIL_NEXT_TOKEN_MAX_LENGTH = exports.RETAIL_EVENT_DECIMAL_PATTERN = exports.RETAIL_ELIGIBLE_FINANCIERS_MAX = exports.RETAIL_EVENT_STOCK_MAX = exports.RETAIL_LONG_TEXT_MAX_LENGTH = exports.RETAIL_SHORT_TEXT_MAX_LENGTH = exports.RETAIL_ID_TEXT_MAX_LENGTH = exports.RETAIL_EVENT_PIECES_MAX = exports.RETAIL_LIVE_CHECK_IDENTIFIERS_MAX = exports.RETAIL_DECIMAL_PATTERN = exports.RETAIL_SKU_PATTERN = exports.RETAIL_ZIP_CODE_MAX_LENGTH = exports.RETAIL_ZIP_CODE_MIN_LENGTH = exports.RETAIL_STORE_CODE_MAX_LENGTH = exports.RETAIL_ZONE_ID_PATTERN = exports.RETAIL_ENTITY_ID_PATTERN = exports.RETAIL_TENANT_ID_PATTERN = exports.RETAIL_LIST_LIMIT_MAX = exports.RETAIL_LIST_LIMIT_MIN = exports.RETAIL_EVENT_ID_MAX_LENGTH = void 0;
+exports.RETAIL_CUSTOMER_PHONE_PATTERN = exports.RETAIL_CANCEL_REASON_MAX_LENGTH = exports.RETAIL_CLABE_PATTERN = exports.RETAIL_SPEI_TRACKING_KEY_PATTERN = exports.RETAIL_CARD_LAST4_PATTERN = exports.RETAIL_SALE_ID_TEXT_PATTERN = exports.RETAIL_SALE_POSITIVE_DECIMAL_PATTERN = exports.RETAIL_SALE_DECIMAL_PATTERN = exports.RETAIL_MOVEMENTS_RANGE_MAX_MS = exports.RETAIL_LINE_INDEX_MAX = exports.RETAIL_LINE_INDEX_MIN = exports.RETAIL_ERROR_CODE_MAX_LENGTH = exports.RETAIL_EXTERNAL_ID_PATTERN = exports.RETAIL_NEXT_TOKEN_MAX_LENGTH = exports.RETAIL_EVENT_DECIMAL_PATTERN = exports.RETAIL_ELIGIBLE_FINANCIERS_MAX = exports.RETAIL_EVENT_STOCK_MAX = exports.RETAIL_LONG_TEXT_MAX_LENGTH = exports.RETAIL_SHORT_TEXT_MAX_LENGTH = exports.RETAIL_ID_TEXT_MAX_LENGTH = exports.RETAIL_EVENT_PIECES_MAX = exports.RETAIL_LIVE_CHECK_IDENTIFIERS_MAX = exports.RETAIL_DECIMAL_PATTERN = exports.RETAIL_SKU_PATTERN = exports.RETAIL_ZIP_CODE_MAX_LENGTH = exports.RETAIL_ZIP_CODE_MIN_LENGTH = exports.RETAIL_STORE_CODE_MAX_LENGTH = exports.RETAIL_ZONE_ID_PATTERN = exports.RETAIL_ENTITY_ID_PATTERN = exports.RETAIL_TENANT_ID_PATTERN = exports.RETAIL_LIST_LIMIT_MAX = exports.RETAIL_LIST_LIMIT_MIN = exports.RETAIL_EVENT_ID_MAX_LENGTH = void 0;
 /** Tope de `eventId`: el límite seguro de una llave de DynamoDB. */
 exports.RETAIL_EVENT_ID_MAX_LENGTH = 1024;
 /** Rango de `limit` en las listas paginadas del retailer. */
@@ -48,3 +48,18 @@ exports.RETAIL_LINE_INDEX_MIN = 0;
 exports.RETAIL_LINE_INDEX_MAX = 999;
 /** Rango máximo de `GET /inventory/movements`: 7 días en milisegundos. */
 exports.RETAIL_MOVEMENTS_RANGE_MAX_MS = 7 * 24 * 60 * 60 * 1000;
+/** Decimal de la venta y la cancelación: hasta 12 enteros y dos decimales, nunca negativo. */
+exports.RETAIL_SALE_DECIMAL_PATTERN = /^\d{1,12}\.\d{2}$/;
+/** Decimal de la venta mayor que cero, como `payments[].amount`. */
+exports.RETAIL_SALE_POSITIVE_DECIMAL_PATTERN = /^(?=.*[1-9])\d{1,12}\.\d{2}$/;
+/** Texto libre corto de la venta, como `authCode` y `promotionId`: no vacío y de a lo más 64. */
+exports.RETAIL_SALE_ID_TEXT_PATTERN = /^(?=.*\S).{1,64}$/;
+/** Últimos 4 dígitos de la tarjeta en un pago `CARD`. */
+exports.RETAIL_CARD_LAST4_PATTERN = /^\d{4}$/;
+/** Clave de rastreo SPEI y CLABE de un pago `WIRE`: 18 dígitos. */
+exports.RETAIL_SPEI_TRACKING_KEY_PATTERN = /^\d{18}$/;
+exports.RETAIL_CLABE_PATTERN = /^\d{18}$/;
+/** Tope del motivo de cancelación de una venta. */
+exports.RETAIL_CANCEL_REASON_MAX_LENGTH = 200;
+/** Teléfono del cliente en la venta: 10 dígitos. */
+exports.RETAIL_CUSTOMER_PHONE_PATTERN = /^\d{10}$/;

package/bin/retailIntegration/dtos/CancelRetailSaleRequest.d.ts

@@ -1,6 +1,13 @@
+/** Lo que regresa dañado al cancelar; `identifier` en `null` si el producto es `QUANTITY`. */
+export declare class RetailSystemDamagedItem {
+    sku: string;
+    identifier: string | null;
+    qty: number;
+}
 /** Cuerpo de `POST /private/retail/sales/cancel`; el `saleId` es el mismo del registro. */
 export declare class CancelRetailSaleRequest {
     saleId: string;
     cancelledAt: string;
     reason: string;
+    damaged: RetailSystemDamagedItem[];
 }

package/bin/retailIntegration/dtos/CancelRetailSaleRequest.js

@@ -9,9 +9,35 @@ 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.CancelRetailSaleRequest = void 0;
+exports.CancelRetailSaleRequest = exports.RetailSystemDamagedItem = void 0;
+const class_transformer_1 = require("class-transformer");
 const class_validator_1 = require("class-validator");
+const retailIntegrationLimits_1 = require("../constants/retailIntegrationLimits");
 const IsIsoDateTimeWithZone_1 = require("../validators/IsIsoDateTimeWithZone");
+const payloadValidators_1 = require("../validators/payloadValidators");
+const saleValidators_1 = require("../validators/saleValidators");
+/** Lo que regresa dañado al cancelar; `identifier` en `null` si el producto es `QUANTITY`. */
+class RetailSystemDamagedItem {
+}
+exports.RetailSystemDamagedItem = RetailSystemDamagedItem;
+__decorate([
+    (0, class_validator_1.IsString)(),
+    (0, class_validator_1.Matches)(retailIntegrationLimits_1.RETAIL_SKU_PATTERN),
+    __metadata("design:type", String)
+], RetailSystemDamagedItem.prototype, "sku", void 0);
+__decorate([
+    (0, class_validator_1.ValidateIf)(payloadValidators_1.isNullOrValidated),
+    (0, class_validator_1.IsString)(),
+    (0, class_validator_1.Matches)(/\S/),
+    (0, class_validator_1.MaxLength)(retailIntegrationLimits_1.RETAIL_SHORT_TEXT_MAX_LENGTH),
+    __metadata("design:type", String)
+], RetailSystemDamagedItem.prototype, "identifier", void 0);
+__decorate([
+    (0, class_validator_1.IsInt)(),
+    (0, class_validator_1.Min)(1),
+    (0, class_validator_1.Validate)(saleValidators_1.QtyMatchesIdentifier),
+    __metadata("design:type", Number)
+], RetailSystemDamagedItem.prototype, "qty", void 0);
 /** Cuerpo de `POST /private/retail/sales/cancel`; el `saleId` es el mismo del registro. */
 class CancelRetailSaleRequest {
 }
@@ -28,5 +54,12 @@ __decorate([
 __decorate([
     (0, class_validator_1.IsString)(),
     (0, class_validator_1.Matches)(/\S/),
+    (0, class_validator_1.MaxLength)(retailIntegrationLimits_1.RETAIL_CANCEL_REASON_MAX_LENGTH),
     __metadata("design:type", String)
 ], CancelRetailSaleRequest.prototype, "reason", void 0);
+__decorate([
+    (0, class_validator_1.IsArray)(),
+    (0, class_validator_1.ValidateNested)({ each: true }),
+    (0, class_transformer_1.Type)(() => RetailSystemDamagedItem),
+    __metadata("design:type", Array)
+], CancelRetailSaleRequest.prototype, "damaged", void 0);

package/bin/retailIntegration/enums/RetailPaymentFrequencyEnum.d.ts

@@ -0,0 +1,6 @@
+/** Cada cuánto paga el cliente en `credit.paymentFrequency`. */
+export declare enum RetailPaymentFrequencyEnum {
+    WEEKLY = "WEEKLY",
+    BIWEEKLY = "BIWEEKLY",
+    MONTHLY = "MONTHLY"
+}

package/bin/retailIntegration/enums/RetailPaymentFrequencyEnum.js

@@ -0,0 +1,10 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.RetailPaymentFrequencyEnum = void 0;
+/** Cada cuánto paga el cliente en `credit.paymentFrequency`. */
+var RetailPaymentFrequencyEnum;
+(function (RetailPaymentFrequencyEnum) {
+    RetailPaymentFrequencyEnum["WEEKLY"] = "WEEKLY";
+    RetailPaymentFrequencyEnum["BIWEEKLY"] = "BIWEEKLY";
+    RetailPaymentFrequencyEnum["MONTHLY"] = "MONTHLY";
+})(RetailPaymentFrequencyEnum || (exports.RetailPaymentFrequencyEnum = RetailPaymentFrequencyEnum = {}));

package/bin/retailIntegration/enums/RetailPaymentMethodEnum.d.ts

@@ -1,6 +1,7 @@
-/** Método de pago de la venta. */
+/** Medio de pago de `payments[].method` en la venta. */
 export declare enum RetailPaymentMethodEnum {
     CASH = "CASH",
     CARD = "CARD",
-    SPEI = "SPEI"
+    WIRE = "WIRE",
+    FIADO = "FIADO"
 }

package/bin/retailIntegration/enums/RetailPaymentMethodEnum.js

@@ -1,10 +1,11 @@
 "use strict";
 Object.defineProperty(exports, "__esModule", { value: true });
 exports.RetailPaymentMethodEnum = void 0;
-/** Método de pago de la venta. */
+/** Medio de pago de `payments[].method` en la venta. */
 var RetailPaymentMethodEnum;
 (function (RetailPaymentMethodEnum) {
     RetailPaymentMethodEnum["CASH"] = "CASH";
     RetailPaymentMethodEnum["CARD"] = "CARD";
-    RetailPaymentMethodEnum["SPEI"] = "SPEI";
+    RetailPaymentMethodEnum["WIRE"] = "WIRE";
+    RetailPaymentMethodEnum["FIADO"] = "FIADO";
 })(RetailPaymentMethodEnum || (exports.RetailPaymentMethodEnum = RetailPaymentMethodEnum = {}));

package/bin/retailIntegration/enums/index.d.ts

@@ -18,6 +18,7 @@ export * from './RetailUserAccessStatusEnum';
 export * from './RetailSaleTypeEnum';
 export * from './RetailSaleFinancierEnum';
 export * from './RetailPaymentMethodEnum';
+export * from './RetailPaymentFrequencyEnum';
 export * from './RetailLinePaymentTypeEnum';
 export * from './RetailSaleLineRoleEnum';
 export * from './RetailEventRejectCodeEnum';

package/bin/retailIntegration/enums/index.js

@@ -34,6 +34,7 @@ __exportStar(require("./RetailUserAccessStatusEnum"), exports);
 __exportStar(require("./RetailSaleTypeEnum"), exports);
 __exportStar(require("./RetailSaleFinancierEnum"), exports);
 __exportStar(require("./RetailPaymentMethodEnum"), exports);
+__exportStar(require("./RetailPaymentFrequencyEnum"), exports);
 __exportStar(require("./RetailLinePaymentTypeEnum"), exports);
 __exportStar(require("./RetailSaleLineRoleEnum"), exports);
 __exportStar(require("./RetailEventRejectCodeEnum"), exports);

package/bin/retailIntegration/index.d.ts

@@ -3,6 +3,8 @@ export * from './constants/retailIntegrationErrorHttpStatus';
 export * from './enums';
 export * from './validators/IsIsoDateTimeWithZone';
 export * from './validators/IsMovementsRangeValid';
+export * from './validators/IsCalendarDate';
+export * from './validators/saleValidators';
 export * from './dtos/RetailEventEnvelope';
 export * from './dtos/ReceiveStoreEventRequest';
 export * from './dtos/ReceiveRetailUserEventRequest';

package/bin/retailIntegration/index.js

@@ -19,6 +19,8 @@ __exportStar(require("./constants/retailIntegrationErrorHttpStatus"), exports);
 __exportStar(require("./enums"), exports);
 __exportStar(require("./validators/IsIsoDateTimeWithZone"), exports);
 __exportStar(require("./validators/IsMovementsRangeValid"), exports);
+__exportStar(require("./validators/IsCalendarDate"), exports);
+__exportStar(require("./validators/saleValidators"), exports);
 __exportStar(require("./dtos/RetailEventEnvelope"), exports);
 __exportStar(require("./dtos/ReceiveStoreEventRequest"), exports);
 __exportStar(require("./dtos/ReceiveRetailUserEventRequest"), exports);

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

@@ -1,8 +1,9 @@
-import { RetailLinePaymentTypeEnum, RetailPaymentMethodEnum, RetailSaleFinancierEnum, RetailSaleLineRoleEnum, RetailSaleTypeEnum } from '../enums';
+import { RetailLinePaymentTypeEnum, RetailPaymentFrequencyEnum, RetailPaymentMethodEnum, RetailSaleFinancierEnum, RetailSaleLineRoleEnum, RetailSaleTypeEnum } from '../enums';
 import { RetailCurrency } from './RetailSystemProduct';
 export type RetailSaleType = `${RetailSaleTypeEnum}`;
 export type RetailSaleFinancier = `${RetailSaleFinancierEnum}`;
 export type RetailPaymentMethod = `${RetailPaymentMethodEnum}`;
+export type RetailPaymentFrequency = `${RetailPaymentFrequencyEnum}`;
 export type RetailLinePaymentType = `${RetailLinePaymentTypeEnum}`;
 export type RetailSaleLineRole = `${RetailSaleLineRoleEnum}`;
 export declare class RetailSystemSaleCustomer {
@@ -12,6 +13,24 @@ export declare class RetailSystemSaleCustomer {
     maternalLastName: string | null;
     phone: string;
 }
+/** Condiciones del crédito; todas obligatorias cuando `credit` no es `null`. */
+export declare class RetailSystemSaleCredit {
+    paymentFrequency: RetailPaymentFrequency;
+    installments: number;
+    installmentAmount: string;
+    downPayment: string;
+    totalToPay: string;
+    firstPaymentDate: string;
+}
+/** Un medio de pago de `amountPaid`; las seis llaves van siempre, en `null` las que no aplican. */
+export declare class RetailSystemSalePayment {
+    method: RetailPaymentMethod;
+    amount: string;
+    cardLast4: string | null;
+    authCode: string | null;
+    speiTrackingKey: string | null;
+    senderClabe: string | null;
+}
 export declare class RetailSystemSaleComponent {
     sku: string;
     qty: number;
@@ -26,6 +45,7 @@ export declare class RetailSystemSaleLine {
     paymentType: RetailLinePaymentType;
     financedAmount: string;
     role: RetailSaleLineRole | null;
+    promotionId: string | null;
     components: RetailSystemSaleComponent[];
 }
 /** Cuerpo de `POST /sales` de la doc y de `privateRegisterRetailSale`; `saleId` es la llave de idempotencia. */
@@ -38,10 +58,11 @@ export declare class RetailSystemSale {
     saleType: RetailSaleType;
     financier: RetailSaleFinancier;
     creditId: string | null;
+    credit: RetailSystemSaleCredit | null;
     currencyId: RetailCurrency;
     customer: RetailSystemSaleCustomer;
     equipmentPrice: string;
     amountPaid: string;
-    paymentMethod: RetailPaymentMethod | null;
+    payments: RetailSystemSalePayment[];
     lines: RetailSystemSaleLine[];
 }

package/bin/retailIntegration/models/RetailSystemSale.js

@@ -9,13 +9,16 @@ 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.RetailSystemSale = exports.RetailSystemSaleLine = exports.RetailSystemSaleComponent = exports.RetailSystemSaleCustomer = void 0;
+exports.RetailSystemSale = exports.RetailSystemSaleLine = exports.RetailSystemSaleComponent = exports.RetailSystemSalePayment = exports.RetailSystemSaleCredit = exports.RetailSystemSaleCustomer = void 0;
 const class_transformer_1 = require("class-transformer");
 const class_validator_1 = require("class-validator");
 const retailIntegrationLimits_1 = require("../constants/retailIntegrationLimits");
 const enums_1 = require("../enums");
+const IsCalendarDate_1 = require("../validators/IsCalendarDate");
 const IsIsoDateTimeWithZone_1 = require("../validators/IsIsoDateTimeWithZone");
 const payloadValidators_1 = require("../validators/payloadValidators");
+const saleValidators_1 = require("../validators/saleValidators");
+const { CARD, WIRE } = enums_1.RetailPaymentMethodEnum;
 class RetailSystemSaleCustomer {
 }
 exports.RetailSystemSaleCustomer = RetailSystemSaleCustomer;
@@ -41,9 +44,70 @@ __decorate([
 ], RetailSystemSaleCustomer.prototype, "maternalLastName", void 0);
 __decorate([
     (0, class_validator_1.IsString)(),
-    (0, class_validator_1.Matches)(/\S/),
+    (0, class_validator_1.Matches)(retailIntegrationLimits_1.RETAIL_CUSTOMER_PHONE_PATTERN),
     __metadata("design:type", String)
 ], RetailSystemSaleCustomer.prototype, "phone", void 0);
+/** Condiciones del crédito; todas obligatorias cuando `credit` no es `null`. */
+class RetailSystemSaleCredit {
+}
+exports.RetailSystemSaleCredit = RetailSystemSaleCredit;
+__decorate([
+    (0, class_validator_1.IsIn)(Object.values(enums_1.RetailPaymentFrequencyEnum)),
+    __metadata("design:type", String)
+], RetailSystemSaleCredit.prototype, "paymentFrequency", void 0);
+__decorate([
+    (0, class_validator_1.IsInt)(),
+    (0, class_validator_1.Min)(1),
+    __metadata("design:type", Number)
+], RetailSystemSaleCredit.prototype, "installments", void 0);
+__decorate([
+    (0, class_validator_1.IsString)(),
+    (0, class_validator_1.Matches)(retailIntegrationLimits_1.RETAIL_SALE_DECIMAL_PATTERN),
+    __metadata("design:type", String)
+], RetailSystemSaleCredit.prototype, "installmentAmount", void 0);
+__decorate([
+    (0, class_validator_1.IsString)(),
+    (0, class_validator_1.Matches)(retailIntegrationLimits_1.RETAIL_SALE_DECIMAL_PATTERN),
+    __metadata("design:type", String)
+], RetailSystemSaleCredit.prototype, "downPayment", void 0);
+__decorate([
+    (0, class_validator_1.IsString)(),
+    (0, class_validator_1.Matches)(retailIntegrationLimits_1.RETAIL_SALE_DECIMAL_PATTERN),
+    __metadata("design:type", String)
+], RetailSystemSaleCredit.prototype, "totalToPay", void 0);
+__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. */
+class RetailSystemSalePayment {
+}
+exports.RetailSystemSalePayment = RetailSystemSalePayment;
+__decorate([
+    (0, class_validator_1.IsIn)(Object.values(enums_1.RetailPaymentMethodEnum)),
+    __metadata("design:type", String)
+], RetailSystemSalePayment.prototype, "method", void 0);
+__decorate([
+    (0, class_validator_1.IsString)(),
+    (0, class_validator_1.Matches)(retailIntegrationLimits_1.RETAIL_SALE_POSITIVE_DECIMAL_PATTERN),
+    __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]),
+    __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]),
+    __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]),
+    __metadata("design:type", String)
+], RetailSystemSalePayment.prototype, "speiTrackingKey", void 0);
+__decorate([
+    (0, class_validator_1.Validate)(saleValidators_1.MatchesForPaymentMethod, [WIRE, retailIntegrationLimits_1.RETAIL_CLABE_PATTERN, true]),
+    __metadata("design:type", String)
+], RetailSystemSalePayment.prototype, "senderClabe", void 0);
 class RetailSystemSaleComponent {
 }
 exports.RetailSystemSaleComponent = RetailSystemSaleComponent;
@@ -83,12 +147,12 @@ __decorate([
 ], RetailSystemSaleLine.prototype, "qty", void 0);
 __decorate([
     (0, class_validator_1.IsString)(),
-    (0, class_validator_1.Matches)(retailIntegrationLimits_1.RETAIL_DECIMAL_PATTERN),
+    (0, class_validator_1.Matches)(retailIntegrationLimits_1.RETAIL_SALE_DECIMAL_PATTERN),
     __metadata("design:type", String)
 ], RetailSystemSaleLine.prototype, "basePrice", void 0);
 __decorate([
     (0, class_validator_1.IsString)(),
-    (0, class_validator_1.Matches)(retailIntegrationLimits_1.RETAIL_DECIMAL_PATTERN),
+    (0, class_validator_1.Matches)(retailIntegrationLimits_1.RETAIL_SALE_DECIMAL_PATTERN),
     __metadata("design:type", String)
 ], RetailSystemSaleLine.prototype, "discount", void 0);
 __decorate([
@@ -97,7 +161,7 @@ __decorate([
 ], RetailSystemSaleLine.prototype, "paymentType", void 0);
 __decorate([
     (0, class_validator_1.IsString)(),
-    (0, class_validator_1.Matches)(retailIntegrationLimits_1.RETAIL_DECIMAL_PATTERN),
+    (0, class_validator_1.Matches)(retailIntegrationLimits_1.RETAIL_SALE_DECIMAL_PATTERN),
     __metadata("design:type", String)
 ], RetailSystemSaleLine.prototype, "financedAmount", void 0);
 __decorate([
@@ -105,6 +169,10 @@ __decorate([
     (0, class_validator_1.IsIn)(Object.values(enums_1.RetailSaleLineRoleEnum)),
     __metadata("design:type", String)
 ], RetailSystemSaleLine.prototype, "role", void 0);
+__decorate([
+    (0, class_validator_1.Validate)(saleValidators_1.PromotionIdMatchesRole),
+    __metadata("design:type", String)
+], RetailSystemSaleLine.prototype, "promotionId", void 0);
 __decorate([
     (0, class_validator_1.IsArray)(),
     (0, class_validator_1.ValidateNested)({ each: true }),
@@ -145,6 +213,7 @@ __decorate([
 ], RetailSystemSale.prototype, "saleType", void 0);
 __decorate([
     (0, class_validator_1.IsIn)(Object.values(enums_1.RetailSaleFinancierEnum)),
+    (0, class_validator_1.Validate)(saleValidators_1.CreditMatchesFinancier),
     __metadata("design:type", String)
 ], RetailSystemSale.prototype, "financier", void 0);
 __decorate([
@@ -153,6 +222,13 @@ __decorate([
     (0, class_validator_1.Matches)(/\S/),
     __metadata("design:type", String)
 ], RetailSystemSale.prototype, "creditId", void 0);
+__decorate([
+    (0, class_validator_1.ValidateIf)(payloadValidators_1.isNullOrValidated),
+    (0, class_validator_1.IsObject)(),
+    (0, class_validator_1.ValidateNested)(),
+    (0, class_transformer_1.Type)(() => RetailSystemSaleCredit),
+    __metadata("design:type", RetailSystemSaleCredit)
+], RetailSystemSale.prototype, "credit", void 0);
 __decorate([
     (0, class_validator_1.IsIn)(Object.values(enums_1.RetailCurrencyEnum)),
     __metadata("design:type", String)
@@ -165,19 +241,21 @@ __decorate([
 ], RetailSystemSale.prototype, "customer", void 0);
 __decorate([
     (0, class_validator_1.IsString)(),
-    (0, class_validator_1.Matches)(retailIntegrationLimits_1.RETAIL_DECIMAL_PATTERN),
+    (0, class_validator_1.Matches)(retailIntegrationLimits_1.RETAIL_SALE_DECIMAL_PATTERN),
     __metadata("design:type", String)
 ], RetailSystemSale.prototype, "equipmentPrice", void 0);
 __decorate([
     (0, class_validator_1.IsString)(),
-    (0, class_validator_1.Matches)(retailIntegrationLimits_1.RETAIL_DECIMAL_PATTERN),
+    (0, class_validator_1.Matches)(retailIntegrationLimits_1.RETAIL_SALE_DECIMAL_PATTERN),
     __metadata("design:type", String)
 ], RetailSystemSale.prototype, "amountPaid", void 0);
 __decorate([
-    (0, class_validator_1.ValidateIf)(payloadValidators_1.isNullOrValidated),
-    (0, class_validator_1.IsIn)(Object.values(enums_1.RetailPaymentMethodEnum)),
-    __metadata("design:type", String)
-], RetailSystemSale.prototype, "paymentMethod", void 0);
+    (0, class_validator_1.IsArray)(),
+    (0, class_validator_1.ValidateNested)({ each: true }),
+    (0, class_transformer_1.Type)(() => RetailSystemSalePayment),
+    (0, class_validator_1.Validate)(saleValidators_1.PaymentsMatchAmountPaid),
+    __metadata("design:type", Array)
+], RetailSystemSale.prototype, "payments", void 0);
 __decorate([
     (0, class_validator_1.IsArray)(),
     (0, class_validator_1.ArrayNotEmpty)(),

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

@@ -0,0 +1,6 @@
+import { ValidatorConstraintInterface } from 'class-validator';
+/** Acepta una fecha `YYYY-MM-DD` que exista en el calendario. */
+export declare class IsCalendarDate implements ValidatorConstraintInterface {
+    validate(value: unknown): boolean;
+    defaultMessage(): string;
+}

package/bin/retailIntegration/validators/IsCalendarDate.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.IsCalendarDate = void 0;
+const class_validator_1 = require("class-validator");
+const calendarDate_1 = require("./calendarDate");
+const CALENDAR_DATE = /^\d{4}-\d{2}-\d{2}$/;
+/** Acepta una fecha `YYYY-MM-DD` que exista en el calendario. */
+let IsCalendarDate = class IsCalendarDate {
+    validate(value) {
+        return typeof value === 'string' && CALENDAR_DATE.test(value) && (0, calendarDate_1.isRealCalendarDate)(value);
+    }
+    defaultMessage() {
+        return 'debe ser una fecha YYYY-MM-DD, por ejemplo 2026-08-21';
+    }
+};
+exports.IsCalendarDate = IsCalendarDate;
+exports.IsCalendarDate = IsCalendarDate = __decorate([
+    (0, class_validator_1.ValidatorConstraint)({ name: 'isCalendarDate', async: false })
+], IsCalendarDate);

package/bin/retailIntegration/validators/IsIsoDateTimeWithZone.js

@@ -8,16 +8,12 @@ var __decorate = (this && this.__decorate) || function (decorators, target, key,
 Object.defineProperty(exports, "__esModule", { value: true });
 exports.IsIsoDateTimeWithZone = void 0;
 const class_validator_1 = require("class-validator");
+const calendarDate_1 = require("./calendarDate");
 const ISO_DATE_TIME_WITH_ZONE = /^\d{4}-\d{2}-\d{2}T\d{2}:\d{2}:\d{2}(\.\d{1,9})?(Z|[+-]\d{2}:\d{2})$/;
-/** Descarta fechas que `Date` recorre en silencio, como el 31 de febrero. */
-function isRealCalendarDate(value) {
-    const [year, month, day] = value.slice(0, 10).split('-').map(Number);
-    return !Number.isNaN(Date.parse(value)) && new Date(Date.UTC(year, month - 1, day)).getUTCDate() === day;
-}
 /** Acepta fecha y hora ISO-8601 con segundos y zona; sin zona se rechaza, como dice la doc. */
 let IsIsoDateTimeWithZone = class IsIsoDateTimeWithZone {
     validate(value) {
-        return typeof value === 'string' && ISO_DATE_TIME_WITH_ZONE.test(value) && isRealCalendarDate(value);
+        return typeof value === 'string' && ISO_DATE_TIME_WITH_ZONE.test(value) && (0, calendarDate_1.isRealCalendarDate)(value);
     }
     defaultMessage() {
         return 'debe ser fecha y hora ISO-8601 con zona, por ejemplo 2026-08-17T20:32:05Z';

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

@@ -0,0 +1,2 @@
+/** Descarta fechas que `Date` recorre en silencio, como el 31 de febrero; lee los primeros 10 caracteres. */
+export declare function isRealCalendarDate(value: string): boolean;

package/bin/retailIntegration/validators/calendarDate.js

@@ -0,0 +1,8 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.isRealCalendarDate = isRealCalendarDate;
+/** Descarta fechas que `Date` recorre en silencio, como el 31 de febrero; lee los primeros 10 caracteres. */
+function isRealCalendarDate(value) {
+    const [year, month, day] = value.slice(0, 10).split('-').map(Number);
+    return !Number.isNaN(Date.parse(value)) && new Date(Date.UTC(year, month - 1, day)).getUTCDate() === day;
+}

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

@@ -0,0 +1,26 @@
+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`. */
+export declare class MatchesForPaymentMethod implements ValidatorConstraintInterface {
+    validate(value: unknown, args: ValidationArguments): boolean;
+    defaultMessage(args: ValidationArguments): string;
+}
+/** La suma de `payments[].amount` es `amountPaid`; con `amountPaid` en `"0.00"` el arreglo va vacío. */
+export declare class PaymentsMatchAmountPaid implements ValidatorConstraintInterface {
+    validate(value: unknown, args: ValidationArguments): boolean;
+    defaultMessage(): string;
+}
+/** `credit` y `creditId`: obligatorios con `SUREKEEP` y `null` en contado. */
+export declare class CreditMatchesFinancier implements ValidatorConstraintInterface {
+    validate(value: unknown, args: ValidationArguments): boolean;
+    defaultMessage(): string;
+}
+/** `promotionId`: texto o `null`, nunca omitido; un regalo siempre lo trae. */
+export declare class PromotionIdMatchesRole implements ValidatorConstraintInterface {
+    validate(value: unknown, args: ValidationArguments): boolean;
+    defaultMessage(): string;
+}
+/** Un dañado con `identifier` es una sola pieza: `qty` debe ser 1. */
+export declare class QtyMatchesIdentifier implements ValidatorConstraintInterface {
+    validate(value: unknown, args: ValidationArguments): boolean;
+    defaultMessage(): string;
+}

package/bin/retailIntegration/validators/saleValidators.js

@@ -0,0 +1,100 @@
+"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.QtyMatchesIdentifier = exports.PromotionIdMatchesRole = exports.CreditMatchesFinancier = exports.PaymentsMatchAmountPaid = exports.MatchesForPaymentMethod = void 0;
+const class_validator_1 = require("class-validator");
+const retailIntegrationLimits_1 = require("../constants/retailIntegrationLimits");
+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`. */
+let MatchesForPaymentMethod = class MatchesForPaymentMethod {
+    validate(value, args) {
+        const [method, pattern, nullable] = args.constraints;
+        if (args.object.method !== method)
+            return value === null;
+        if (value === null)
+            return nullable === true;
+        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`;
+    }
+};
+exports.MatchesForPaymentMethod = MatchesForPaymentMethod;
+exports.MatchesForPaymentMethod = MatchesForPaymentMethod = __decorate([
+    (0, class_validator_1.ValidatorConstraint)({ name: 'matchesForPaymentMethod', async: false })
+], MatchesForPaymentMethod);
+/** La suma de `payments[].amount` es `amountPaid`; con `amountPaid` en `"0.00"` el arreglo va vacío. */
+let PaymentsMatchAmountPaid = class PaymentsMatchAmountPaid {
+    validate(value, args) {
+        const amountPaid = args.object.amountPaid;
+        if (!Array.isArray(value) || typeof amountPaid !== 'string' || !retailIntegrationLimits_1.RETAIL_SALE_DECIMAL_PATTERN.test(amountPaid))
+            return true;
+        const amounts = value.map((p) => p?.amount);
+        if (!amounts.every((a) => typeof a === 'string' && retailIntegrationLimits_1.RETAIL_SALE_POSITIVE_DECIMAL_PATTERN.test(a)))
+            return true;
+        const total = amounts.reduce((sum, a) => sum + decimalToCents(a), 0);
+        return total === decimalToCents(amountPaid);
+    }
+    defaultMessage() {
+        return 'la suma de payments[].amount debe ser amountPaid; [] solo si amountPaid es 0.00';
+    }
+};
+exports.PaymentsMatchAmountPaid = PaymentsMatchAmountPaid;
+exports.PaymentsMatchAmountPaid = PaymentsMatchAmountPaid = __decorate([
+    (0, class_validator_1.ValidatorConstraint)({ name: 'paymentsMatchAmountPaid', async: false })
+], PaymentsMatchAmountPaid);
+/** `credit` y `creditId`: obligatorios con `SUREKEEP` y `null` en contado. */
+let CreditMatchesFinancier = class CreditMatchesFinancier {
+    validate(value, args) {
+        const { saleType, credit, creditId } = args.object;
+        if (value === enums_1.RetailSaleFinancierEnum.SUREKEEP)
+            return credit !== null && creditId !== null;
+        if (value === enums_1.RetailSaleFinancierEnum.NONE || saleType === enums_1.RetailSaleTypeEnum.CASH)
+            return credit == null && creditId == null;
+        return true;
+    }
+    defaultMessage() {
+        return 'credit y creditId son obligatorios con SUREKEEP y null en contado';
+    }
+};
+exports.CreditMatchesFinancier = CreditMatchesFinancier;
+exports.CreditMatchesFinancier = CreditMatchesFinancier = __decorate([
+    (0, class_validator_1.ValidatorConstraint)({ name: 'creditMatchesFinancier', async: false })
+], CreditMatchesFinancier);
+/** `promotionId`: texto o `null`, nunca omitido; un regalo siempre lo trae. */
+let PromotionIdMatchesRole = class PromotionIdMatchesRole {
+    validate(value, args) {
+        if (value === null)
+            return args.object.role !== enums_1.RetailSaleLineRoleEnum.GIFT;
+        return typeof value === 'string' && retailIntegrationLimits_1.RETAIL_SALE_ID_TEXT_PATTERN.test(value);
+    }
+    defaultMessage() {
+        return 'promotionId es texto de 1 a 64 o null, y obligatorio con role GIFT';
+    }
+};
+exports.PromotionIdMatchesRole = PromotionIdMatchesRole;
+exports.PromotionIdMatchesRole = PromotionIdMatchesRole = __decorate([
+    (0, class_validator_1.ValidatorConstraint)({ name: 'promotionIdMatchesRole', async: false })
+], PromotionIdMatchesRole);
+/** Un dañado con `identifier` es una sola pieza: `qty` debe ser 1. */
+let QtyMatchesIdentifier = class QtyMatchesIdentifier {
+    validate(value, args) {
+        const identifier = args.object.identifier;
+        return typeof identifier !== 'string' || value === 1;
+    }
+    defaultMessage() {
+        return 'qty debe ser 1 cuando viene identifier';
+    }
+};
+exports.QtyMatchesIdentifier = QtyMatchesIdentifier;
+exports.QtyMatchesIdentifier = QtyMatchesIdentifier = __decorate([
+    (0, class_validator_1.ValidatorConstraint)({ name: 'qtyMatchesIdentifier', async: false })
+], QtyMatchesIdentifier);

package/package.json

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

package/src/retailIntegration/constants/retailIntegrationLimits.ts

@@ -66,3 +66,25 @@ export const RETAIL_LINE_INDEX_MAX = 999;
 
 /** Rango máximo de `GET /inventory/movements`: 7 días en milisegundos. */
 export const RETAIL_MOVEMENTS_RANGE_MAX_MS = 7 * 24 * 60 * 60 * 1000;
+
+/** Decimal de la venta y la cancelación: hasta 12 enteros y dos decimales, nunca negativo. */
+export const RETAIL_SALE_DECIMAL_PATTERN = /^\d{1,12}\.\d{2}$/;
+
+/** Decimal de la venta mayor que cero, como `payments[].amount`. */
+export const RETAIL_SALE_POSITIVE_DECIMAL_PATTERN = /^(?=.*[1-9])\d{1,12}\.\d{2}$/;
+
+/** Texto libre corto de la venta, como `authCode` y `promotionId`: no vacío y de a lo más 64. */
+export const RETAIL_SALE_ID_TEXT_PATTERN = /^(?=.*\S).{1,64}$/;
+
+/** Últimos 4 dígitos de la tarjeta en un pago `CARD`. */
+export const RETAIL_CARD_LAST4_PATTERN = /^\d{4}$/;
+
+/** Clave de rastreo SPEI y CLABE de un pago `WIRE`: 18 dígitos. */
+export const RETAIL_SPEI_TRACKING_KEY_PATTERN = /^\d{18}$/;
+export const RETAIL_CLABE_PATTERN = /^\d{18}$/;
+
+/** Tope del motivo de cancelación de una venta. */
+export const RETAIL_CANCEL_REASON_MAX_LENGTH = 200;
+
+/** Teléfono del cliente en la venta: 10 dígitos. */
+export const RETAIL_CUSTOMER_PHONE_PATTERN = /^\d{10}$/;

package/src/retailIntegration/dtos/CancelRetailSaleRequest.ts

@@ -1,9 +1,21 @@
-import { IsString, Matches, Validate } from 'class-validator';
+import { Type } from 'class-transformer';
+import { IsArray, IsInt, IsString, Matches, MaxLength, Min, Validate, ValidateIf, ValidateNested } from 'class-validator';
+import { RETAIL_CANCEL_REASON_MAX_LENGTH, RETAIL_SHORT_TEXT_MAX_LENGTH, RETAIL_SKU_PATTERN } from '../constants/retailIntegrationLimits';
 import { IsIsoDateTimeWithZone } from '../validators/IsIsoDateTimeWithZone';
+import { isNullOrValidated } from '../validators/payloadValidators';
+import { QtyMatchesIdentifier } from '../validators/saleValidators';
+
+/** Lo que regresa dañado al cancelar; `identifier` en `null` si el producto es `QUANTITY`. */
+export class RetailSystemDamagedItem {
+    @IsString() @Matches(RETAIL_SKU_PATTERN) sku!: string;
+    @ValidateIf(isNullOrValidated) @IsString() @Matches(/\S/) @MaxLength(RETAIL_SHORT_TEXT_MAX_LENGTH) identifier!: string | null;
+    @IsInt() @Min(1) @Validate(QtyMatchesIdentifier) qty!: number;
+}
 
 /** Cuerpo de `POST /private/retail/sales/cancel`; el `saleId` es el mismo del registro. */
 export class CancelRetailSaleRequest {
     @IsString() @Matches(/\S/) saleId!: string;
     @Validate(IsIsoDateTimeWithZone) cancelledAt!: string;
-    @IsString() @Matches(/\S/) reason!: string;
+    @IsString() @Matches(/\S/) @MaxLength(RETAIL_CANCEL_REASON_MAX_LENGTH) reason!: string;
+    @IsArray() @ValidateNested({ each: true }) @Type(() => RetailSystemDamagedItem) damaged!: RetailSystemDamagedItem[];
 }

package/src/retailIntegration/enums/RetailPaymentFrequencyEnum.ts

@@ -0,0 +1,6 @@
+/** Cada cuánto paga el cliente en `credit.paymentFrequency`. */
+export enum RetailPaymentFrequencyEnum {
+    WEEKLY = 'WEEKLY',
+    BIWEEKLY = 'BIWEEKLY',
+    MONTHLY = 'MONTHLY',
+}

package/src/retailIntegration/enums/RetailPaymentMethodEnum.ts

@@ -1,6 +1,7 @@
-/** Método de pago de la venta. */
+/** Medio de pago de `payments[].method` en la venta. */
 export enum RetailPaymentMethodEnum {
     CASH = 'CASH',
     CARD = 'CARD',
-    SPEI = 'SPEI',
+    WIRE = 'WIRE',
+    FIADO = 'FIADO',
 }

package/src/retailIntegration/enums/index.ts

@@ -18,6 +18,7 @@ export * from './RetailUserAccessStatusEnum';
 export * from './RetailSaleTypeEnum';
 export * from './RetailSaleFinancierEnum';
 export * from './RetailPaymentMethodEnum';
+export * from './RetailPaymentFrequencyEnum';
 export * from './RetailLinePaymentTypeEnum';
 export * from './RetailSaleLineRoleEnum';
 export * from './RetailEventRejectCodeEnum';

package/src/retailIntegration/index.ts

@@ -3,6 +3,8 @@ export * from './constants/retailIntegrationErrorHttpStatus';
 export * from './enums';
 export * from './validators/IsIsoDateTimeWithZone';
 export * from './validators/IsMovementsRangeValid';
+export * from './validators/IsCalendarDate';
+export * from './validators/saleValidators';
 export * from './dtos/RetailEventEnvelope';
 export * from './dtos/ReceiveStoreEventRequest';
 export * from './dtos/ReceiveRetailUserEventRequest';

package/src/retailIntegration/models/RetailSystemSale.ts

@@ -1,23 +1,66 @@
 import { Type } from 'class-transformer';
 import { ArrayNotEmpty, IsArray, IsIn, IsInt, IsObject, IsString, Matches, Min, Validate, ValidateIf, ValidateNested } from 'class-validator';
-import { RETAIL_DECIMAL_PATTERN, RETAIL_ENTITY_ID_PATTERN, RETAIL_SKU_PATTERN } from '../constants/retailIntegrationLimits';
-import { RetailCurrencyEnum, RetailLinePaymentTypeEnum, RetailPaymentMethodEnum, RetailSaleFinancierEnum, RetailSaleLineRoleEnum, RetailSaleTypeEnum } from '../enums';
+import {
+    RETAIL_CARD_LAST4_PATTERN,
+    RETAIL_CLABE_PATTERN,
+    RETAIL_CUSTOMER_PHONE_PATTERN,
+    RETAIL_ENTITY_ID_PATTERN,
+    RETAIL_SALE_DECIMAL_PATTERN,
+    RETAIL_SALE_ID_TEXT_PATTERN,
+    RETAIL_SALE_POSITIVE_DECIMAL_PATTERN,
+    RETAIL_SKU_PATTERN,
+    RETAIL_SPEI_TRACKING_KEY_PATTERN,
+} from '../constants/retailIntegrationLimits';
+import {
+    RetailCurrencyEnum,
+    RetailLinePaymentTypeEnum,
+    RetailPaymentFrequencyEnum,
+    RetailPaymentMethodEnum,
+    RetailSaleFinancierEnum,
+    RetailSaleLineRoleEnum,
+    RetailSaleTypeEnum,
+} from '../enums';
+import { IsCalendarDate } from '../validators/IsCalendarDate';
 import { IsIsoDateTimeWithZone } from '../validators/IsIsoDateTimeWithZone';
 import { HasUniqueKeys, isNullOrValidated } from '../validators/payloadValidators';
+import { CreditMatchesFinancier, MatchesForPaymentMethod, PaymentsMatchAmountPaid, PromotionIdMatchesRole } from '../validators/saleValidators';
 import { RetailCurrency } from './RetailSystemProduct';
 
 export type RetailSaleType = `${RetailSaleTypeEnum}`;
 export type RetailSaleFinancier = `${RetailSaleFinancierEnum}`;
 export type RetailPaymentMethod = `${RetailPaymentMethodEnum}`;
+export type RetailPaymentFrequency = `${RetailPaymentFrequencyEnum}`;
 export type RetailLinePaymentType = `${RetailLinePaymentTypeEnum}`;
 export type RetailSaleLineRole = `${RetailSaleLineRoleEnum}`;
 
+const { CARD, WIRE } = RetailPaymentMethodEnum;
+
 export class RetailSystemSaleCustomer {
     @IsString() @Matches(/\S/) customerId!: string;
     @IsString() @Matches(/\S/) names!: string;
     @IsString() @Matches(/\S/) paternalLastName!: string;
     @ValidateIf(isNullOrValidated) @IsString() maternalLastName!: string | null;
-    @IsString() @Matches(/\S/) phone!: string;
+    @IsString() @Matches(RETAIL_CUSTOMER_PHONE_PATTERN) phone!: string;
+}
+
+/** Condiciones del crédito; todas obligatorias cuando `credit` no es `null`. */
+export class RetailSystemSaleCredit {
+    @IsIn(Object.values(RetailPaymentFrequencyEnum)) paymentFrequency!: RetailPaymentFrequency;
+    @IsInt() @Min(1) installments!: number;
+    @IsString() @Matches(RETAIL_SALE_DECIMAL_PATTERN) installmentAmount!: string;
+    @IsString() @Matches(RETAIL_SALE_DECIMAL_PATTERN) downPayment!: string;
+    @IsString() @Matches(RETAIL_SALE_DECIMAL_PATTERN) totalToPay!: string;
+    @Validate(IsCalendarDate) firstPaymentDate!: string;
+}
+
+/** Un medio de pago de `amountPaid`; las seis llaves van siempre, en `null` las que no aplican. */
+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, [WIRE, RETAIL_CLABE_PATTERN, true]) senderClabe!: string | null;
 }
 
 export class RetailSystemSaleComponent {
@@ -30,11 +73,12 @@ export class RetailSystemSaleLine {
     @IsString() @Matches(/\S/) lineId!: string;
     @IsString() @Matches(RETAIL_SKU_PATTERN) sku!: string;
     @IsInt() @Min(1) qty!: number;
-    @IsString() @Matches(RETAIL_DECIMAL_PATTERN) basePrice!: string;
-    @IsString() @Matches(RETAIL_DECIMAL_PATTERN) discount!: string;
+    @IsString() @Matches(RETAIL_SALE_DECIMAL_PATTERN) basePrice!: string;
+    @IsString() @Matches(RETAIL_SALE_DECIMAL_PATTERN) discount!: string;
     @IsIn(Object.values(RetailLinePaymentTypeEnum)) paymentType!: RetailLinePaymentType;
-    @IsString() @Matches(RETAIL_DECIMAL_PATTERN) financedAmount!: string;
+    @IsString() @Matches(RETAIL_SALE_DECIMAL_PATTERN) financedAmount!: string;
     @ValidateIf(isNullOrValidated) @IsIn(Object.values(RetailSaleLineRoleEnum)) role!: RetailSaleLineRole | null;
+    @Validate(PromotionIdMatchesRole) promotionId!: string | null;
     @IsArray() @ValidateNested({ each: true }) @Type(() => RetailSystemSaleComponent) components!: RetailSystemSaleComponent[];
 }
 
@@ -46,13 +90,16 @@ export class RetailSystemSale {
     @IsString() @Matches(RETAIL_ENTITY_ID_PATTERN) sellerRetailUserId!: string;
     @Validate(IsIsoDateTimeWithZone) soldAt!: string;
     @IsIn(Object.values(RetailSaleTypeEnum)) saleType!: RetailSaleType;
-    @IsIn(Object.values(RetailSaleFinancierEnum)) financier!: RetailSaleFinancier;
+    @IsIn(Object.values(RetailSaleFinancierEnum)) @Validate(CreditMatchesFinancier) financier!: RetailSaleFinancier;
     @ValidateIf(isNullOrValidated) @IsString() @Matches(/\S/) creditId!: string | null;
+    @ValidateIf(isNullOrValidated) @IsObject() @ValidateNested() @Type(() => RetailSystemSaleCredit) credit!: RetailSystemSaleCredit | null;
     @IsIn(Object.values(RetailCurrencyEnum)) currencyId!: RetailCurrency;
     @IsObject() @ValidateNested() @Type(() => RetailSystemSaleCustomer) customer!: RetailSystemSaleCustomer;
-    @IsString() @Matches(RETAIL_DECIMAL_PATTERN) equipmentPrice!: string;
-    @IsString() @Matches(RETAIL_DECIMAL_PATTERN) amountPaid!: string;
-    @ValidateIf(isNullOrValidated) @IsIn(Object.values(RetailPaymentMethodEnum)) paymentMethod!: RetailPaymentMethod | null;
+    @IsString() @Matches(RETAIL_SALE_DECIMAL_PATTERN) equipmentPrice!: string;
+    @IsString() @Matches(RETAIL_SALE_DECIMAL_PATTERN) amountPaid!: string;
+
+    @IsArray() @ValidateNested({ each: true }) @Type(() => RetailSystemSalePayment) @Validate(PaymentsMatchAmountPaid)
+    payments!: RetailSystemSalePayment[];
 
     @IsArray() @ArrayNotEmpty() @ValidateNested({ each: true }) @Type(() => RetailSystemSaleLine) @Validate(HasUniqueKeys, ['lineId'])
     lines!: RetailSystemSaleLine[];

package/src/retailIntegration/validators/IsCalendarDate.ts

@@ -0,0 +1,16 @@
+import { ValidatorConstraint, ValidatorConstraintInterface } from 'class-validator';
+import { isRealCalendarDate } from './calendarDate';
+
+const CALENDAR_DATE = /^\d{4}-\d{2}-\d{2}$/;
+
+/** Acepta una fecha `YYYY-MM-DD` que exista en el calendario. */
+@ValidatorConstraint({ name: 'isCalendarDate', async: false })
+export class IsCalendarDate implements ValidatorConstraintInterface {
+    validate(value: unknown): boolean {
+        return typeof value === 'string' && CALENDAR_DATE.test(value) && isRealCalendarDate(value);
+    }
+
+    defaultMessage(): string {
+        return 'debe ser una fecha YYYY-MM-DD, por ejemplo 2026-08-21';
+    }
+}

package/src/retailIntegration/validators/IsIsoDateTimeWithZone.ts

@@ -1,13 +1,8 @@
 import { ValidatorConstraint, ValidatorConstraintInterface } from 'class-validator';
+import { isRealCalendarDate } from './calendarDate';
 
 const ISO_DATE_TIME_WITH_ZONE = /^\d{4}-\d{2}-\d{2}T\d{2}:\d{2}:\d{2}(\.\d{1,9})?(Z|[+-]\d{2}:\d{2})$/;
 
-/** Descarta fechas que `Date` recorre en silencio, como el 31 de febrero. */
-function isRealCalendarDate(value: string): boolean {
-    const [year, month, day] = value.slice(0, 10).split('-').map(Number);
-    return !Number.isNaN(Date.parse(value)) && new Date(Date.UTC(year, month - 1, day)).getUTCDate() === day;
-}
-
 /** Acepta fecha y hora ISO-8601 con segundos y zona; sin zona se rechaza, como dice la doc. */
 @ValidatorConstraint({ name: 'isIsoDateTimeWithZone', async: false })
 export class IsIsoDateTimeWithZone implements ValidatorConstraintInterface {

package/src/retailIntegration/validators/calendarDate.ts

@@ -0,0 +1,5 @@
+/** Descarta fechas que `Date` recorre en silencio, como el 31 de febrero; lee los primeros 10 caracteres. */
+export function isRealCalendarDate(value: string): boolean {
+    const [year, month, day] = value.slice(0, 10).split('-').map(Number);
+    return !Number.isNaN(Date.parse(value)) && new Date(Date.UTC(year, month - 1, day)).getUTCDate() === day;
+}

package/src/retailIntegration/validators/saleValidators.ts

@@ -0,0 +1,80 @@
+import { ValidationArguments, ValidatorConstraint, ValidatorConstraintInterface } from 'class-validator';
+import { RETAIL_SALE_DECIMAL_PATTERN, RETAIL_SALE_ID_TEXT_PATTERN, RETAIL_SALE_POSITIVE_DECIMAL_PATTERN } from '../constants/retailIntegrationLimits';
+import { RetailSaleFinancierEnum, RetailSaleLineRoleEnum, RetailSaleTypeEnum } from '../enums';
+
+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`. */
+@ValidatorConstraint({ name: 'matchesForPaymentMethod', async: false })
+export class MatchesForPaymentMethod implements ValidatorConstraintInterface {
+    validate(value: unknown, args: ValidationArguments): boolean {
+        const [method, pattern, nullable] = args.constraints as [string, RegExp, boolean?];
+        if ((args.object as { method?: string }).method !== method) return value === null;
+        if (value === null) return nullable === true;
+        return typeof value === 'string' && pattern.test(value);
+    }
+
+    defaultMessage(args: ValidationArguments): string {
+        return `${args.property} es obligatorio y válido en ${args.constraints[0]} y null en los demás medios`;
+    }
+}
+
+/** La suma de `payments[].amount` es `amountPaid`; con `amountPaid` en `"0.00"` el arreglo va vacío. */
+@ValidatorConstraint({ name: 'paymentsMatchAmountPaid', async: false })
+export class PaymentsMatchAmountPaid implements ValidatorConstraintInterface {
+    validate(value: unknown, args: ValidationArguments): boolean {
+        const amountPaid = (args.object as { amountPaid?: unknown }).amountPaid;
+        if (!Array.isArray(value) || typeof amountPaid !== 'string' || !RETAIL_SALE_DECIMAL_PATTERN.test(amountPaid)) return true;
+        const amounts = value.map((p) => (p as { amount?: unknown })?.amount);
+        if (!amounts.every((a) => typeof a === 'string' && RETAIL_SALE_POSITIVE_DECIMAL_PATTERN.test(a))) return true;
+        const total = (amounts as string[]).reduce((sum, a) => sum + decimalToCents(a), 0);
+        return total === decimalToCents(amountPaid);
+    }
+
+    defaultMessage(): string {
+        return 'la suma de payments[].amount debe ser amountPaid; [] solo si amountPaid es 0.00';
+    }
+}
+
+/** `credit` y `creditId`: obligatorios con `SUREKEEP` y `null` en contado. */
+@ValidatorConstraint({ name: 'creditMatchesFinancier', async: false })
+export class CreditMatchesFinancier implements ValidatorConstraintInterface {
+    validate(value: unknown, args: ValidationArguments): boolean {
+        const { saleType, credit, creditId } = args.object as { saleType?: unknown; credit?: unknown; creditId?: unknown };
+        if (value === RetailSaleFinancierEnum.SUREKEEP) return credit !== null && creditId !== null;
+        if (value === RetailSaleFinancierEnum.NONE || saleType === RetailSaleTypeEnum.CASH) return credit == null && creditId == null;
+        return true;
+    }
+
+    defaultMessage(): string {
+        return 'credit y creditId son obligatorios con SUREKEEP y null en contado';
+    }
+}
+
+/** `promotionId`: texto o `null`, nunca omitido; un regalo siempre lo trae. */
+@ValidatorConstraint({ name: 'promotionIdMatchesRole', async: false })
+export class PromotionIdMatchesRole implements ValidatorConstraintInterface {
+    validate(value: unknown, args: ValidationArguments): boolean {
+        if (value === null) return (args.object as { role?: unknown }).role !== RetailSaleLineRoleEnum.GIFT;
+        return typeof value === 'string' && RETAIL_SALE_ID_TEXT_PATTERN.test(value);
+    }
+
+    defaultMessage(): string {
+        return 'promotionId es texto de 1 a 64 o null, y obligatorio con role GIFT';
+    }
+}
+
+/** Un dañado con `identifier` es una sola pieza: `qty` debe ser 1. */
+@ValidatorConstraint({ name: 'qtyMatchesIdentifier', async: false })
+export class QtyMatchesIdentifier implements ValidatorConstraintInterface {
+    validate(value: unknown, args: ValidationArguments): boolean {
+        const identifier = (args.object as { identifier?: unknown }).identifier;
+        return typeof identifier !== 'string' || value === 1;
+    }
+
+    defaultMessage(): string {
+        return 'qty debe ser 1 cuando viene identifier';
+    }
+}