@fiado/type-kit 3.550.0 → 3.552.0

package/bin/retailOrg/dtos/requests/LookupRetailUserWalletRequest.d.ts

@@ -0,0 +1,10 @@
+/**
+ * Body de `POST /retailers/{retailerId}/users/wallet-lookup`: busca una wallet PCF por CLABE o por
+ * teléfono, exactamente uno. No escribe nada.
+ */
+export declare class LookupRetailUserWalletRequest {
+    /** CLABE PCF, 18 dígitos. No va a logs completa. */
+    clabe?: string | null;
+    /** Teléfono de México: 10 dígitos, con o sin `+52`; retail-org lo normaliza a E.164. No va a logs completo. */
+    phone?: string | null;
+}

package/bin/retailOrg/dtos/requests/LookupRetailUserWalletRequest.js

@@ -0,0 +1,37 @@
+"use strict";
+var __decorate = (this && this.__decorate) || function (decorators, target, key, desc) {
+    var c = arguments.length, r = c < 3 ? target : desc === null ? desc = Object.getOwnPropertyDescriptor(target, key) : desc, d;
+    if (typeof Reflect === "object" && typeof Reflect.decorate === "function") r = Reflect.decorate(decorators, target, key, desc);
+    else for (var i = decorators.length - 1; i >= 0; i--) if (d = decorators[i]) r = (c < 3 ? d(r) : c > 3 ? d(target, key, r) : d(target, key)) || r;
+    return c > 3 && r && Object.defineProperty(target, key, r), r;
+};
+var __metadata = (this && this.__metadata) || function (k, v) {
+    if (typeof Reflect === "object" && typeof Reflect.metadata === "function") return Reflect.metadata(k, v);
+};
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.LookupRetailUserWalletRequest = void 0;
+const class_transformer_1 = require("class-transformer");
+const class_validator_1 = require("class-validator");
+const IsSingleWalletKeyConstraint_1 = require("../../validators/IsSingleWalletKeyConstraint");
+/**
+ * Body de `POST /retailers/{retailerId}/users/wallet-lookup`: busca una wallet PCF por CLABE o por
+ * teléfono, exactamente uno. No escribe nada.
+ */
+class LookupRetailUserWalletRequest {
+}
+exports.LookupRetailUserWalletRequest = LookupRetailUserWalletRequest;
+__decorate([
+    (0, class_transformer_1.Expose)(),
+    (0, class_validator_1.ValidateIf)((o) => o.clabe != null || o.phone == null),
+    (0, class_validator_1.Validate)(IsSingleWalletKeyConstraint_1.IsSingleWalletKeyConstraint),
+    (0, class_validator_1.IsString)({ message: 'clabe debe ser texto' }),
+    (0, class_validator_1.Matches)(/^\d{18}$/, { message: 'clabe debe tener 18 dígitos' }),
+    __metadata("design:type", String)
+], LookupRetailUserWalletRequest.prototype, "clabe", void 0);
+__decorate([
+    (0, class_transformer_1.Expose)(),
+    (0, class_validator_1.IsOptional)(),
+    (0, class_validator_1.IsString)({ message: 'phone debe ser texto' }),
+    (0, class_validator_1.Matches)(/^(\+52)?\d{10}$/, { message: 'phone debe tener 10 dígitos, con o sin +52' }),
+    __metadata("design:type", String)
+], LookupRetailUserWalletRequest.prototype, "phone", void 0);

package/bin/retailOrg/dtos/responses/LookupRetailUserWalletResponse.d.ts

@@ -0,0 +1,10 @@
+import type { RetailUserWalletLinkMethodEnum } from '../../enums/RetailUserWalletLinkMethodEnum';
+/** Respuesta de `POST /retailers/{retailerId}/users/wallet-lookup`. */
+export interface LookupRetailUserWalletResponse {
+    found: boolean;
+    active: boolean;
+    /** Nombre del titular para que el administrador confirme; `null` si no se encontró. */
+    holderName: string | null;
+    /** Por dónde se buscó. */
+    method: RetailUserWalletLinkMethodEnum;
+}

package/bin/retailOrg/dtos/responses/LookupRetailUserWalletResponse.js

@@ -0,0 +1,2 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });

package/bin/retailOrg/dtos/responses/PrivateRetailUserWalletResponse.d.ts

@@ -0,0 +1,8 @@
+/**
+ * Respuesta de `GET /private/retailers/{retailerId}/users/{retailUserId}/wallet`: la wallet del
+ * vendedor para el motor de comisiones. Ambos `null` si no tiene wallet vinculada.
+ */
+export interface PrivateRetailUserWalletResponse {
+    directoryId: string | null;
+    pcfAccountId: string | null;
+}

package/bin/retailOrg/dtos/responses/PrivateRetailUserWalletResponse.js

@@ -0,0 +1,2 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });

package/bin/retailOrg/enums/RetailUserWalletLinkMethodEnum.d.ts

@@ -0,0 +1,11 @@
+/**
+ * Cómo se encontró la wallet PCF del vendedor.
+ * @enum {string}
+ *
+ * @property {string} CLABE - Por la CLABE PCF capturada en el alta.
+ * @property {string} PHONE - Por el teléfono de su usuario de Fiado.
+ */
+export declare enum RetailUserWalletLinkMethodEnum {
+    CLABE = "CLABE",
+    PHONE = "PHONE"
+}

package/bin/retailOrg/enums/RetailUserWalletLinkMethodEnum.js

@@ -0,0 +1,15 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.RetailUserWalletLinkMethodEnum = void 0;
+/**
+ * Cómo se encontró la wallet PCF del vendedor.
+ * @enum {string}
+ *
+ * @property {string} CLABE - Por la CLABE PCF capturada en el alta.
+ * @property {string} PHONE - Por el teléfono de su usuario de Fiado.
+ */
+var RetailUserWalletLinkMethodEnum;
+(function (RetailUserWalletLinkMethodEnum) {
+    RetailUserWalletLinkMethodEnum["CLABE"] = "CLABE";
+    RetailUserWalletLinkMethodEnum["PHONE"] = "PHONE";
+})(RetailUserWalletLinkMethodEnum || (exports.RetailUserWalletLinkMethodEnum = RetailUserWalletLinkMethodEnum = {}));

package/bin/retailOrg/index.d.ts

@@ -5,6 +5,7 @@ export * from './enums/StoreStatusEnum';
 export * from './enums/RetailUserStatusEnum';
 export * from './enums/EmploymentTypeEnum';
 export * from './enums/CollectorSeniorityEnum';
+export * from './enums/RetailUserWalletLinkMethodEnum';
 export * from './enums/GoalTargetTypeEnum';
 export * from './dtos/GeoLocation';
 export * from './dtos/GoalAmounts';
@@ -18,6 +19,7 @@ export * from './dtos/validation/RetailUserValidationDto';
 export * from './dtos/validation/CollectorValidationDto';
 export * from './dtos/validation/PrivateSellerListResponse';
 export * from './dtos/PaginatedResult';
+export * from './validators/IsSingleWalletKeyConstraint';
 export * from './dtos/requests/RetailAddressInput';
 export * from './dtos/requests/CreateRetailerRequest';
 export * from './dtos/requests/UpdateRetailerRequest';
@@ -34,6 +36,8 @@ export * from './dtos/requests/ProvisionRetailUserRequest';
 export * from './dtos/requests/UpdateRetailUserRequest';
 export * from './dtos/requests/ChangeRetailUserStatusRequest';
 export * from './dtos/requests/TransferRetailUserRequest';
+export * from './dtos/requests/LookupRetailUserWalletRequest';
+export * from './dtos/requests/LinkRetailUserWalletRequest';
 export * from './dtos/requests/GoalListQuery';
 export * from './dtos/requests/GoalUpsertRequest';
 export * from './dtos/requests/GoalPathParams';
@@ -46,3 +50,5 @@ export * from './dtos/responses/GoalUpsertResponse';
 export * from './dtos/responses/PrivateGoalListResponse';
 export * from './dtos/responses/StoreKpiResponse';
 export * from './dtos/responses/SellerKpiResponse';
+export * from './dtos/responses/LookupRetailUserWalletResponse';
+export * from './dtos/responses/PrivateRetailUserWalletResponse';

package/bin/retailOrg/index.js

@@ -21,6 +21,7 @@ __exportStar(require("./enums/StoreStatusEnum"), exports);
 __exportStar(require("./enums/RetailUserStatusEnum"), exports);
 __exportStar(require("./enums/EmploymentTypeEnum"), exports);
 __exportStar(require("./enums/CollectorSeniorityEnum"), exports);
+__exportStar(require("./enums/RetailUserWalletLinkMethodEnum"), exports);
 // F3 — Portal Admin VentasLuga (metas de venta del periodo)
 __exportStar(require("./enums/GoalTargetTypeEnum"), exports);
 // Entity DTOs
@@ -38,6 +39,8 @@ __exportStar(require("./dtos/validation/CollectorValidationDto"), exports);
 __exportStar(require("./dtos/validation/PrivateSellerListResponse"), exports);
 // Paginación genérica
 __exportStar(require("./dtos/PaginatedResult"), exports);
+// Validadores
+__exportStar(require("./validators/IsSingleWalletKeyConstraint"), exports);
 // Request DTOs (input validado por endpoint)
 __exportStar(require("./dtos/requests/RetailAddressInput"), exports);
 __exportStar(require("./dtos/requests/CreateRetailerRequest"), exports);
@@ -55,6 +58,8 @@ __exportStar(require("./dtos/requests/ProvisionRetailUserRequest"), exports);
 __exportStar(require("./dtos/requests/UpdateRetailUserRequest"), exports);
 __exportStar(require("./dtos/requests/ChangeRetailUserStatusRequest"), exports);
 __exportStar(require("./dtos/requests/TransferRetailUserRequest"), exports);
+__exportStar(require("./dtos/requests/LookupRetailUserWalletRequest"), exports);
+__exportStar(require("./dtos/requests/LinkRetailUserWalletRequest"), exports);
 // F3 — metas y KPIs del Portal Admin VL
 __exportStar(require("./dtos/requests/GoalListQuery"), exports);
 __exportStar(require("./dtos/requests/GoalUpsertRequest"), exports);
@@ -69,3 +74,5 @@ __exportStar(require("./dtos/responses/GoalUpsertResponse"), exports);
 __exportStar(require("./dtos/responses/PrivateGoalListResponse"), exports);
 __exportStar(require("./dtos/responses/StoreKpiResponse"), exports);
 __exportStar(require("./dtos/responses/SellerKpiResponse"), exports);
+__exportStar(require("./dtos/responses/LookupRetailUserWalletResponse"), exports);
+__exportStar(require("./dtos/responses/PrivateRetailUserWalletResponse"), exports);

package/bin/retailOrg/validators/IsSingleWalletKeyConstraint.d.ts

@@ -0,0 +1,6 @@
+import { type ValidationArguments, type ValidatorConstraintInterface } from 'class-validator';
+/** Exige exactamente uno de `clabe` o `phone`. */
+export declare class IsSingleWalletKeyConstraint implements ValidatorConstraintInterface {
+    validate(_value: unknown, args: ValidationArguments): boolean;
+    defaultMessage(): string;
+}

package/bin/retailOrg/validators/IsSingleWalletKeyConstraint.js

@@ -0,0 +1,24 @@
+"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.IsSingleWalletKeyConstraint = void 0;
+const class_validator_1 = require("class-validator");
+/** Exige exactamente uno de `clabe` o `phone`. */
+let IsSingleWalletKeyConstraint = class IsSingleWalletKeyConstraint {
+    validate(_value, args) {
+        const o = args.object;
+        return (o.clabe != null) !== (o.phone != null);
+    }
+    defaultMessage() {
+        return 'debe venir clabe o phone, solo uno';
+    }
+};
+exports.IsSingleWalletKeyConstraint = IsSingleWalletKeyConstraint;
+exports.IsSingleWalletKeyConstraint = IsSingleWalletKeyConstraint = __decorate([
+    (0, class_validator_1.ValidatorConstraint)({ name: 'isSingleWalletKey', async: false })
+], IsSingleWalletKeyConstraint);

package/bin/retailPromotions/dtos/responses/WizardSalePromotionResponses.d.ts

@@ -42,7 +42,10 @@ export interface ListStoreSalePromotionsResponse {
 export interface GiftOption {
     sku: string;
     name: string;
-    listPriceCents: number;
+    /** Valor del regalo: su precio de venta. */
+    valueCents?: number;
+    /** @deprecated Usa `valueCents`; trae el mismo valor. */
+    listPriceCents?: number;
     inStock: boolean;
 }
 /** Lo que se entrega al cerrar («Después en la venta»). `quantity`: recargas o meses de garantía. */

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

@@ -8,7 +8,8 @@ export interface SaleLine extends WizardLinePromotionFields {
     sku: string;
     qty: number;
     basePriceCents: number;
-    listPriceCents: number | null;
+    /** @deprecated Ya no se escribe; el valor de un regalo vive en `originalPriceCents`. */
+    listPriceCents?: number | null;
     /** Llave del registro PRICE# del que salió el precio. */
     priceSk: string;
     paymentType: LinePaymentTypeEnum;

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

@@ -1,6 +1,6 @@
 import type { WizardLineRoleEnum } from '../enums/WizardLineRoleEnum';
 import type { WizardReservedLine } from './WizardReservedLine';
-/** Línea GIFT: ligada a un ancla, con su promo y el precio de lista que se regala. */
+/** Línea GIFT: ligada a un ancla, con su promo y el valor del regalo (su precio de venta). */
 export type WizardGiftLine = WizardReservedLine & {
     role: WizardLineRoleEnum.GIFT;
     linkedLineId: string;

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

@@ -11,7 +11,7 @@ export interface WizardLinePromotionFields {
     discountCode?: string;
     /** Descuento total de la línea; neto = basePriceCents × qty − discountCents. */
     discountCents?: number;
-    /** Precio antes del descuento; en un regalo, el valor de lista con la línea a $0. */
+    /** Precio antes del descuento; en un regalo, su precio de venta con la línea a $0. */
     originalPriceCents?: number;
     /** Descuento de cada promo en la línea; sin el campo, la de `promotionId` lleva todo menos el código. */
     promotionDiscounts?: LinePromotionAmount[];

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

@@ -17,7 +17,8 @@ export interface WizardReservedLine extends WizardLinePromotionFields {
     expiresAt: string;
     /** Precio fijado de la línea (el del kit si es kit). */
     basePriceCents: number | null;
-    listPriceCents: number | null;
+    /** @deprecated Ya no se escribe; el valor de un regalo vive en `originalPriceCents`. */
+    listPriceCents?: number | null;
     /** Llave del registro PRICE# del que salió el precio. */
     priceSk: string | null;
     eligibleFinanciers: string[];

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

@@ -23,7 +23,7 @@ export interface SaleCompletedV1 {
      * sin `type` un crédito con $1,300 de enganche era indistinguible de un contado de $1,300.
      */
     type?: SaleTypeEnum;
-    /** Precio de lista del equipo; en contado coincide con `amountCents`. Sin equipo se omite. */
+    /** Precio neto del equipo: su precio de venta menos su descuento. Sin equipo se omite. */
     equipmentPriceCents?: number;
     /** Enganche cobrado (solo `type=CREDIT`). */
     downPaymentCents?: number;

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

@@ -30,7 +30,7 @@ export interface SaleCompletedV2 {
     imei: string | null;
     /** Lo COBRADO en caja. En contado == precio del equipo; en CREDIT es SOLO el enganche. */
     amountCents: number;
-    /** Precio de lista del equipo — la base de comisión. `null` en ventas sin el dato. */
+    /** Precio neto del equipo (venta menos descuento), la base de comisión. `null` sin el dato. */
     equipmentPriceCents: number | null;
     downPaymentCents: number | null;
     creditId: string | null;

package/package.json

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

package/src/retailCatalog/dtos/Product.ts

@@ -28,7 +28,8 @@ export class Product {
     /** `null` = Sin gama. */
     tier!: ProductTierEnum | null;
     basePriceCents!: number;
-    listPriceCents!: number | null;
+    /** @deprecated Ya no se usa; el único precio es `basePriceCents`. */
+    listPriceCents?: number | null;
     eligibleFinanciers!: string[];
     mdmEnabled!: boolean;
     mdmProvider!: MdmProviderEnum | null;

package/src/retailCatalog/dtos/requests/BackofficeCreateSkuPriceRequest.ts

@@ -6,6 +6,7 @@ export class BackofficeCreateSkuPriceRequest {
     @Min(0)
     basePriceCents!: number;
 
+    /** @deprecated Ya no se usa; el único precio es `basePriceCents`. */
     @IsOptional()
     @IsInt()
     @Min(0)

package/src/retailCatalog/dtos/requests/CreateProductRequest.ts

@@ -61,6 +61,7 @@ export class CreateProductRequest {
     @Min(0)
     basePriceCents!: number;
 
+    /** @deprecated Ya no se usa; el único precio es `basePriceCents`. */
     @IsOptional()
     @IsInt()
     @Min(0)

package/src/retailCatalog/dtos/requests/SyncInventoryRequest.ts

@@ -22,6 +22,7 @@ import { ProductComponent } from '../ProductComponent';
 
 /** Precio de un producto en la puerta de entrada; crea PRICE# solo si cambió el monto. */
 export class SyncPrice {
+    /** @deprecated Ya no se usa; el único precio es `basePriceCents`. */
     @IsOptional()
     @IsInt()
     @Min(0)

package/src/retailCatalog/dtos/requests/UpdateProductRequest.ts

@@ -60,6 +60,7 @@ export class UpdateProductRequest {
     @Min(0)
     basePriceCents?: number;
 
+    /** @deprecated Ya no se usa; el único precio es `basePriceCents`. */
     @IsOptional()
     @IsInt()
     @Min(0)

package/src/retailCatalog/dtos/responses/InventoryLensResponse.ts

@@ -69,7 +69,7 @@ export interface InventoryLensSkuItem {
     /** Unidades de este SKU vendidas hoy en esta tienda, **financiadas por SureKeep**. */
     soldTodayUnits: number;
 
-    /** Precio de contado en centavos (`listPriceCents`, o `basePriceCents` si no hay lista). */
+    /** Precio de contado en centavos (`basePriceCents`). */
     cashPriceCents: number;
 }
 

package/src/retailCatalog/dtos/responses/ReserveStockResponse.ts

@@ -16,7 +16,10 @@ export interface ReservedComponent {
 export interface ReserveStockResponse {
     expiresAt: string;
     basePriceCents: number;
-    listPriceCents: number | null;
+    /** @deprecated Usa `giftValueCents`; en reservas GIFT trae el mismo valor, en las demás `null`. */
+    listPriceCents?: number | null;
+    /** Solo en reservas `purpose: GIFT`: valor del regalo, su precio de venta. */
+    giftValueCents?: number;
     /** Llave del registro PRICE# del que salió el precio fijado. */
     priceSk: string;
     eligibleFinanciers: string[];

package/src/retailCatalog/dtos/responses/SkuPriceEntry.ts

@@ -3,7 +3,8 @@ import type { PriceSourceEnum } from '../../enums/PriceSourceEnum';
 /** Un registro del historial de precios PRICE# de un SKU. */
 export interface SkuPriceEntry {
     effectiveFrom: string;
-    listPriceCents: number | null;
+    /** @deprecated Ya no se usa; el único precio es `basePriceCents`. */
+    listPriceCents?: number | null;
     basePriceCents: number;
     source: PriceSourceEnum;
     createdBy: string;

package/src/retailCatalog/dtos/responses/StoreCatalogItem.ts

@@ -38,7 +38,7 @@ export interface StoreCatalogItem {
     itemType?: ItemTypeEnum;
     /** Nombre visible para kits y servicios, que no tienen marca/modelo. */
     description?: string;
-    /** Precio de lista de respaldo para un regalo: el precio vigente o, si no hay, product.basePriceCents. */
+    /** @deprecated Ya no se usa; el valor de un regalo es `basePriceCents`. */
     listPriceCents?: number;
     /** Prioridad de venta de 0 a 100; «Recomendados» ordena por ella. */
     salePriority?: number;

package/src/retailCommission/dtos/CommissionApi.ts

@@ -23,8 +23,16 @@ import type {
     CommissionRuleScope,
     CommissionRuleSetSnapshot,
 } from './CommissionRule';
+import type {
+    CommissionChainStatement,
+    CommissionLedgerMovement,
+    CommissionPayment,
+    CommissionSellerBalance,
+} from './CommissionLedger';
 import type { CommissionWindowEnum } from '../enums/CommissionWindowEnum';
+import type { CommissionBillingPeriodEnum } from '../enums/CommissionBillingPeriodEnum';
 import type { CommissionCountByEnum } from '../enums/CommissionCountByEnum';
+import type { CommissionPayTimingEnum } from '../enums/CommissionPayTimingEnum';
 import type { CommissionAggregateByEnum } from '../enums/CommissionAggregateByEnum';
 import type { CommissionSeriesByEnum } from '../enums/CommissionSeriesByEnum';
 import type { CommissionAccrualStatusEnum } from '../enums/CommissionAccrualStatusEnum';
@@ -254,6 +262,8 @@ export interface CommissionRuleInput {
     replacesOthers: boolean;
     /** Si la regla cuenta piezas o ventas. Ausente = `PIECE`. */
     countBy?: CommissionCountByEnum;
+    /** Cuándo se paga lo que gana. Ausente = `ON_CUT`. */
+    payTiming?: CommissionPayTimingEnum;
 }
 
 /** `POST /backoffice/commissions/rules` — la regla nace en borrador. */
@@ -297,10 +307,12 @@ export interface GetPoliciesResponse {
     policies: CommissionPolicies;
 }
 
-/** `PUT /backoffice/commissions/policies` — las dos políticas se guardan juntas. */
+/** `PUT /backoffice/commissions/policies` — las políticas se guardan juntas. */
 export interface UpdatePoliciesRequest {
     clawback: { cancelacionDias: number; devolucionDias: number; npiM30Dias: number };
     commissions: { multiplicadorMaxBps: number; ventanaDefault: CommissionWindowEnum };
+    /** Opcional para que un editor que todavía no la manda siga funcionando. */
+    payouts?: { walletDeposits: boolean; chainBillingPeriod: CommissionBillingPeriodEnum };
 }
 
 export interface UpdatePoliciesResponse {
@@ -452,6 +464,8 @@ export interface CommissionRuleView {
     effectiveTo: string | null;
     /** Si la regla cuenta piezas o ventas. Ausente = `PIECE`. */
     countBy?: CommissionCountByEnum;
+    /** Cuándo se paga lo que gana. Ausente = `ON_CUT`. */
+    payTiming?: CommissionPayTimingEnum;
 }
 
 /** Lo pagado en varios cortes. */
@@ -482,3 +496,85 @@ export interface GetMyCommissionsResponse {
     /** Tope del multiplicador de la política; `null` sin política. */
     multiplierCapBps: number | null;
 }
+
+// ─────────────────────────────────────────────────────────────────────────────
+// Pagos a la wallet
+// ─────────────────────────────────────────────────────────────────────────────
+
+/** `GET /backoffice/commissions/payments/attention` — el reporte "Por pagar" de la cadena. */
+export interface GetPaymentAttentionResponse {
+    /** Saldos con exigible sin depositar, con su motivo. */
+    pending: CommissionSellerBalance[];
+    /** Depósitos sin confirmar: "Requiere revisión". */
+    unverified: CommissionPayment[];
+    /** Saldos con exigible negativo. */
+    debts: CommissionSellerBalance[];
+}
+
+/** `POST /backoffice/commissions/payments/sellers/{sellerId}/paid-outside` */
+export interface MarkPaidOutsideRequest {
+    amountCents: number;
+    /** Obligatorio: dinero que sale sin depósito tiene que poder auditarse. */
+    reason: string;
+}
+
+/** `POST /backoffice/commissions/payments/{paymentId}/resolve` — revisión de un depósito sin confirmar. */
+export interface ResolvePaymentRequest {
+    /** `true` = sí se depositó; `false` = no, y el monto vuelve al exigible. */
+    accredited: boolean;
+    /** El folio, cuando sí se depositó. */
+    transactionId?: string;
+    note: string;
+}
+
+/** `GET /backoffice/commissions/sellers/{sellerId}/ledger` — saldo e historial de un vendedor. */
+export interface GetSellerLedgerResponse {
+    balance: CommissionSellerBalance;
+    movements: CommissionLedgerMovement[];
+    payments: CommissionPayment[];
+}
+
+/** `GET /backoffice/commissions/statements` */
+export interface ListStatementsResponse {
+    statements: CommissionChainStatement[];
+}
+
+/** `GET /backoffice/commissions/statements/{statementId}` — el estado de cuenta y sus depósitos. */
+export interface GetStatementResponse {
+    statement: CommissionChainStatement;
+    payments: CommissionPayment[];
+}
+
+/** `GET /commissions/me/payments` — los pagos del vendedor que llama. */
+export interface GetMyPaymentsResponse {
+    /** `null` mientras no tiene nada en el libro. */
+    balance: CommissionSellerBalance | null;
+    payments: CommissionPayment[];
+}
+
+/** `POST /backoffice/commissions/payments/sellers/{sellerId}/retry` (202) — el pago quedó en la cola. */
+export interface RetrySellerPaymentView {
+    sellerId: string;
+    /** Id del disparo `RETRY` con que se encoló. */
+    triggerId: string;
+}
+
+/** `POST /backoffice/commissions/payments/sellers/{sellerId}/paid-outside` (201) — el saldo nuevo y el movimiento escrito. */
+export interface MarkPaidOutsideView {
+    balance: CommissionSellerBalance;
+    movement: CommissionLedgerMovement;
+}
+
+/** `POST /backoffice/commissions/payments/{paymentId}/resolve` — el depósito ya resuelto. */
+export interface ResolvePaymentView {
+    payment: CommissionPayment;
+}
+
+/**
+ * `POST /private/retailers/{retailerId}/sellers/{sellerId}/payments/trigger?tenantId=` (202) — retail-org
+ * avisa que el vendedor vinculó su wallet. El cuerpo va vacío (`{}`).
+ */
+export interface PrivateTriggerSellerPaymentResponse {
+    /** `false` si la cola no lo recibió: el saldo sigue pendiente y entra en el siguiente pago. */
+    enqueued: boolean;
+}

package/src/retailCommission/dtos/CommissionLedger.ts

@@ -0,0 +1,101 @@
+import type { CommissionBillingPeriodEnum } from '../enums/CommissionBillingPeriodEnum';
+import type { CommissionLedgerMovementKindEnum } from '../enums/CommissionLedgerMovementKindEnum';
+import type { CommissionPayTimingEnum } from '../enums/CommissionPayTimingEnum';
+import type { CommissionPaymentAttentionEnum } from '../enums/CommissionPaymentAttentionEnum';
+import type { CommissionPaymentStatusEnum } from '../enums/CommissionPaymentStatusEnum';
+
+/**
+ * Saldo de un vendedor en una cadena. Es parte del libro de pagos: cada peso que se le acredita, se
+ * le descuenta o se le deposita en su wallet. Montos en centavos; fechas en ISO.
+ */
+export interface CommissionSellerBalance {
+    retailerId: string;
+    sellerId: string;
+    /** Ganado que todavía no toca pagar (reglas al cierre del mes). */
+    retainedCents: number;
+    /** Lo que se puede depositar ya. Negativo = el vendedor debe. */
+    payableCents: number;
+    /** Apartado para un depósito en curso o sin confirmar. */
+    inTransitCents: number;
+    /** Acumulado de todo lo ganado. */
+    earnedCents: number;
+    /** Acumulado de todo lo descontado. */
+    deductedCents: number;
+    /** Acumulado de lo depositado y confirmado. */
+    accreditedCents: number;
+    /** Acumulado de lo pagado por fuera. */
+    paidOutsideCents: number;
+    /** `null` si no necesita atención. */
+    attention: CommissionPaymentAttentionEnum | null;
+    /** Código del último rechazo, p. ej. `USER_NOT_ACTIVE`. */
+    attentionCode: string | null;
+    /** Desde cuándo tiene esa atención. */
+    attentionSince: string | null;
+    updatedAt: string;
+}
+
+/** Lo que una regla aporta a un movimiento. */
+export interface CommissionLedgerMovementRule {
+    ruleId: string;
+    payTiming: CommissionPayTimingEnum;
+    cents: number;
+}
+
+/** Un movimiento del libro. Nunca cambia. */
+export interface CommissionLedgerMovement {
+    /** Determinista por origen: una reentrega no duplica el movimiento. */
+    movementKey: string;
+    kind: CommissionLedgerMovementKindEnum;
+    periodId: string;
+    retainedDeltaCents: number;
+    payableDeltaCents: number;
+    byRule: CommissionLedgerMovementRule[];
+    saleId: string | null;
+    adjustmentId: string | null;
+    /** `YYYY-MM` de la liberación mensual. */
+    releaseMonth: string | null;
+    /** Obligatorio en lo pagado por fuera. */
+    reason: string | null;
+    createdAt: string;
+    createdBy: string;
+}
+
+/** Un depósito a la wallet del vendedor. Solo cambia su estado. */
+export interface CommissionPayment {
+    /** También es la llave de idempotencia del depósito. */
+    paymentId: string;
+    retailerId: string;
+    sellerId: string;
+    amountCents: number;
+    status: CommissionPaymentStatusEnum;
+    /** La wallet a la que se depositó. */
+    directoryId: string;
+    /** Folio del depósito; `null` mientras no se confirma. */
+    transactionId: string | null;
+    errorCode: string | null;
+    /** Lo que ve el vendedor en su wallet; máximo 120 caracteres. */
+    concept: string;
+    requestedAt: string;
+    resolvedAt: string | null;
+    resolvedBy: string | null;
+    /** Nota de quien lo revisó a mano. */
+    note: string | null;
+}
+
+/**
+ * Estado de cuenta para cobrarle a la cadena: los depósitos confirmados del periodo. Lo pagado por
+ * fuera no entra. Se genera una vez y no cambia.
+ */
+export interface CommissionChainStatement {
+    statementId: string;
+    retailerId: string;
+    period: CommissionBillingPeriodEnum;
+    /** `YYYY-MM-DD`, inclusive. */
+    startDate: string;
+    /** `YYYY-MM-DD`, inclusive. */
+    endDate: string;
+    accreditedCents: number;
+    paymentsCount: number;
+    sellersCount: number;
+    generatedAt: string;
+}