@fiado/type-kit 3.222.0 → 3.223.0

package/bin/kyc/dtos/responses/KycPersonData.d.ts

@@ -8,4 +8,13 @@ export declare class KycPersonData {
     maternalLastName?: string;
     curp?: string;
     dateOfBirth?: string;
+    /**
+     * Vigencia del documento de identidad (el `expirationDate` que el OCR lee del INE). Aditivo y
+     * opcional: un mensaje viejo sin el campo sigue validando, y un INE cuyo OCR no la resolvió viaja
+     * sin ella.
+     *
+     * Se usa para mostrarle al vendedor con qué documento se verificó al cliente ("INE vigente, vence
+     * 2033"). NO es un gate: quién decide si la identidad es válida es el proveedor, no esta fecha.
+     */
+    documentExpiresAt?: string;
 }

package/bin/kyc/dtos/responses/KycPersonData.js

@@ -49,3 +49,9 @@ __decorate([
     (0, class_validator_1.IsString)(),
     __metadata("design:type", String)
 ], KycPersonData.prototype, "dateOfBirth", void 0);
+__decorate([
+    (0, class_transformer_1.Expose)(),
+    (0, class_validator_1.IsOptional)(),
+    (0, class_validator_1.IsString)(),
+    __metadata("design:type", String)
+], KycPersonData.prototype, "documentExpiresAt", void 0);

package/bin/retailCustomer/dtos/RetailAddress.d.ts

@@ -0,0 +1,42 @@
+/**
+ * Domicilio del cliente Retail tal como lo entrega el OCR del INE (paso 02e de SureKeep F2), ya
+ * normalizado contra `places-business`. **TODOS los campos son opcionales**: el OCR es best-effort y
+ * una credencial puede no traer número exterior, colonia ni CP.
+ *
+ * Cierra TD-014 / TD-ADDRESSBASE-OCR. El campo `address` del upsert-from-kyc apuntaba al `AddressBase`
+ * canónico de Fiado, que exige ~12 campos (`tenantId`, `provider`, `validFrom`, `addressStatus`,
+ * `countryId`, `typeOfAddressId`…) que el OCR NO tiene y que nadie puede inventar en ese boundary.
+ * Consecuencia real: `retail-customer-business` tuvo que redefinir el DTO LOCALMENTE (antipatrón
+ * `DTO_LOCAL`) para no rechazar el payload con 400 VALIDATION_ERROR, y `retail-wizard-business` se
+ * quedó SIN mandar el domicilio — se extraía del INE y se descartaba en el último salto.
+ *
+ * Este DTO es el shape que los dos repos ya usaban de hecho: espeja 1:1 el `addressSchema` de
+ * Dynamoose que realmente se persiste en `RetailCustomer_GT`.
+ *
+ * ⚠️ **NO es el `AddressBase` canónico ni lo reemplaza.** `AddressBase` sigue siendo el domicilio
+ * gobernado de Fiado (`Address_GT`, con vigencias, proveedor y estatus). Este es el espejo ligero que
+ * vive embebido en el ítem del cliente Retail.
+ *
+ * ⚠️ PII: es el domicilio de una persona física. Nunca se loguea.
+ */
+export declare class RetailAddress {
+    /** Etiqueta completa legible, tal como la devuelve el geocoder (equivalente a `Place.Label`). */
+    fullAddress?: string;
+    street?: string;
+    /** Número exterior. */
+    externalNumber?: string;
+    internalNumber?: string;
+    /** Colonia. */
+    neighborhood?: string;
+    /** Ciudad o municipio (el OCR del INE usa uno u otro indistintamente). */
+    city?: string;
+    /** Estado de la República. */
+    state?: string;
+    /** Código postal. */
+    zipCode?: string;
+    country?: string;
+    /** Referencias de ubicación capturadas a mano (el OCR nunca las trae). */
+    reference?: string;
+    lat?: number;
+    lng?: number;
+}

package/bin/retailCustomer/dtos/RetailAddress.js

@@ -0,0 +1,110 @@
+"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.RetailAddress = void 0;
+const class_transformer_1 = require("class-transformer");
+const class_validator_1 = require("class-validator");
+/**
+ * Domicilio del cliente Retail tal como lo entrega el OCR del INE (paso 02e de SureKeep F2), ya
+ * normalizado contra `places-business`. **TODOS los campos son opcionales**: el OCR es best-effort y
+ * una credencial puede no traer número exterior, colonia ni CP.
+ *
+ * Cierra TD-014 / TD-ADDRESSBASE-OCR. El campo `address` del upsert-from-kyc apuntaba al `AddressBase`
+ * canónico de Fiado, que exige ~12 campos (`tenantId`, `provider`, `validFrom`, `addressStatus`,
+ * `countryId`, `typeOfAddressId`…) que el OCR NO tiene y que nadie puede inventar en ese boundary.
+ * Consecuencia real: `retail-customer-business` tuvo que redefinir el DTO LOCALMENTE (antipatrón
+ * `DTO_LOCAL`) para no rechazar el payload con 400 VALIDATION_ERROR, y `retail-wizard-business` se
+ * quedó SIN mandar el domicilio — se extraía del INE y se descartaba en el último salto.
+ *
+ * Este DTO es el shape que los dos repos ya usaban de hecho: espeja 1:1 el `addressSchema` de
+ * Dynamoose que realmente se persiste en `RetailCustomer_GT`.
+ *
+ * ⚠️ **NO es el `AddressBase` canónico ni lo reemplaza.** `AddressBase` sigue siendo el domicilio
+ * gobernado de Fiado (`Address_GT`, con vigencias, proveedor y estatus). Este es el espejo ligero que
+ * vive embebido en el ítem del cliente Retail.
+ *
+ * ⚠️ PII: es el domicilio de una persona física. Nunca se loguea.
+ */
+class RetailAddress {
+}
+exports.RetailAddress = RetailAddress;
+__decorate([
+    (0, class_transformer_1.Expose)(),
+    (0, class_validator_1.IsOptional)(),
+    (0, class_validator_1.IsString)(),
+    __metadata("design:type", String)
+], RetailAddress.prototype, "fullAddress", void 0);
+__decorate([
+    (0, class_transformer_1.Expose)(),
+    (0, class_validator_1.IsOptional)(),
+    (0, class_validator_1.IsString)(),
+    __metadata("design:type", String)
+], RetailAddress.prototype, "street", void 0);
+__decorate([
+    (0, class_transformer_1.Expose)(),
+    (0, class_validator_1.IsOptional)(),
+    (0, class_validator_1.IsString)(),
+    __metadata("design:type", String)
+], RetailAddress.prototype, "externalNumber", void 0);
+__decorate([
+    (0, class_transformer_1.Expose)(),
+    (0, class_validator_1.IsOptional)(),
+    (0, class_validator_1.IsString)(),
+    __metadata("design:type", String)
+], RetailAddress.prototype, "internalNumber", void 0);
+__decorate([
+    (0, class_transformer_1.Expose)(),
+    (0, class_validator_1.IsOptional)(),
+    (0, class_validator_1.IsString)(),
+    __metadata("design:type", String)
+], RetailAddress.prototype, "neighborhood", void 0);
+__decorate([
+    (0, class_transformer_1.Expose)(),
+    (0, class_validator_1.IsOptional)(),
+    (0, class_validator_1.IsString)(),
+    __metadata("design:type", String)
+], RetailAddress.prototype, "city", void 0);
+__decorate([
+    (0, class_transformer_1.Expose)(),
+    (0, class_validator_1.IsOptional)(),
+    (0, class_validator_1.IsString)(),
+    __metadata("design:type", String)
+], RetailAddress.prototype, "state", void 0);
+__decorate([
+    (0, class_transformer_1.Expose)(),
+    (0, class_validator_1.IsOptional)(),
+    (0, class_validator_1.IsString)(),
+    __metadata("design:type", String)
+], RetailAddress.prototype, "zipCode", void 0);
+__decorate([
+    (0, class_transformer_1.Expose)(),
+    (0, class_validator_1.IsOptional)(),
+    (0, class_validator_1.IsString)(),
+    __metadata("design:type", String)
+], RetailAddress.prototype, "country", void 0);
+__decorate([
+    (0, class_transformer_1.Expose)(),
+    (0, class_validator_1.IsOptional)(),
+    (0, class_validator_1.IsString)(),
+    __metadata("design:type", String)
+], RetailAddress.prototype, "reference", void 0);
+__decorate([
+    (0, class_transformer_1.Expose)(),
+    (0, class_validator_1.IsOptional)(),
+    (0, class_validator_1.IsNumber)(),
+    __metadata("design:type", Number)
+], RetailAddress.prototype, "lat", void 0);
+__decorate([
+    (0, class_transformer_1.Expose)(),
+    (0, class_validator_1.IsOptional)(),
+    (0, class_validator_1.IsNumber)(),
+    __metadata("design:type", Number)
+], RetailAddress.prototype, "lng", void 0);

package/bin/retailCustomer/dtos/RetailCustomer.d.ts

@@ -1,4 +1,4 @@
-import { AddressBase } from '../../address/dtos/AddressBase';
+import { RetailAddress } from './RetailAddress';
 import { AccountStatusEnum } from '../enums/AccountStatusEnum';
 import { KycModalityEnum } from '../enums/KycModalityEnum';
 import { RetailCustomerStatusEnum } from '../enums/RetailCustomerStatusEnum';
@@ -29,6 +29,8 @@ export declare class RetailCustomer {
     email: string | null;
     /** Fecha de nacimiento (ISO 8601, admite fecha sola); se completa con el OCR del KYC. */
     birthDate?: string;
+    /** Vigencia del documento con el que se verificó la identidad (OCR del INE). Informativo. */
+    documentExpiresAt?: string;
     fiadoDirectoryId: string | null;
     fiadoPeopleId: string | null;
     pcfAccountId: string | null;
@@ -37,7 +39,7 @@ export declare class RetailCustomer {
     accountStatus: AccountStatusEnum | null;
     failReason: string | null;
     welcomeAccredited: boolean;
-    address: AddressBase | null;
+    address: RetailAddress | null;
     addressConfirmed: boolean;
     kycStatus: RetailKycStatusEnum;
     kycModality: KycModalityEnum | null;

package/bin/retailCustomer/dtos/RetailCustomer.js

@@ -13,7 +13,7 @@ exports.RetailCustomer = void 0;
 const class_transformer_1 = require("class-transformer");
 const class_validator_1 = require("class-validator");
 const regex_1 = require("../../helpers/constans/regex");
-const AddressBase_1 = require("../../address/dtos/AddressBase");
+const RetailAddress_1 = require("./RetailAddress");
 const AccountStatusEnum_1 = require("../enums/AccountStatusEnum");
 const KycModalityEnum_1 = require("../enums/KycModalityEnum");
 const RetailCustomerStatusEnum_1 = require("../enums/RetailCustomerStatusEnum");
@@ -94,6 +94,13 @@ __decorate([
     (0, class_validator_1.Matches)(regex_1.regexIso8601Date, { message: 'birthDate debe ser una fecha ISO 8601' }),
     __metadata("design:type", String)
 ], RetailCustomer.prototype, "birthDate", void 0);
+__decorate([
+    (0, class_transformer_1.Expose)(),
+    (0, class_validator_1.IsOptional)(),
+    (0, class_validator_1.IsString)(),
+    (0, class_validator_1.Matches)(regex_1.regexIso8601Date, { message: 'documentExpiresAt debe ser una fecha ISO 8601' }),
+    __metadata("design:type", String)
+], RetailCustomer.prototype, "documentExpiresAt", void 0);
 __decorate([
     (0, class_transformer_1.Expose)(),
     (0, class_validator_1.IsOptional)(),
@@ -145,8 +152,8 @@ __decorate([
     (0, class_transformer_1.Expose)(),
     (0, class_validator_1.IsOptional)(),
     (0, class_validator_1.ValidateNested)(),
-    (0, class_transformer_1.Type)(() => AddressBase_1.AddressBase),
-    __metadata("design:type", AddressBase_1.AddressBase)
+    (0, class_transformer_1.Type)(() => RetailAddress_1.RetailAddress),
+    __metadata("design:type", RetailAddress_1.RetailAddress)
 ], RetailCustomer.prototype, "address", void 0);
 __decorate([
     (0, class_transformer_1.Expose)(),

package/bin/retailCustomer/dtos/requests/UpsertCustomerFromKycRequest.d.ts

@@ -1,4 +1,4 @@
-import { AddressBase } from '../../../address/dtos/AddressBase';
+import { RetailAddress } from '../RetailAddress';
 import { KycModalityEnum } from '../../enums/KycModalityEnum';
 import { RetailKycStatusEnum } from '../../enums/RetailKycStatusEnum';
 /**
@@ -17,6 +17,12 @@ export declare class UpsertCustomerFromKycRequest {
     phone: string;
     curp: string;
     birthDate?: string;
+    /**
+     * Vigencia del documento con el que se verificó la identidad (el `expirationDate` que el OCR lee
+     * del INE). Se guarda para poder decirle al vendedor CON QUÉ documento quedó registrado el cliente.
+     * NO es un gate de nada: quién valida la identidad es el proveedor de KYC.
+     */
+    documentExpiresAt?: string;
     rfc?: string;
     email?: string;
     /** Score de confianza que devuelve Metamap junto con el resultado del KYC (F1 §3.5). */
@@ -36,5 +42,13 @@ export declare class UpsertCustomerFromKycRequest {
     hasActiveMxAccount?: boolean;
     kycStatus: RetailKycStatusEnum;
     kycModality: KycModalityEnum;
-    address?: AddressBase;
+    /**
+     * Domicilio del INE (paso 02e), ya normalizado contra `places-business`. Se persiste embebido en la
+     * MISMA TX del upsert.
+     *
+     * Cierra TD-ADDRESSBASE-OCR: apuntaba al `AddressBase` canónico, que exige ~12 campos que el OCR no
+     * trae — el `@ValidateNested` rechazaba el payload real con 400 VALIDATION_ERROR. `RetailAddress` es
+     * el shape ligero que ambos extremos ya usaban de hecho. Ver el DTO para el detalle.
+     */
+    address?: RetailAddress;
 }

package/bin/retailCustomer/dtos/requests/UpsertCustomerFromKycRequest.js

@@ -13,7 +13,7 @@ exports.UpsertCustomerFromKycRequest = void 0;
 const class_transformer_1 = require("class-transformer");
 const class_validator_1 = require("class-validator");
 const regex_1 = require("../../../helpers/constans/regex");
-const AddressBase_1 = require("../../../address/dtos/AddressBase");
+const RetailAddress_1 = require("../RetailAddress");
 const KycModalityEnum_1 = require("../../enums/KycModalityEnum");
 const RetailKycStatusEnum_1 = require("../../enums/RetailKycStatusEnum");
 /**
@@ -66,6 +66,13 @@ __decorate([
     (0, class_validator_1.Matches)(regex_1.regexIso8601Date, { message: 'birthDate debe ser una fecha ISO 8601' }),
     __metadata("design:type", String)
 ], UpsertCustomerFromKycRequest.prototype, "birthDate", void 0);
+__decorate([
+    (0, class_transformer_1.Expose)(),
+    (0, class_validator_1.IsOptional)(),
+    (0, class_validator_1.IsString)(),
+    (0, class_validator_1.Matches)(regex_1.regexIso8601Date, { message: 'documentExpiresAt debe ser una fecha ISO 8601' }),
+    __metadata("design:type", String)
+], UpsertCustomerFromKycRequest.prototype, "documentExpiresAt", void 0);
 __decorate([
     (0, class_transformer_1.Expose)(),
     (0, class_validator_1.IsOptional)(),
@@ -138,6 +145,6 @@ __decorate([
     (0, class_transformer_1.Expose)(),
     (0, class_validator_1.IsOptional)(),
     (0, class_validator_1.ValidateNested)(),
-    (0, class_transformer_1.Type)(() => AddressBase_1.AddressBase),
-    __metadata("design:type", AddressBase_1.AddressBase)
+    (0, class_transformer_1.Type)(() => RetailAddress_1.RetailAddress),
+    __metadata("design:type", RetailAddress_1.RetailAddress)
 ], UpsertCustomerFromKycRequest.prototype, "address", void 0);

package/bin/retailCustomer/dtos/responses/CustomerResponse.d.ts

@@ -1,11 +1,15 @@
-import { AddressBase } from '../../../address/dtos/AddressBase';
+import { RetailAddress } from '../RetailAddress';
 import { AccountStatusEnum } from '../../enums/AccountStatusEnum';
 import { KycModalityEnum } from '../../enums/KycModalityEnum';
 import { RetailCustomerStatusEnum } from '../../enums/RetailCustomerStatusEnum';
 import { RetailKycStatusEnum } from '../../enums/RetailKycStatusEnum';
 /**
  * Vista de un cliente retail hacia el consumidor (BO / api-invoker). SureKeep Fase 2 — pista Retail.
- * `address` reusa el `AddressBase` canónico de Fiado (ver TD en RetailCustomer.address).
+ *
+ * `address` es el `RetailAddress` ligero — el shape que el lambda REALMENTE persiste. Antes decía
+ * `AddressBase`, y esa mentira de tipos ya había producido un bug silencioso: los consumidores leían
+ * `address.municipality` / `address.region` / `address.postalCode` (campos de `AddressBase`) y en
+ * runtime obtenían `undefined`, porque lo persistido se llama `city` / `state` / `zipCode`.
  */
 export interface CustomerResponse {
     retailCustomerId: string;
@@ -20,6 +24,8 @@ export interface CustomerResponse {
     rfc: string | null;
     email: string | null;
     birthDate: string | null;
+    /** Vigencia del documento de identidad con el que se verificó al cliente (OCR del INE). */
+    documentExpiresAt: string | null;
     fiadoDirectoryId: string | null;
     fiadoPeopleId: string | null;
     pcfAccountId: string | null;
@@ -28,7 +34,7 @@ export interface CustomerResponse {
     accountStatus: AccountStatusEnum | null;
     failReason: string | null;
     welcomeAccredited: boolean;
-    address: AddressBase | null;
+    address: RetailAddress | null;
     addressConfirmed: boolean;
     kycStatus: RetailKycStatusEnum;
     kycModality: KycModalityEnum | null;

package/bin/retailCustomer/index.d.ts

@@ -4,6 +4,7 @@ export * from './enums/KycModalityEnum';
 export * from './enums/KycReviewResultEnum';
 export * from './enums/RetailCustomerStatusEnum';
 export * from './dtos/KycReview';
+export * from './dtos/RetailAddress';
 export * from './dtos/RetailCustomer';
 export * from './dtos/requests/CreateCustomerRequest';
 export * from './dtos/requests/UpsertCustomerFromKycRequest';

package/bin/retailCustomer/index.js

@@ -22,6 +22,7 @@ __exportStar(require("./enums/KycReviewResultEnum"), exports);
 __exportStar(require("./enums/RetailCustomerStatusEnum"), exports);
 // Entidades (planas, con class-validator + @Expose)
 __exportStar(require("./dtos/KycReview"), exports);
+__exportStar(require("./dtos/RetailAddress"), exports);
 __exportStar(require("./dtos/RetailCustomer"), exports);
 // Request DTOs (input validado por endpoint)
 __exportStar(require("./dtos/requests/CreateCustomerRequest"), exports);

package/package.json

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

package/src/kyc/dtos/responses/KycPersonData.ts

@@ -20,4 +20,15 @@ export class KycPersonData {
 
     @Expose() @IsOptional() @IsString()
     dateOfBirth?: string;
+
+    /**
+     * Vigencia del documento de identidad (el `expirationDate` que el OCR lee del INE). Aditivo y
+     * opcional: un mensaje viejo sin el campo sigue validando, y un INE cuyo OCR no la resolvió viaja
+     * sin ella.
+     *
+     * Se usa para mostrarle al vendedor con qué documento se verificó al cliente ("INE vigente, vence
+     * 2033"). NO es un gate: quién decide si la identidad es válida es el proveedor, no esta fecha.
+     */
+    @Expose() @IsOptional() @IsString()
+    documentExpiresAt?: string;
 }

package/src/retailCustomer/dtos/RetailAddress.ts

@@ -0,0 +1,92 @@
+import { Expose } from 'class-transformer';
+import { IsNumber, IsOptional, IsString } from 'class-validator';
+
+/**
+ * Domicilio del cliente Retail tal como lo entrega el OCR del INE (paso 02e de SureKeep F2), ya
+ * normalizado contra `places-business`. **TODOS los campos son opcionales**: el OCR es best-effort y
+ * una credencial puede no traer número exterior, colonia ni CP.
+ *
+ * Cierra TD-014 / TD-ADDRESSBASE-OCR. El campo `address` del upsert-from-kyc apuntaba al `AddressBase`
+ * canónico de Fiado, que exige ~12 campos (`tenantId`, `provider`, `validFrom`, `addressStatus`,
+ * `countryId`, `typeOfAddressId`…) que el OCR NO tiene y que nadie puede inventar en ese boundary.
+ * Consecuencia real: `retail-customer-business` tuvo que redefinir el DTO LOCALMENTE (antipatrón
+ * `DTO_LOCAL`) para no rechazar el payload con 400 VALIDATION_ERROR, y `retail-wizard-business` se
+ * quedó SIN mandar el domicilio — se extraía del INE y se descartaba en el último salto.
+ *
+ * Este DTO es el shape que los dos repos ya usaban de hecho: espeja 1:1 el `addressSchema` de
+ * Dynamoose que realmente se persiste en `RetailCustomer_GT`.
+ *
+ * ⚠️ **NO es el `AddressBase` canónico ni lo reemplaza.** `AddressBase` sigue siendo el domicilio
+ * gobernado de Fiado (`Address_GT`, con vigencias, proveedor y estatus). Este es el espejo ligero que
+ * vive embebido en el ítem del cliente Retail.
+ *
+ * ⚠️ PII: es el domicilio de una persona física. Nunca se loguea.
+ */
+export class RetailAddress {
+    /** Etiqueta completa legible, tal como la devuelve el geocoder (equivalente a `Place.Label`). */
+    @Expose()
+    @IsOptional()
+    @IsString()
+    fullAddress?: string;
+
+    @Expose()
+    @IsOptional()
+    @IsString()
+    street?: string;
+
+    /** Número exterior. */
+    @Expose()
+    @IsOptional()
+    @IsString()
+    externalNumber?: string;
+
+    @Expose()
+    @IsOptional()
+    @IsString()
+    internalNumber?: string;
+
+    /** Colonia. */
+    @Expose()
+    @IsOptional()
+    @IsString()
+    neighborhood?: string;
+
+    /** Ciudad o municipio (el OCR del INE usa uno u otro indistintamente). */
+    @Expose()
+    @IsOptional()
+    @IsString()
+    city?: string;
+
+    /** Estado de la República. */
+    @Expose()
+    @IsOptional()
+    @IsString()
+    state?: string;
+
+    /** Código postal. */
+    @Expose()
+    @IsOptional()
+    @IsString()
+    zipCode?: string;
+
+    @Expose()
+    @IsOptional()
+    @IsString()
+    country?: string;
+
+    /** Referencias de ubicación capturadas a mano (el OCR nunca las trae). */
+    @Expose()
+    @IsOptional()
+    @IsString()
+    reference?: string;
+
+    @Expose()
+    @IsOptional()
+    @IsNumber()
+    lat?: number;
+
+    @Expose()
+    @IsOptional()
+    @IsNumber()
+    lng?: number;
+}

package/src/retailCustomer/dtos/RetailCustomer.ts

@@ -11,7 +11,7 @@ import {
     ValidateNested,
 } from 'class-validator';
 import { regexIso8601, regexIso8601Date } from '../../helpers/constans/regex';
-import { AddressBase } from '../../address/dtos/AddressBase';
+import { RetailAddress } from './RetailAddress';
 import { AccountStatusEnum } from '../enums/AccountStatusEnum';
 import { KycModalityEnum } from '../enums/KycModalityEnum';
 import { RetailCustomerStatusEnum } from '../enums/RetailCustomerStatusEnum';
@@ -85,6 +85,13 @@ export class RetailCustomer {
     @Matches(regexIso8601Date, { message: 'birthDate debe ser una fecha ISO 8601' })
     birthDate?: string;
 
+    /** Vigencia del documento con el que se verificó la identidad (OCR del INE). Informativo. */
+    @Expose()
+    @IsOptional()
+    @IsString()
+    @Matches(regexIso8601Date, { message: 'documentExpiresAt debe ser una fecha ISO 8601' })
+    documentExpiresAt?: string;
+
     @Expose()
     @IsOptional()
     @IsString()
@@ -124,18 +131,22 @@ export class RetailCustomer {
     @IsBoolean()
     welcomeAccredited!: boolean;
 
-    // TD-ADDRESSBASE-OCR: por decisión de Andrés (2026-07) el domicilio reusa el `AddressBase` canónico
-    // de Fiado (`address/dtos/AddressBase`, espejo de Address_GT) tal cual manda el spec (componente 01 +
-    // modelo-datos F2). RIESGO detectado: `AddressBase` tiene ~12 campos requeridos (directoryId, tenantId,
-    // createdBy, typeOfAddressId, typeOfDirectoryId, provider, addressStatus, validFrom, isPrincipal,
-    // helpNeeded, countryId, country) que un domicilio de copia OCR-parcial puede NO llenar → con
-    // @ValidateNested esto puede RECHAZAR en runtime los payloads OCR de kyc/confirm y address/confirm.
-    // Se acepta ahora para apegarse al doc; ajustar después (posible tipo de dirección ligero para captura).
+    // TD-ADDRESSBASE-OCR — CERRADO (2026-07-26) con el "tipo de dirección ligero para captura" que este
+    // mismo comentario dejaba pendiente. El riesgo anotado se materializó: `AddressBase` exige ~12 campos
+    // (directoryId, tenantId, createdBy, typeOfAddressId, typeOfDirectoryId, provider, addressStatus,
+    // validFrom, isPrincipal, helpNeeded, countryId, country) que un domicilio OCR-parcial NO llena, y con
+    // @ValidateNested el payload real del INE se rechazaba con 400 VALIDATION_ERROR. Consecuencias que ya
+    // estaban en producción: `retail-customer-business` redefinió el DTO local (antipatrón DTO_LOCAL) para
+    // poder recibirlo, y `retail-wizard-business` directamente dejó de mandar el domicilio.
+    //
+    // `RetailAddress` es el espejo ligero (todo opcional) del `addressSchema` que se persiste de hecho.
+    // El `AddressBase` canónico sigue siendo el domicilio gobernado de Fiado (Address_GT) — este NO lo
+    // reemplaza, solo deja de mentir sobre lo que vive embebido en el cliente Retail.
     @Expose()
     @IsOptional()
     @ValidateNested()
-    @Type(() => AddressBase)
-    address!: AddressBase | null;
+    @Type(() => RetailAddress)
+    address!: RetailAddress | null;
 
     @Expose()
     @IsBoolean()

package/src/retailCustomer/dtos/requests/UpsertCustomerFromKycRequest.ts

@@ -11,7 +11,7 @@ import {
     ValidateNested,
 } from 'class-validator';
 import { regexCurp, regexIso8601Date, regexPhoneMx } from '../../../helpers/constans/regex';
-import { AddressBase } from '../../../address/dtos/AddressBase';
+import { RetailAddress } from '../RetailAddress';
 import { KycModalityEnum } from '../../enums/KycModalityEnum';
 import { RetailKycStatusEnum } from '../../enums/RetailKycStatusEnum';
 
@@ -63,6 +63,17 @@ export class UpsertCustomerFromKycRequest {
     @Matches(regexIso8601Date, { message: 'birthDate debe ser una fecha ISO 8601' })
     birthDate?: string;
 
+    /**
+     * Vigencia del documento con el que se verificó la identidad (el `expirationDate` que el OCR lee
+     * del INE). Se guarda para poder decirle al vendedor CON QUÉ documento quedó registrado el cliente.
+     * NO es un gate de nada: quién valida la identidad es el proveedor de KYC.
+     */
+    @Expose()
+    @IsOptional()
+    @IsString()
+    @Matches(regexIso8601Date, { message: 'documentExpiresAt debe ser una fecha ISO 8601' })
+    documentExpiresAt?: string;
+
     @Expose()
     @IsOptional()
     @IsString()
@@ -126,12 +137,17 @@ export class UpsertCustomerFromKycRequest {
     @IsEnum(KycModalityEnum)
     kycModality!: KycModalityEnum;
 
-    // TD-ADDRESSBASE-OCR: reusa el `AddressBase` canónico por decisión de Andrés (apego al spec). El OCR
-    // (paso 02e) puede no traer los ~12 campos requeridos de AddressBase → posible rechazo en runtime con
-    // @ValidateNested. Se persiste en la MISMA TX del upsert. Ajustar después (ver RetailCustomer.address).
+    /**
+     * Domicilio del INE (paso 02e), ya normalizado contra `places-business`. Se persiste embebido en la
+     * MISMA TX del upsert.
+     *
+     * Cierra TD-ADDRESSBASE-OCR: apuntaba al `AddressBase` canónico, que exige ~12 campos que el OCR no
+     * trae — el `@ValidateNested` rechazaba el payload real con 400 VALIDATION_ERROR. `RetailAddress` es
+     * el shape ligero que ambos extremos ya usaban de hecho. Ver el DTO para el detalle.
+     */
     @Expose()
     @IsOptional()
     @ValidateNested()
-    @Type(() => AddressBase)
-    address?: AddressBase;
+    @Type(() => RetailAddress)
+    address?: RetailAddress;
 }

package/src/retailCustomer/dtos/responses/CustomerResponse.ts

@@ -1,4 +1,4 @@
-import { AddressBase } from '../../../address/dtos/AddressBase';
+import { RetailAddress } from '../RetailAddress';
 import { AccountStatusEnum } from '../../enums/AccountStatusEnum';
 import { KycModalityEnum } from '../../enums/KycModalityEnum';
 import { RetailCustomerStatusEnum } from '../../enums/RetailCustomerStatusEnum';
@@ -6,7 +6,11 @@ import { RetailKycStatusEnum } from '../../enums/RetailKycStatusEnum';
 
 /**
  * Vista de un cliente retail hacia el consumidor (BO / api-invoker). SureKeep Fase 2 — pista Retail.
- * `address` reusa el `AddressBase` canónico de Fiado (ver TD en RetailCustomer.address).
+ *
+ * `address` es el `RetailAddress` ligero — el shape que el lambda REALMENTE persiste. Antes decía
+ * `AddressBase`, y esa mentira de tipos ya había producido un bug silencioso: los consumidores leían
+ * `address.municipality` / `address.region` / `address.postalCode` (campos de `AddressBase`) y en
+ * runtime obtenían `undefined`, porque lo persistido se llama `city` / `state` / `zipCode`.
  */
 export interface CustomerResponse {
     retailCustomerId: string;
@@ -21,6 +25,8 @@ export interface CustomerResponse {
     rfc: string | null;
     email: string | null;
     birthDate: string | null;
+    /** Vigencia del documento de identidad con el que se verificó al cliente (OCR del INE). */
+    documentExpiresAt: string | null;
     fiadoDirectoryId: string | null;
     fiadoPeopleId: string | null;
     pcfAccountId: string | null;
@@ -29,7 +35,7 @@ export interface CustomerResponse {
     accountStatus: AccountStatusEnum | null;
     failReason: string | null;
     welcomeAccredited: boolean;
-    address: AddressBase | null;
+    address: RetailAddress | null;
     addressConfirmed: boolean;
     kycStatus: RetailKycStatusEnum;
     kycModality: KycModalityEnum | null;

package/src/retailCustomer/index.ts

@@ -7,6 +7,7 @@ export * from './enums/RetailCustomerStatusEnum';
 
 // Entidades (planas, con class-validator + @Expose)
 export * from './dtos/KycReview';
+export * from './dtos/RetailAddress';
 export * from './dtos/RetailCustomer';
 
 // Request DTOs (input validado por endpoint)