@fiado/type-kit 3.550.0 → 3.551.0

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;
+}

package/src/retailCommission/dtos/CommissionRule.ts

@@ -1,9 +1,11 @@
 import type { ProductCategoryEnum } from '../../retailCatalog/enums/ProductCategoryEnum';
 import type { ProductTierEnum } from '../../retailCatalog/enums/ProductTierEnum';
+import type { CommissionBillingPeriodEnum } from '../enums/CommissionBillingPeriodEnum';
 import type { CommissionBonusModeEnum } from '../enums/CommissionBonusModeEnum';
 import type { CommissionCountByEnum } from '../enums/CommissionCountByEnum';
 import type { CommissionMetricEnum } from '../enums/CommissionMetricEnum';
 import type { CommissionOperatorEnum } from '../enums/CommissionOperatorEnum';
+import type { CommissionPayTimingEnum } from '../enums/CommissionPayTimingEnum';
 import type { CommissionRuleStatusEnum } from '../enums/CommissionRuleStatusEnum';
 import type { CommissionWindowEnum } from '../enums/CommissionWindowEnum';
 
@@ -84,6 +86,8 @@ export interface CommissionRule {
     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;
     /** Sube en cada guardado. */
     version: number;
     /** La versión que está en el plan vigente. `null` si nunca se publicó. */
@@ -114,10 +118,20 @@ export interface CommissionPolicyCommissions {
     editedAt: string;
 }
 
-/** Políticas de la cadena. Cada una es `null` mientras la cadena no la guarda. */
+/** Política de pagos a la wallet de los vendedores. */
+export interface CommissionPayoutPolicy {
+    /** Depositar las comisiones a la wallet. Apagado, todo se calcula y queda pendiente. */
+    walletDeposits: boolean;
+    /** Cada cuánto se le cobra a la cadena. */
+    chainBillingPeriod: CommissionBillingPeriodEnum;
+}
+
+/** Políticas de la cadena. `clawback` y `commissions` son `null` mientras la cadena no las guarda. */
 export interface CommissionPolicies {
     clawback: CommissionPolicyClawback | null;
     commissions: CommissionPolicyCommissions | null;
+    /** Ausente = depósitos encendidos y cobro semanal. */
+    payouts?: CommissionPayoutPolicy;
 }
 
 /**

package/src/retailCommission/enums/CommissionBillingPeriodEnum.ts

@@ -0,0 +1,10 @@
+/**
+ * Cada cuánto se le cobra a la cadena lo que Fiado depositó a sus vendedores.
+ *
+ * WEEKLY - Semanal. Es el valor cuando la cadena no guardó la política.
+ * MONTHLY - Mensual.
+ */
+export enum CommissionBillingPeriodEnum {
+    WEEKLY = 'WEEKLY',
+    MONTHLY = 'MONTHLY',
+}

package/src/retailCommission/enums/CommissionLedgerMovementKindEnum.ts

@@ -0,0 +1,14 @@
+/**
+ * Tipo de movimiento del libro de pagos. Un movimiento nunca cambia.
+ *
+ * EARN - Ganado: suma al exigible o al retenido.
+ * DEDUCT - Descontado del exigible.
+ * RELEASE - Liberación mensual: pasa de retenido a exigible.
+ * PAID_OUTSIDE - Pagado por fuera de la wallet: sale del exigible sin depósito.
+ */
+export enum CommissionLedgerMovementKindEnum {
+    EARN = 'EARN',
+    DEDUCT = 'DEDUCT',
+    RELEASE = 'RELEASE',
+    PAID_OUTSIDE = 'PAID_OUTSIDE',
+}

package/src/retailCommission/enums/CommissionPayTimingEnum.ts

@@ -0,0 +1,13 @@
+/**
+ * Cuándo se paga lo que gana una regla.
+ *
+ * ON_SALE - Al momento: se vuelve exigible al registrar la venta. Solo para reglas que únicamente
+ *   pagan bono por venta.
+ * ON_CUT - Al cierre de la semana. Es el valor cuando la regla no lo trae.
+ * MONTHLY - Al cierre del mes: se retiene hasta el día 1 del mes siguiente al lunes del corte.
+ */
+export enum CommissionPayTimingEnum {
+    ON_SALE = 'ON_SALE',
+    ON_CUT = 'ON_CUT',
+    MONTHLY = 'MONTHLY',
+}

package/src/retailCommission/enums/CommissionPayTriggerEnum.ts

@@ -0,0 +1,18 @@
+/**
+ * Qué pidió pagarle a un vendedor.
+ *
+ * SALE - Una venta con reglas al momento.
+ * CUT - El cierre del corte.
+ * RELEASE - La liberación mensual.
+ * ADJUSTMENT - Un ajuste manual.
+ * WALLET_LINKED - Se vinculó su wallet.
+ * RETRY - "Reintentar ahora" desde "Por pagar".
+ */
+export enum CommissionPayTriggerEnum {
+    SALE = 'SALE',
+    CUT = 'CUT',
+    RELEASE = 'RELEASE',
+    ADJUSTMENT = 'ADJUSTMENT',
+    WALLET_LINKED = 'WALLET_LINKED',
+    RETRY = 'RETRY',
+}

package/src/retailCommission/enums/CommissionPaymentAttentionEnum.ts

@@ -0,0 +1,14 @@
+/**
+ * Por qué el saldo de un vendedor aparece en "Por pagar".
+ *
+ * NO_WALLET - No tiene wallet vinculada.
+ * REJECTED - Su último depósito se rechazó (cuenta bloqueada, tope de nivel...); el código va aparte.
+ * PAUSED - La cadena apagó los depósitos a la wallet.
+ * DEBT - Su exigible es negativo: debe.
+ */
+export enum CommissionPaymentAttentionEnum {
+    NO_WALLET = 'NO_WALLET',
+    REJECTED = 'REJECTED',
+    PAUSED = 'PAUSED',
+    DEBT = 'DEBT',
+}

package/src/retailCommission/enums/CommissionPaymentStatusEnum.ts

@@ -0,0 +1,14 @@
+/**
+ * Estado de un depósito de comisiones a la wallet del vendedor.
+ *
+ * PENDING - El monto se apartó y el depósito está en curso.
+ * ACCREDITED - Depositado, con folio.
+ * FAILED - Rechazado sin mover dinero: el monto vuelve al exigible.
+ * UNVERIFIED - Resultado ambiguo: el monto sigue apartado y no se reintenta solo; alguien lo revisa.
+ */
+export enum CommissionPaymentStatusEnum {
+    PENDING = 'PENDING',
+    ACCREDITED = 'ACCREDITED',
+    FAILED = 'FAILED',
+    UNVERIFIED = 'UNVERIFIED',
+}

package/src/retailCommission/index.ts

@@ -21,6 +21,12 @@ export * from './enums/CommissionCountByEnum';
 export * from './enums/CommissionAggregateByEnum';
 export * from './enums/CommissionSeriesByEnum';
 export * from './enums/CommissionSimulationSkipEnum';
+export * from './enums/CommissionPayTimingEnum';
+export * from './enums/CommissionBillingPeriodEnum';
+export * from './enums/CommissionPaymentStatusEnum';
+export * from './enums/CommissionPaymentAttentionEnum';
+export * from './enums/CommissionLedgerMovementKindEnum';
+export * from './enums/CommissionPayTriggerEnum';
 
 // Entidades del dominio
 export * from './dtos/CommissionPlan';
@@ -29,6 +35,7 @@ export * from './dtos/CommissionCouponAccrual';
 export * from './dtos/CommissionCalcTrace';
 export * from './dtos/CommissionAccrual';
 export * from './dtos/CommissionPayout';
+export * from './dtos/CommissionLedger';
 
 // Contratos HTTP — uno por endpoint
 export * from './dtos/CommissionApi';

package/src/retailOrg/dtos/RetailUser.ts

@@ -4,6 +4,7 @@ import { regexIso8601 } from '../../helpers/constans/regex';
 import { CollectorSeniorityEnum } from '../enums/CollectorSeniorityEnum';
 import { EmploymentTypeEnum } from '../enums/EmploymentTypeEnum';
 import { RetailUserStatusEnum } from '../enums/RetailUserStatusEnum';
+import { RetailUserWalletLinkMethodEnum } from '../enums/RetailUserWalletLinkMethodEnum';
 
 /**
  * RetailUser — usuario retail (empleado de tienda) de un retailer (SureKeep Fase 1 — pista Retail).
@@ -74,6 +75,44 @@ export class RetailUser {
     @IsEnum(RetailUserStatusEnum)
     status!: RetailUserStatusEnum;
 
+    /** Directorio de Fiado del dueño de la wallet PCF; `null` o ausente si no tiene wallet. */
+    @Expose()
+    @IsOptional()
+    @IsString()
+    fiadoDirectoryId?: string | null;
+
+    /** Cuenta PCF de la wallet. */
+    @Expose()
+    @IsOptional()
+    @IsString()
+    pcfAccountId?: string | null;
+
+    /** Cómo se encontró la wallet: por CLABE o por teléfono. */
+    @Expose()
+    @IsOptional()
+    @IsEnum(RetailUserWalletLinkMethodEnum)
+    walletLinkMethod?: RetailUserWalletLinkMethodEnum | null;
+
+    /** Últimos 4 dígitos de la CLABE; la CLABE completa no se guarda. */
+    @Expose()
+    @IsOptional()
+    @IsString()
+    @Matches(/^\d{4}$/, { message: 'walletClabeLast4 debe tener 4 dígitos' })
+    walletClabeLast4?: string | null;
+
+    /** Cuándo se vinculó (ISO). */
+    @Expose()
+    @IsOptional()
+    @IsString()
+    @Matches(regexIso8601, { message: 'walletLinkedAt debe ser una fecha ISO 8601' })
+    walletLinkedAt?: string | null;
+
+    /** Quién la vinculó: el actorId del usuario del back office. */
+    @Expose()
+    @IsOptional()
+    @IsString()
+    walletLinkedBy?: string | null;
+
     @Expose()
     @IsString()
     @Matches(regexIso8601, { message: 'createdAt debe ser una fecha ISO 8601' })

package/src/retailOrg/dtos/requests/LinkRetailUserWalletRequest.ts

@@ -0,0 +1,24 @@
+import { Expose } from 'class-transformer';
+import { IsOptional, IsString, Matches, Validate, ValidateIf } from 'class-validator';
+import { IsSingleWalletKeyConstraint } from '../../validators/IsSingleWalletKeyConstraint';
+
+/**
+ * Body de `PUT /retailers/{retailerId}/users/{retailUserId}/wallet`: vincula la wallet PCF del
+ * vendedor por CLABE o por teléfono, exactamente uno. El servidor vuelve a resolver la cuenta.
+ */
+export class LinkRetailUserWalletRequest {
+    /** CLABE PCF, 18 dígitos. Solo se guardan los últimos 4; no va a logs completa. */
+    @Expose()
+    @ValidateIf((o: LinkRetailUserWalletRequest) => o.clabe != null || o.phone == null)
+    @Validate(IsSingleWalletKeyConstraint)
+    @IsString({ message: 'clabe debe ser texto' })
+    @Matches(/^\d{18}$/, { message: 'clabe debe tener 18 dígitos' })
+    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. */
+    @Expose()
+    @IsOptional()
+    @IsString({ message: 'phone debe ser texto' })
+    @Matches(/^(\+52)?\d{10}$/, { message: 'phone debe tener 10 dígitos, con o sin +52' })
+    phone?: string | null;
+}

package/src/retailOrg/dtos/requests/LookupRetailUserWalletRequest.ts

@@ -0,0 +1,24 @@
+import { Expose } from 'class-transformer';
+import { IsOptional, IsString, Matches, Validate, ValidateIf } from 'class-validator';
+import { IsSingleWalletKeyConstraint } from '../../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.
+ */
+export class LookupRetailUserWalletRequest {
+    /** CLABE PCF, 18 dígitos. No va a logs completa. */
+    @Expose()
+    @ValidateIf((o: LookupRetailUserWalletRequest) => o.clabe != null || o.phone == null)
+    @Validate(IsSingleWalletKeyConstraint)
+    @IsString({ message: 'clabe debe ser texto' })
+    @Matches(/^\d{18}$/, { message: 'clabe debe tener 18 dígitos' })
+    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. */
+    @Expose()
+    @IsOptional()
+    @IsString({ message: 'phone debe ser texto' })
+    @Matches(/^(\+52)?\d{10}$/, { message: 'phone debe tener 10 dígitos, con o sin +52' })
+    phone?: string | null;
+}

package/src/retailOrg/dtos/responses/LookupRetailUserWalletResponse.ts

@@ -0,0 +1,11 @@
+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/src/retailOrg/dtos/responses/PrivateRetailUserWalletResponse.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/src/retailOrg/enums/RetailUserWalletLinkMethodEnum.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 enum RetailUserWalletLinkMethodEnum {
+    CLABE = 'CLABE',
+    PHONE = 'PHONE',
+}

package/src/retailOrg/index.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';
 // F3 — Portal Admin VentasLuga (metas de venta del periodo)
 export * from './enums/GoalTargetTypeEnum';
 
@@ -26,6 +27,9 @@ export * from './dtos/validation/PrivateSellerListResponse';
 // Paginación genérica
 export * from './dtos/PaginatedResult';
 
+// Validadores
+export * from './validators/IsSingleWalletKeyConstraint';
+
 // Request DTOs (input validado por endpoint)
 export * from './dtos/requests/RetailAddressInput';
 export * from './dtos/requests/CreateRetailerRequest';
@@ -43,6 +47,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';
 // F3 — metas y KPIs del Portal Admin VL
 export * from './dtos/requests/GoalListQuery';
 export * from './dtos/requests/GoalUpsertRequest';
@@ -58,3 +64,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/src/retailOrg/validators/IsSingleWalletKeyConstraint.ts

@@ -0,0 +1,18 @@
+import {
+    ValidatorConstraint,
+    type ValidationArguments,
+    type ValidatorConstraintInterface,
+} from 'class-validator';
+
+/** Exige exactamente uno de `clabe` o `phone`. */
+@ValidatorConstraint({ name: 'isSingleWalletKey', async: false })
+export class IsSingleWalletKeyConstraint implements ValidatorConstraintInterface {
+    validate(_value: unknown, args: ValidationArguments): boolean {
+        const o = args.object as { clabe?: unknown; phone?: unknown };
+        return (o.clabe != null) !== (o.phone != null);
+    }
+
+    defaultMessage(): string {
+        return 'debe venir clabe o phone, solo uno';
+    }
+}