@fiado/api-invoker 5.46.0 → 5.48.0

package/bin/datacultrConnector/api/DatacultrConnectorApi.d.ts

@@ -1,7 +1,7 @@
 import type { IHttpRequest } from "@fiado/http-client";
 import { StandardResponse } from "@fiado/gateway-adapter";
-import { DeviceAutoLockScheduleRequest, DeviceAutoLockScheduleResponse, DeviceEnrollInitiateResponse, DeviceEnrollRequest, DeviceEnrollStatusRequest, DeviceEnrollStatusResponse, DeviceLastSeenRequest, DeviceLastSeenResponse, DeviceLockRequest, DeviceLockResponse, DeviceStatusRequest, DeviceStatusResponse, DeviceUnlockRequest, DeviceUnlockResponse } from "@fiado/type-kit/bin/mdm/index.js";
-import { DeviceBatchRequest, DeviceBatchResult, IDatacultrConnectorApi } from "./interfaces/IDatacultrConnectorApi.js";
+import { DeviceAutoLockScheduleRequest, DeviceAutoLockScheduleResponse, DeviceEnrollInitiateResponse, DeviceEnrollRequest, DeviceEnrollStatusRequest, DeviceEnrollStatusResponse, DeviceLastSeenRequest, DeviceLastSeenResponse, DeviceLockRequest, DeviceLockResponse, DeviceNotifyRequest, DeviceNotifyResponse, DevicePinUnlockRequest, DevicePinUnlockResponse, DeviceReleaseInitiateResponse, DeviceReleaseRequest, DeviceReleaseStatusRequest, DeviceReleaseStatusResponse, DeviceStatusRequest, DeviceStatusResponse, DeviceUnlockRequest, DeviceUnlockResponse } from "@fiado/type-kit/bin/mdm/index.js";
+import { DeviceBatchRequest, DeviceBatchResult, DeviceSingleResult, IDatacultrConnectorApi } from "./interfaces/IDatacultrConnectorApi.js";
 /**
  * Publisher HTTP del lambda `datacultr-connector` (provider MDM de SureKeep). Contrato y semántica
  * completos → `IDatacultrConnectorApi` (paths sin prefijo `/private`, sin tenant, `StandardResponse`
@@ -25,4 +25,8 @@ export default class DatacultrConnectorApi implements IDatacultrConnectorApi {
     lockDevices(input: DeviceBatchRequest<DeviceLockRequest>): Promise<StandardResponse<DeviceBatchResult<DeviceLockResponse>>>;
     unlockDevices(input: DeviceBatchRequest<DeviceUnlockRequest>): Promise<StandardResponse<DeviceBatchResult<DeviceUnlockResponse>>>;
     autoLockSchedule(input: DeviceBatchRequest<DeviceAutoLockScheduleRequest>): Promise<StandardResponse<DeviceBatchResult<DeviceAutoLockScheduleResponse>>>;
+    pinUnlock(input: DevicePinUnlockRequest): Promise<StandardResponse<DeviceSingleResult<DevicePinUnlockResponse>>>;
+    notifyDevices(input: DeviceBatchRequest<DeviceNotifyRequest>): Promise<StandardResponse<DeviceBatchResult<DeviceNotifyResponse>>>;
+    releaseDevices(input: DeviceBatchRequest<DeviceReleaseRequest>): Promise<StandardResponse<DeviceBatchResult<DeviceReleaseInitiateResponse>>>;
+    releaseStatus(input: DeviceBatchRequest<DeviceReleaseStatusRequest>): Promise<StandardResponse<DeviceBatchResult<DeviceReleaseStatusResponse>>>;
 }

package/bin/datacultrConnector/api/DatacultrConnectorApi.js

@@ -51,6 +51,18 @@ let DatacultrConnectorApi = class DatacultrConnectorApi {
     async autoLockSchedule(input) {
         return await this.httpRequest.post(`${this.baseUrl}/devices/auto-lock-schedule`, input);
     }
+    async pinUnlock(input) {
+        return await this.httpRequest.post(`${this.baseUrl}/devices/pin-unlock`, input);
+    }
+    async notifyDevices(input) {
+        return await this.httpRequest.post(`${this.baseUrl}/devices/notify`, input);
+    }
+    async releaseDevices(input) {
+        return await this.httpRequest.post(`${this.baseUrl}/devices/release`, input);
+    }
+    async releaseStatus(input) {
+        return await this.httpRequest.post(`${this.baseUrl}/devices/release/status`, input);
+    }
 };
 DatacultrConnectorApi = __decorate([
     injectable(),

package/bin/datacultrConnector/api/interfaces/IDatacultrConnectorApi.d.ts

@@ -1,5 +1,5 @@
 import { StandardResponse } from "@fiado/gateway-adapter";
-import { DeviceAutoLockScheduleRequest, DeviceAutoLockScheduleResponse, DeviceEnrollInitiateResponse, DeviceEnrollRequest, DeviceEnrollStatusRequest, DeviceEnrollStatusResponse, DeviceLastSeenRequest, DeviceLastSeenResponse, DeviceLockRequest, DeviceLockResponse, DeviceStatusRequest, DeviceStatusResponse, DeviceUnlockRequest, DeviceUnlockResponse } from "@fiado/type-kit/bin/mdm/index.js";
+import { DeviceAutoLockScheduleRequest, DeviceAutoLockScheduleResponse, DeviceEnrollInitiateResponse, DeviceEnrollRequest, DeviceEnrollStatusRequest, DeviceEnrollStatusResponse, DeviceLastSeenRequest, DeviceLastSeenResponse, DeviceLockRequest, DeviceLockResponse, DeviceNotifyRequest, DeviceNotifyResponse, DevicePinUnlockRequest, DevicePinUnlockResponse, DeviceReleaseInitiateResponse, DeviceReleaseRequest, DeviceReleaseStatusRequest, DeviceReleaseStatusResponse, DeviceStatusRequest, DeviceStatusResponse, DeviceUnlockRequest, DeviceUnlockResponse } from "@fiado/type-kit/bin/mdm/index.js";
 /**
  * Contrato del publisher HTTP del lambda `datacultr-connector` — el provider MDM que traduce el
  * contrato agnóstico de dispositivo (`@fiado/type-kit/bin/mdm`) a la API de Datacultr. Su consumidor
@@ -58,6 +58,10 @@ export interface DeviceBatchRequest<TItem> {
 export interface DeviceBatchResult<TItem> {
     results: TItem[];
 }
+/** Sobre de salida de los endpoints de UN solo IMEI. Hoy solo `pinUnlock` no es batch. */
+export interface DeviceSingleResult<TItem> {
+    result: TItem;
+}
 export interface IDatacultrConnectorApi {
     /**
      * POST `/devices/enroll` — pre-registra la expectativa de enrolamiento de cada IMEI.
@@ -102,4 +106,30 @@ export interface IDatacultrConnectorApi {
      * Es la vía real del bloqueo en Datacultr: el inmediato no surte efecto, el programado sí.
      */
     autoLockSchedule(input: DeviceBatchRequest<DeviceAutoLockScheduleRequest>): Promise<StandardResponse<DeviceBatchResult<DeviceAutoLockScheduleResponse>>>;
+    /**
+     * POST `/devices/pin-unlock` — pide a Datacultr el passcode de desbloqueo del equipo.
+     *
+     * ⚠️ NO ES BATCH, a diferencia del resto del contrato: recibe UN `DevicePinUnlockRequest` y
+     * devuelve `{ result }`, no `{ results }`. El destino lo declara así en su `PrivateController`.
+     *
+     * Es el camino del "desbloqueo especial" del backoffice: el operador le dicta el PIN al cliente
+     * que se quedó sin señal. `pin`, `validitySeconds` y `generatedAt` solo vienen con `status`
+     * `SUCCESS`; si el proveedor no devolvió passcode, el ítem llega en `ERROR` con su `error.code`.
+     */
+    pinUnlock(input: DevicePinUnlockRequest): Promise<StandardResponse<DeviceSingleResult<DevicePinUnlockResponse>>>;
+    /**
+     * POST `/devices/notify` — manda una notificación al equipo de cada IMEI.
+     *
+     * ⚠️ `notificationCode` es OBLIGATORIO y sale del catálogo de mensajes predefinidos de Datacultr,
+     * que hoy NO tenemos. Sin ese catálogo el caller no puede armar un request válido: pedirlo antes
+     * de construir encima.
+     */
+    notifyDevices(input: DeviceBatchRequest<DeviceNotifyRequest>): Promise<StandardResponse<DeviceBatchResult<DeviceNotifyResponse>>>;
+    /**
+     * POST `/devices/release` — libera definitivamente cada IMEI del MDM (crédito liquidado o
+     * cancelado). Es asíncrono: el ítem suele volver en `PENDING` y se confirma con `releaseStatus`.
+     */
+    releaseDevices(input: DeviceBatchRequest<DeviceReleaseRequest>): Promise<StandardResponse<DeviceBatchResult<DeviceReleaseInitiateResponse>>>;
+    /** POST `/devices/release/status` — consulta en qué punto va la liberación de cada IMEI. */
+    releaseStatus(input: DeviceBatchRequest<DeviceReleaseStatusRequest>): Promise<StandardResponse<DeviceBatchResult<DeviceReleaseStatusResponse>>>;
 }

package/bin/retailCustomer/api/RetailCustomerBusinessApi.d.ts

@@ -1,9 +1,10 @@
 import type { IHttpRequest } from "@fiado/http-client";
 import { StandardResponse } from "@fiado/gateway-adapter";
 import { UpsertCustomerFromKycRequest, AccountResultRequest, CustomerResponse, WelcomeAccreditationRequest, WelcomeAccreditationResponse, WelcomeAccreditationResultRequest, WelcomeBonusResponse } from "@fiado/type-kit/bin/retailCustomer/index.js";
+import { CustomersBatchRequest, CustomersBatchResponse } from "./dtos/CustomersBatch.js";
 import { IRetailCustomerBusinessApi } from "./interfaces/IRetailCustomerBusinessApi.js";
 /**
- * Publisher HTTP del lambda `retail-customer-business` (SureKeep Fase 2, pista Retail) para sus 6
+ * Publisher HTTP del lambda `retail-customer-business` (SureKeep Fase 2, pista Retail) para sus 7
  * endpoints privados de cliente. Contrato y semántica completos → `IRetailCustomerBusinessApi`.
  *
  * Los paths y el `?tenantId=` matchean `openapi/private.yaml` del lambda destino (mismo patrón que
@@ -26,4 +27,5 @@ export default class RetailCustomerBusinessApi implements IRetailCustomerBusines
     getCustomer(customerId: string, tenantId: string): Promise<StandardResponse<CustomerResponse>>;
     markWelcomeAccredited(customerId: string, tenantId: string, payload?: WelcomeAccreditationRequest): Promise<StandardResponse<WelcomeAccreditationResponse>>;
     setWelcomeAccreditationResult(customerId: string, payload: WelcomeAccreditationResultRequest, tenantId: string): Promise<StandardResponse<WelcomeBonusResponse>>;
+    getCustomersBatch(payload: CustomersBatchRequest, tenantId: string): Promise<StandardResponse<CustomersBatchResponse>>;
 }

package/bin/retailCustomer/api/RetailCustomerBusinessApi.js

@@ -12,7 +12,7 @@ var __param = (this && this.__param) || function (paramIndex, decorator) {
 };
 import { inject, injectable } from "inversify";
 /**
- * Publisher HTTP del lambda `retail-customer-business` (SureKeep Fase 2, pista Retail) para sus 6
+ * Publisher HTTP del lambda `retail-customer-business` (SureKeep Fase 2, pista Retail) para sus 7
  * endpoints privados de cliente. Contrato y semántica completos → `IRetailCustomerBusinessApi`.
  *
  * Los paths y el `?tenantId=` matchean `openapi/private.yaml` del lambda destino (mismo patrón que
@@ -56,6 +56,10 @@ let RetailCustomerBusinessApi = class RetailCustomerBusinessApi {
         const url = `${this.baseUrl}/private/customers/${encodeURIComponent(customerId)}/welcome-accreditation/result?tenantId=${encodeURIComponent(tenantId)}`;
         return await this.httpRequest.put(url, payload);
     }
+    async getCustomersBatch(payload, tenantId) {
+        const url = `${this.baseUrl}/private/customers/batch?tenantId=${encodeURIComponent(tenantId)}`;
+        return await this.httpRequest.post(url, payload);
+    }
 };
 RetailCustomerBusinessApi = __decorate([
     injectable(),

package/bin/retailCustomer/api/dtos/CustomersBatch.d.ts

@@ -0,0 +1,23 @@
+/**
+ * Tipos del lote de nombres de cliente. Viven en esta lib (y no en `@fiado/type-kit`) porque el
+ * type-kit todavía no modela esta vista reducida — el lambda destino la tiene como DTO local (TD-029).
+ */
+/** Body de `POST /private/customers/batch`. Hasta 100 ids por request; el caller pagina. */
+export interface CustomersBatchRequest {
+    retailCustomerIds: string[];
+}
+/**
+ * Lo mínimo para pintar un nombre. `fullName: null` significa que el cliente existe pero no tiene
+ * nombre resuelto — es distinto de que el id no vuelva.
+ */
+export interface CustomerBatchItem {
+    retailCustomerId: string;
+    fullName: string | null;
+}
+/**
+ * Los ids que no existen simplemente NO vuelven: `items` puede ser más corto que lo que mandaste.
+ * El caller indexa por `retailCustomerId`, nunca aparea por posición.
+ */
+export interface CustomersBatchResponse {
+    items: CustomerBatchItem[];
+}

package/bin/retailCustomer/api/dtos/CustomersBatch.js

@@ -0,0 +1,5 @@
+/**
+ * Tipos del lote de nombres de cliente. Viven en esta lib (y no en `@fiado/type-kit`) porque el
+ * type-kit todavía no modela esta vista reducida — el lambda destino la tiene como DTO local (TD-029).
+ */
+export {};

package/bin/retailCustomer/api/interfaces/IRetailCustomerBusinessApi.d.ts

@@ -1,15 +1,16 @@
 import { StandardResponse } from "@fiado/gateway-adapter";
 import { UpsertCustomerFromKycRequest, AccountResultRequest, CustomerResponse, WelcomeAccreditationRequest, WelcomeAccreditationResponse, WelcomeAccreditationResultRequest, WelcomeBonusResponse } from "@fiado/type-kit/bin/retailCustomer/index.js";
+import { CustomersBatchRequest, CustomersBatchResponse } from "../dtos/CustomersBatch.js";
 /**
  * Contrato del publisher HTTP del lambda `retail-customer-business` (SureKeep Fase 2, pista Retail)
- * para sus 6 endpoints privados de cliente (service-to-service, VPC-only).
+ * para sus 7 endpoints privados de cliente (service-to-service, VPC-only).
  *
  * Consumidor previsto:
  *   - `retail-wizard-business` → upsert del cliente post-KYC, aterrizaje del resultado de apertura
  *     de cuenta (D35), y lecturas del cliente por teléfono / id durante la saga de venta.
  *
  * ─────────────────────────────────────────────────────────────────────────────
- * `tenantId` es OBLIGATORIO en los 6 métodos — no es un detalle de firma.
+ * `tenantId` es OBLIGATORIO en los 7 métodos — no es un detalle de firma.
  * ─────────────────────────────────────────────────────────────────────────────
  * Los privados NO llevan token de usuario (`Feature.ANONIMUS`; la protección es la red VPC), así que
  * el lambda destino no tiene `AuthContext.issuer` y NO puede inferir el silo. El caller declara el
@@ -114,4 +115,23 @@ export interface IRetailCustomerBusinessApi {
      * @throws `400 WELCOME_BONUS_KEY_INVALID` si el `bonusKey` no decodifica (bug del caller).
      */
     setWelcomeAccreditationResult(customerId: string, payload: WelcomeAccreditationResultRequest, tenantId: string): Promise<StandardResponse<WelcomeBonusResponse>>;
+    /**
+     * POST /private/customers/batch?tenantId= — resuelve NOMBRES de cliente EN LOTE por sus ids.
+     * Pensado para pintar una lista sin caer en N+1 contra el privado de un cliente por vez.
+     *
+     * ⚠️ Un id que NO existe simplemente no aparece en `items`: el arreglo puede volver más corto que
+     * lo que mandaste. Indexa el resultado por `retailCustomerId` — NUNCA aparees por posición.
+     * `fullName: null` es otra cosa: el cliente existe y no tiene nombre resuelto.
+     *
+     * El resultado puede ser PARCIAL si DynamoDB deja claves sin procesar tras sus reintentos: faltan
+     * renglones, no explota. Trata la ausencia como «sin nombre», no como error.
+     *
+     * Tope de 100 ids por request, medido sobre lo que manda el caller (el destino deduplica adentro,
+     * pero eso no baja tu cuenta). Lista vacía → `200` con `items: []`, no es error.
+     *
+     * @throws `400 CUSTOMER_BATCH_TOO_LARGE` si el lote pasa de 100 ids. Reintentar igual vuelve a
+     *   fallar: hay que paginar.
+     * @throws `400 UNKNOWN_TENANT` si el `tenantId` viene ausente o desconocido.
+     */
+    getCustomersBatch(payload: CustomersBatchRequest, tenantId: string): Promise<StandardResponse<CustomersBatchResponse>>;
 }

package/bin/retailCustomer/index.d.ts

@@ -1,2 +1,3 @@
+export * from "./api/dtos/CustomersBatch.js";
 export * from "./api/interfaces/IRetailCustomerBusinessApi.js";
 export { default as RetailCustomerBusinessApi } from "./api/RetailCustomerBusinessApi.js";

package/bin/retailCustomer/index.js

@@ -1,2 +1,3 @@
+export * from "./api/dtos/CustomersBatch.js";
 export * from "./api/interfaces/IRetailCustomerBusinessApi.js";
 export { default as RetailCustomerBusinessApi } from "./api/RetailCustomerBusinessApi.js";

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@fiado/api-invoker",
-  "version": "5.46.0",
+  "version": "5.48.0",
   "description": "Sirve como un puente entre diferentes funciones lambda, facilitando la comunicación entre ellas a través de invocaciones http",
   "type": "module",
   "main": "bin/index.js",

package/src/datacultrConnector/api/DatacultrConnectorApi.ts

@@ -12,6 +12,14 @@ import {
     DeviceLastSeenResponse,
     DeviceLockRequest,
     DeviceLockResponse,
+    DeviceNotifyRequest,
+    DeviceNotifyResponse,
+    DevicePinUnlockRequest,
+    DevicePinUnlockResponse,
+    DeviceReleaseInitiateResponse,
+    DeviceReleaseRequest,
+    DeviceReleaseStatusRequest,
+    DeviceReleaseStatusResponse,
     DeviceStatusRequest,
     DeviceStatusResponse,
     DeviceUnlockRequest,
@@ -20,6 +28,7 @@ import {
 import {
     DeviceBatchRequest,
     DeviceBatchResult,
+    DeviceSingleResult,
     IDatacultrConnectorApi,
 } from "./interfaces/IDatacultrConnectorApi.js";
 
@@ -83,4 +92,28 @@ export default class DatacultrConnectorApi implements IDatacultrConnectorApi {
     ): Promise<StandardResponse<DeviceBatchResult<DeviceAutoLockScheduleResponse>>> {
         return await this.httpRequest.post(`${this.baseUrl}/devices/auto-lock-schedule`, input);
     }
+
+    async pinUnlock(
+        input: DevicePinUnlockRequest,
+    ): Promise<StandardResponse<DeviceSingleResult<DevicePinUnlockResponse>>> {
+        return await this.httpRequest.post(`${this.baseUrl}/devices/pin-unlock`, input);
+    }
+
+    async notifyDevices(
+        input: DeviceBatchRequest<DeviceNotifyRequest>,
+    ): Promise<StandardResponse<DeviceBatchResult<DeviceNotifyResponse>>> {
+        return await this.httpRequest.post(`${this.baseUrl}/devices/notify`, input);
+    }
+
+    async releaseDevices(
+        input: DeviceBatchRequest<DeviceReleaseRequest>,
+    ): Promise<StandardResponse<DeviceBatchResult<DeviceReleaseInitiateResponse>>> {
+        return await this.httpRequest.post(`${this.baseUrl}/devices/release`, input);
+    }
+
+    async releaseStatus(
+        input: DeviceBatchRequest<DeviceReleaseStatusRequest>,
+    ): Promise<StandardResponse<DeviceBatchResult<DeviceReleaseStatusResponse>>> {
+        return await this.httpRequest.post(`${this.baseUrl}/devices/release/status`, input);
+    }
 }

package/src/datacultrConnector/api/interfaces/IDatacultrConnectorApi.ts

@@ -10,6 +10,14 @@ import {
     DeviceLastSeenResponse,
     DeviceLockRequest,
     DeviceLockResponse,
+    DeviceNotifyRequest,
+    DeviceNotifyResponse,
+    DevicePinUnlockRequest,
+    DevicePinUnlockResponse,
+    DeviceReleaseInitiateResponse,
+    DeviceReleaseRequest,
+    DeviceReleaseStatusRequest,
+    DeviceReleaseStatusResponse,
     DeviceStatusRequest,
     DeviceStatusResponse,
     DeviceUnlockRequest,
@@ -77,6 +85,11 @@ export interface DeviceBatchResult<TItem> {
     results: TItem[];
 }
 
+/** Sobre de salida de los endpoints de UN solo IMEI. Hoy solo `pinUnlock` no es batch. */
+export interface DeviceSingleResult<TItem> {
+    result: TItem;
+}
+
 export interface IDatacultrConnectorApi {
     /**
      * POST `/devices/enroll` — pre-registra la expectativa de enrolamiento de cada IMEI.
@@ -141,4 +154,42 @@ export interface IDatacultrConnectorApi {
     autoLockSchedule(
         input: DeviceBatchRequest<DeviceAutoLockScheduleRequest>,
     ): Promise<StandardResponse<DeviceBatchResult<DeviceAutoLockScheduleResponse>>>;
+
+    /**
+     * POST `/devices/pin-unlock` — pide a Datacultr el passcode de desbloqueo del equipo.
+     *
+     * ⚠️ NO ES BATCH, a diferencia del resto del contrato: recibe UN `DevicePinUnlockRequest` y
+     * devuelve `{ result }`, no `{ results }`. El destino lo declara así en su `PrivateController`.
+     *
+     * Es el camino del "desbloqueo especial" del backoffice: el operador le dicta el PIN al cliente
+     * que se quedó sin señal. `pin`, `validitySeconds` y `generatedAt` solo vienen con `status`
+     * `SUCCESS`; si el proveedor no devolvió passcode, el ítem llega en `ERROR` con su `error.code`.
+     */
+    pinUnlock(
+        input: DevicePinUnlockRequest,
+    ): Promise<StandardResponse<DeviceSingleResult<DevicePinUnlockResponse>>>;
+
+    /**
+     * POST `/devices/notify` — manda una notificación al equipo de cada IMEI.
+     *
+     * ⚠️ `notificationCode` es OBLIGATORIO y sale del catálogo de mensajes predefinidos de Datacultr,
+     * que hoy NO tenemos. Sin ese catálogo el caller no puede armar un request válido: pedirlo antes
+     * de construir encima.
+     */
+    notifyDevices(
+        input: DeviceBatchRequest<DeviceNotifyRequest>,
+    ): Promise<StandardResponse<DeviceBatchResult<DeviceNotifyResponse>>>;
+
+    /**
+     * POST `/devices/release` — libera definitivamente cada IMEI del MDM (crédito liquidado o
+     * cancelado). Es asíncrono: el ítem suele volver en `PENDING` y se confirma con `releaseStatus`.
+     */
+    releaseDevices(
+        input: DeviceBatchRequest<DeviceReleaseRequest>,
+    ): Promise<StandardResponse<DeviceBatchResult<DeviceReleaseInitiateResponse>>>;
+
+    /** POST `/devices/release/status` — consulta en qué punto va la liberación de cada IMEI. */
+    releaseStatus(
+        input: DeviceBatchRequest<DeviceReleaseStatusRequest>,
+    ): Promise<StandardResponse<DeviceBatchResult<DeviceReleaseStatusResponse>>>;
 }

package/src/retailCustomer/api/RetailCustomerBusinessApi.ts

@@ -10,10 +10,11 @@ import {
     WelcomeAccreditationResultRequest,
     WelcomeBonusResponse,
 } from "@fiado/type-kit/bin/retailCustomer/index.js";
+import { CustomersBatchRequest, CustomersBatchResponse } from "./dtos/CustomersBatch.js";
 import { IRetailCustomerBusinessApi } from "./interfaces/IRetailCustomerBusinessApi.js";
 
 /**
- * Publisher HTTP del lambda `retail-customer-business` (SureKeep Fase 2, pista Retail) para sus 6
+ * Publisher HTTP del lambda `retail-customer-business` (SureKeep Fase 2, pista Retail) para sus 7
  * endpoints privados de cliente. Contrato y semántica completos → `IRetailCustomerBusinessApi`.
  *
  * Los paths y el `?tenantId=` matchean `openapi/private.yaml` del lambda destino (mismo patrón que
@@ -83,4 +84,12 @@ export default class RetailCustomerBusinessApi implements IRetailCustomerBusines
         const url = `${this.baseUrl}/private/customers/${encodeURIComponent(customerId)}/welcome-accreditation/result?tenantId=${encodeURIComponent(tenantId)}`;
         return await this.httpRequest.put(url, payload);
     }
+
+    async getCustomersBatch(
+        payload: CustomersBatchRequest,
+        tenantId: string,
+    ): Promise<StandardResponse<CustomersBatchResponse>> {
+        const url = `${this.baseUrl}/private/customers/batch?tenantId=${encodeURIComponent(tenantId)}`;
+        return await this.httpRequest.post(url, payload);
+    }
 }

package/src/retailCustomer/api/dtos/CustomersBatch.ts

@@ -0,0 +1,26 @@
+/**
+ * Tipos del lote de nombres de cliente. Viven en esta lib (y no en `@fiado/type-kit`) porque el
+ * type-kit todavía no modela esta vista reducida — el lambda destino la tiene como DTO local (TD-029).
+ */
+
+/** Body de `POST /private/customers/batch`. Hasta 100 ids por request; el caller pagina. */
+export interface CustomersBatchRequest {
+    retailCustomerIds: string[];
+}
+
+/**
+ * Lo mínimo para pintar un nombre. `fullName: null` significa que el cliente existe pero no tiene
+ * nombre resuelto — es distinto de que el id no vuelva.
+ */
+export interface CustomerBatchItem {
+    retailCustomerId: string;
+    fullName: string | null;
+}
+
+/**
+ * Los ids que no existen simplemente NO vuelven: `items` puede ser más corto que lo que mandaste.
+ * El caller indexa por `retailCustomerId`, nunca aparea por posición.
+ */
+export interface CustomersBatchResponse {
+    items: CustomerBatchItem[];
+}

package/src/retailCustomer/api/interfaces/IRetailCustomerBusinessApi.ts

@@ -8,17 +8,18 @@ import {
     WelcomeAccreditationResultRequest,
     WelcomeBonusResponse,
 } from "@fiado/type-kit/bin/retailCustomer/index.js";
+import { CustomersBatchRequest, CustomersBatchResponse } from "../dtos/CustomersBatch.js";
 
 /**
  * Contrato del publisher HTTP del lambda `retail-customer-business` (SureKeep Fase 2, pista Retail)
- * para sus 6 endpoints privados de cliente (service-to-service, VPC-only).
+ * para sus 7 endpoints privados de cliente (service-to-service, VPC-only).
  *
  * Consumidor previsto:
  *   - `retail-wizard-business` → upsert del cliente post-KYC, aterrizaje del resultado de apertura
  *     de cuenta (D35), y lecturas del cliente por teléfono / id durante la saga de venta.
  *
  * ─────────────────────────────────────────────────────────────────────────────
- * `tenantId` es OBLIGATORIO en los 6 métodos — no es un detalle de firma.
+ * `tenantId` es OBLIGATORIO en los 7 métodos — no es un detalle de firma.
  * ─────────────────────────────────────────────────────────────────────────────
  * Los privados NO llevan token de usuario (`Feature.ANONIMUS`; la protección es la red VPC), así que
  * el lambda destino no tiene `AuthContext.issuer` y NO puede inferir el silo. El caller declara el
@@ -149,4 +150,27 @@ export interface IRetailCustomerBusinessApi {
         payload: WelcomeAccreditationResultRequest,
         tenantId: string,
     ): Promise<StandardResponse<WelcomeBonusResponse>>;
+
+    /**
+     * POST /private/customers/batch?tenantId= — resuelve NOMBRES de cliente EN LOTE por sus ids.
+     * Pensado para pintar una lista sin caer en N+1 contra el privado de un cliente por vez.
+     *
+     * ⚠️ Un id que NO existe simplemente no aparece en `items`: el arreglo puede volver más corto que
+     * lo que mandaste. Indexa el resultado por `retailCustomerId` — NUNCA aparees por posición.
+     * `fullName: null` es otra cosa: el cliente existe y no tiene nombre resuelto.
+     *
+     * El resultado puede ser PARCIAL si DynamoDB deja claves sin procesar tras sus reintentos: faltan
+     * renglones, no explota. Trata la ausencia como «sin nombre», no como error.
+     *
+     * Tope de 100 ids por request, medido sobre lo que manda el caller (el destino deduplica adentro,
+     * pero eso no baja tu cuenta). Lista vacía → `200` con `items: []`, no es error.
+     *
+     * @throws `400 CUSTOMER_BATCH_TOO_LARGE` si el lote pasa de 100 ids. Reintentar igual vuelve a
+     *   fallar: hay que paginar.
+     * @throws `400 UNKNOWN_TENANT` si el `tenantId` viene ausente o desconocido.
+     */
+    getCustomersBatch(
+        payload: CustomersBatchRequest,
+        tenantId: string,
+    ): Promise<StandardResponse<CustomersBatchResponse>>;
 }

package/src/retailCustomer/index.ts

@@ -1,2 +1,3 @@
+export * from "./api/dtos/CustomersBatch.js";
 export * from "./api/interfaces/IRetailCustomerBusinessApi.js";
 export { default as RetailCustomerBusinessApi } from "./api/RetailCustomerBusinessApi.js";