@fiado/api-invoker 4.63.0 → 4.65.0

package/bin/index.d.ts

@@ -77,6 +77,7 @@ export * from "./milestone-business/index.js";
 export * from "./cognitoBackofficeConnector/index.js";
 export * from "./platformRbac/index.js";
 export * from "./retailOrg/index.js";
+export * from "./loanConfig/index.js";
 export * from "./messages-business/index.js";
 export * from "./totp-security/index.js";
 export * from "./equality-connector/index.js";

package/bin/index.js

@@ -77,6 +77,7 @@ export * from "./milestone-business/index.js";
 export * from "./cognitoBackofficeConnector/index.js";
 export * from "./platformRbac/index.js";
 export * from "./retailOrg/index.js";
+export * from "./loanConfig/index.js";
 export * from "./messages-business/index.js";
 export * from "./totp-security/index.js";
 export * from "./equality-connector/index.js";

package/bin/loanConfig/api/LoanConfigBusinessApi.d.ts

@@ -0,0 +1,27 @@
+import type { IHttpRequest } from "@fiado/http-client";
+import { StandardResponse } from "@fiado/gateway-adapter";
+import { BulkGetParametersResponse, ParameterKeyRef, ParameterResponse } from "@fiado/type-kit/bin/loanConfig/index.js";
+import { ILoanConfigBusinessApi } from "./interfaces/ILoanConfigBusinessApi.js";
+/**
+ * Publisher HTTP del lambda `loan-config-business` (componente 09 SureKeep Fase 1) para sus 3
+ * endpoints privados de lectura de parámetros. Contrato y semántica completos →
+ * `ILoanConfigBusinessApi` (tenantId obligatorio, cache 5 min del lado del consumer,
+ * `StandardResponse` → leer `result.data`).
+ *
+ * Env var requerida en el consumer: `LOAN_CONFIG_BUSINESS_URL`.
+ * El template.yml del consumer la setea con:
+ *
+ *   LOAN_CONFIG_BUSINESS_URL: '{{resolve:ssm:loan-config-business}}'
+ *
+ * Convención CLAUDE.md global: SSM key = nombre del lambda owner de la URL.
+ */
+export default class LoanConfigBusinessApi implements ILoanConfigBusinessApi {
+    private httpRequest;
+    private readonly baseUrl;
+    constructor(httpRequest: IHttpRequest);
+    getParameter(paramType: string, key: string, tenantId: string): Promise<StandardResponse<ParameterResponse>>;
+    getParametersByType(paramType: string, tenantId: string): Promise<StandardResponse<{
+        parameters: ParameterResponse[];
+    }>>;
+    bulkGetParameters(items: ParameterKeyRef[], tenantId: string): Promise<StandardResponse<BulkGetParametersResponse>>;
+}

package/bin/loanConfig/api/LoanConfigBusinessApi.js

@@ -0,0 +1,52 @@
+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);
+};
+var __param = (this && this.__param) || function (paramIndex, decorator) {
+    return function (target, key) { decorator(target, key, paramIndex); }
+};
+import { inject, injectable } from "inversify";
+/**
+ * Publisher HTTP del lambda `loan-config-business` (componente 09 SureKeep Fase 1) para sus 3
+ * endpoints privados de lectura de parámetros. Contrato y semántica completos →
+ * `ILoanConfigBusinessApi` (tenantId obligatorio, cache 5 min del lado del consumer,
+ * `StandardResponse` → leer `result.data`).
+ *
+ * Env var requerida en el consumer: `LOAN_CONFIG_BUSINESS_URL`.
+ * El template.yml del consumer la setea con:
+ *
+ *   LOAN_CONFIG_BUSINESS_URL: '{{resolve:ssm:loan-config-business}}'
+ *
+ * Convención CLAUDE.md global: SSM key = nombre del lambda owner de la URL.
+ */
+let LoanConfigBusinessApi = class LoanConfigBusinessApi {
+    httpRequest;
+    // El buildspec publica la URL en SSM con "/" final — se normaliza para no armar "//private".
+    baseUrl = (process.env.LOAN_CONFIG_BUSINESS_URL || "").replace(/\/+$/, "");
+    constructor(httpRequest) {
+        this.httpRequest = httpRequest;
+    }
+    async getParameter(paramType, key, tenantId) {
+        const url = `${this.baseUrl}/private/parameters/${encodeURIComponent(paramType)}/${encodeURIComponent(key)}?tenantId=${encodeURIComponent(tenantId)}`;
+        return await this.httpRequest.get(url);
+    }
+    async getParametersByType(paramType, tenantId) {
+        const url = `${this.baseUrl}/private/parameters/by-type/${encodeURIComponent(paramType)}?tenantId=${encodeURIComponent(tenantId)}`;
+        return await this.httpRequest.get(url);
+    }
+    async bulkGetParameters(items, tenantId) {
+        const url = `${this.baseUrl}/private/parameters/bulk-get?tenantId=${encodeURIComponent(tenantId)}`;
+        return await this.httpRequest.post(url, { items });
+    }
+};
+LoanConfigBusinessApi = __decorate([
+    injectable(),
+    __param(0, inject("IHttpRequest")),
+    __metadata("design:paramtypes", [Object])
+], LoanConfigBusinessApi);
+export default LoanConfigBusinessApi;

package/bin/loanConfig/api/interfaces/ILoanConfigBusinessApi.d.ts

@@ -0,0 +1,67 @@
+import { StandardResponse } from "@fiado/gateway-adapter";
+import { BulkGetParametersResponse, ParameterKeyRef, ParameterResponse } from "@fiado/type-kit/bin/loanConfig/index.js";
+/**
+ * Contrato del publisher HTTP del lambda `loan-config-business` (componente 09 SureKeep Fase 1)
+ * para sus 3 endpoints privados de LECTURA de parámetros operativos (service-to-service, VPC-only).
+ *
+ * loan-config es el "centro de configuración" del SOFOM: una tabla genérica de parámetros
+ * clave/valor discriminados por `paramType` (14 sub-tipos, M6_ADMIN §8). Consumidores previstos:
+ *   - wizard de originación (F2)   → WIZARD (OTP, KYC) · CREDIT (descarte, comisión)
+ *   - motor de crédito (F3)        → SCORING · CREDIT
+ *   - cobranza / batch de mora     → MORA_BLOCK · UNBLOCK · COLLECTIONS · NOTIFICATIONS
+ *
+ * ⏱️ El spec ordena cachear del lado del CONSUMER (~5 min en el warm container, configurable vía
+ * `CONFIG_CACHE_TTL_SECONDS`): los parámetros cambian poco y el hot path no debe pagar una llamada
+ * por lectura. `bulkGetParameters` es la forma eficiente de precargar el cache.
+ *
+ * ─────────────────────────────────────────────────────────────────────────────
+ * `tenantId` es OBLIGATORIO en los 3 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 tenant explícito por query y `@fiado/tenant-context` asume el rol de ESE silo.
+ * Sin `tenantId` → `400 UNKNOWN_TENANT` (fail-closed). Nunca hay default: caer a un tenant por
+ * default sería fail-OPEN y podría devolver parámetros de otra SOFOM.
+ *
+ * ─────────────────────────────────────────────────────────────────────────────
+ * ⚠️ Patrón de retorno: `StandardResponse<T>` — el consumer accede `result.data`, NO `result.body`.
+ * ─────────────────────────────────────────────────────────────────────────────
+ * `@fiado/http-client` devuelve el body pelado (`response.data` de axios); los publishers viejos
+ * que tipan `{ statusCode, body }` son ficción del tipo (ver `IRetailOrgBusinessApi`, donde está
+ * documentado el 500 que costó descubrirlo). Los publishers nuevos dicen la verdad.
+ *
+ * Errores: el lambda destino lanza `DomainError` tipado → el publisher RECHAZA (no devuelve null).
+ * Cada consumer mapea a su propio error de dominio (ver `fiado-api-invoker § 6`):
+ *   `404 PARAMETER_NOT_FOUND` (paramType+key inexistente)
+ *   `400 UNKNOWN_TENANT` (tenantId ausente o desconocido)
+ *
+ * Env var requerida en el consumer: `LOAN_CONFIG_BUSINESS_URL`.
+ * El template.yml del consumer la setea con:
+ *
+ *   LOAN_CONFIG_BUSINESS_URL: '{{resolve:ssm:loan-config-business}}'
+ *
+ * Convención CLAUDE.md global: SSM key = nombre del lambda owner de la URL.
+ */
+export interface ILoanConfigBusinessApi {
+    /**
+     * GET /private/parameters/{paramType}/{key} — un parámetro puntual. `data.effectiveValue` es el
+     * valor a usar (= `value`, o `defaultValue` cuando `value` es null/pendiente).
+     *
+     * @throws si el parámetro no existe (`404 PARAMETER_NOT_FOUND`).
+     */
+    getParameter(paramType: string, key: string, tenantId: string): Promise<StandardResponse<ParameterResponse>>;
+    /**
+     * GET /private/parameters/by-type/{paramType} — todos los parámetros de una categoría (ej. toda
+     * la config de MORA_BLOCK de una vez). Devuelve `{ parameters: [] }` si la categoría está vacía
+     * (no 404): las 14 categorías del enum son válidas por definición.
+     */
+    getParametersByType(paramType: string, tenantId: string): Promise<StandardResponse<{
+        parameters: ParameterResponse[];
+    }>>;
+    /**
+     * POST /private/parameters/bulk-get — el hot path: varios parámetros (de cualquier categoría) en
+     * UNA llamada. Los no existentes NO hacen fallar la llamada: vuelven en `data.notFound` y el
+     * consumer decide (típicamente: usar su default local o fallar tipado).
+     */
+    bulkGetParameters(items: ParameterKeyRef[], tenantId: string): Promise<StandardResponse<BulkGetParametersResponse>>;
+}

package/bin/loanConfig/api/interfaces/ILoanConfigBusinessApi.js

@@ -0,0 +1 @@
+export {};

package/bin/loanConfig/index.d.ts

@@ -0,0 +1,2 @@
+export * from "./api/interfaces/ILoanConfigBusinessApi.js";
+export { default as LoanConfigBusinessApi } from "./api/LoanConfigBusinessApi.js";

package/bin/loanConfig/index.js

@@ -0,0 +1,2 @@
+export * from "./api/interfaces/ILoanConfigBusinessApi.js";
+export { default as LoanConfigBusinessApi } from "./api/LoanConfigBusinessApi.js";

package/bin/retailOrg/api/RetailOrgBusinessApi.d.ts

@@ -1,12 +1,12 @@
 import type { IHttpRequest } from "@fiado/http-client";
 import { StandardResponse } from "@fiado/gateway-adapter";
-import { RetailerValidationDto, StoreValidationDto, RetailUserValidationDto } from "@fiado/type-kit/bin/retailOrg/index.js";
+import { RetailerValidationDto, StoreValidationDto, RetailUserValidationDto, CollectorValidationDto } from "@fiado/type-kit/bin/retailOrg/index.js";
 import { IRetailOrgBusinessApi } from "./interfaces/IRetailOrgBusinessApi.js";
 /**
- * Publisher HTTP del lambda `retail-org-business` (componente 04 SureKeep Fase 1) para sus 4
+ * Publisher HTTP del lambda `retail-org-business` (componente 04 SureKeep Fase 1) para sus 6
  * endpoints privados de validación. Contrato y semántica completos → `IRetailOrgBusinessApi`.
  *
- * Los 4 paths y el `?tenantId=` fueron verificados contra dev (200 + negativos 400/404) el
+ * Los paths y el `?tenantId=` fueron verificados contra dev (200 + negativos 400/404) el
  * 2026-07-16 y matchean `openapi/private.yaml` del lambda destino.
  *
  * Env var requerida en el consumer: `RETAIL_ORG_BUSINESS_URL`.
@@ -25,4 +25,5 @@ export default class RetailOrgBusinessApi implements IRetailOrgBusinessApi {
     getStore(retailerId: string, storeId: string, tenantId: string): Promise<StandardResponse<StoreValidationDto>>;
     getStoreUsers(retailerId: string, storeId: string, tenantId: string): Promise<StandardResponse<RetailUserValidationDto[]>>;
     getUserByCognitoSub(cognitoSub: string, tenantId: string): Promise<StandardResponse<RetailUserValidationDto>>;
+    listActiveCollectorsByRetailer(retailerId: string, tenantId: string): Promise<StandardResponse<CollectorValidationDto[]>>;
 }

package/bin/retailOrg/api/RetailOrgBusinessApi.js

@@ -12,10 +12,10 @@ var __param = (this && this.__param) || function (paramIndex, decorator) {
 };
 import { inject, injectable } from "inversify";
 /**
- * Publisher HTTP del lambda `retail-org-business` (componente 04 SureKeep Fase 1) para sus 4
+ * Publisher HTTP del lambda `retail-org-business` (componente 04 SureKeep Fase 1) para sus 6
  * endpoints privados de validación. Contrato y semántica completos → `IRetailOrgBusinessApi`.
  *
- * Los 4 paths y el `?tenantId=` fueron verificados contra dev (200 + negativos 400/404) el
+ * Los paths y el `?tenantId=` fueron verificados contra dev (200 + negativos 400/404) el
  * 2026-07-16 y matchean `openapi/private.yaml` del lambda destino.
  *
  * Env var requerida en el consumer: `RETAIL_ORG_BUSINESS_URL`.
@@ -51,6 +51,10 @@ let RetailOrgBusinessApi = class RetailOrgBusinessApi {
         const url = `${this.baseUrl}/private/users/by-cognito-sub/${encodeURIComponent(cognitoSub)}?tenantId=${encodeURIComponent(tenantId)}`;
         return await this.httpRequest.get(url);
     }
+    async listActiveCollectorsByRetailer(retailerId, tenantId) {
+        const url = `${this.baseUrl}/private/retailers/${encodeURIComponent(retailerId)}/collectors?tenantId=${encodeURIComponent(tenantId)}`;
+        return await this.httpRequest.get(url);
+    }
 };
 RetailOrgBusinessApi = __decorate([
     injectable(),

package/bin/retailOrg/api/interfaces/IRetailOrgBusinessApi.d.ts

@@ -1,14 +1,15 @@
 import { StandardResponse } from "@fiado/gateway-adapter";
-import { RetailerValidationDto, StoreValidationDto, RetailUserValidationDto } from "@fiado/type-kit/bin/retailOrg/index.js";
+import { RetailerValidationDto, StoreValidationDto, RetailUserValidationDto, CollectorValidationDto } from "@fiado/type-kit/bin/retailOrg/index.js";
 /**
  * Contrato del publisher HTTP del lambda `retail-org-business` (componente 04 SureKeep Fase 1)
- * para sus 4 endpoints privados de VALIDACIÓN (service-to-service, VPC-only).
+ * para sus 6 endpoints privados de VALIDACIÓN (service-to-service, VPC-only).
  *
  * Consumidores previstos (regla R5 — cruces entre lambdas son SOLO lecturas de validación;
  * ningún lambda escribe en tabla ajena):
- *   - `retail-catalog-business` → valida `storeId` al registrar IMEIs
- *   - `retail-cards-business`   → valida `storeId` de un lote de tarjetas PCF
- *   - `loan-*`                  → valida retailer / store / usuarios retail
+ *   - `retail-catalog-business`            → valida `storeId` al registrar IMEIs
+ *   - `retail-cards-business`              → valida `storeId` de un lote de tarjetas PCF
+ *   - `loan-*`                             → valida retailer / store / usuarios retail
+ *   - `loan-collector-assignment-business` → lista cobradores ACTIVE del retailer para asignar cartera
  *
  * ─────────────────────────────────────────────────────────────────────────────
  * `tenantId` es OBLIGATORIO en los 4 métodos — no es un detalle de firma.
@@ -87,4 +88,18 @@ export interface IRetailOrgBusinessApi {
      * @throws si no hay usuario retail para ese sub (`404 RETAIL_USER_NOT_FOUND`).
      */
     getUserByCognitoSub(cognitoSub: string, tenantId: string): Promise<StandardResponse<RetailUserValidationDto>>;
+    /**
+     * GET /private/retailers/{retailerId}/collectors — lista los COBRADORES del retailer que están
+     * `status=ACTIVE`. El criterio de "cobrador" lo aplica retail-org por `commissionTier === 'collector'`
+     * (el caller no lo declara). Lo consume `loan-collector-assignment-business` para alimentar su
+     * algoritmo de asignación de cartera.
+     *
+     * `tenantId` es OBLIGATORIO (igual que el resto de privados): sin él → `400 UNKNOWN_TENANT`
+     * (fail-closed). Nunca hay tenant por default — caer a uno sería fail-OPEN y podría filtrar
+     * cobradores de otra SOFOM.
+     *
+     * Devuelve el body PELADO en `StandardResponse<CollectorValidationDto[]>` (el consumer lee
+     * `result.data`, NO `result.body`). Retorna `[]` (no 404) si el retailer no tiene cobradores activos.
+     */
+    listActiveCollectorsByRetailer(retailerId: string, tenantId: string): Promise<StandardResponse<CollectorValidationDto[]>>;
 }

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@fiado/api-invoker",
-  "version": "4.63.0",
+  "version": "4.65.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",
@@ -34,7 +34,7 @@
     "@fiado/gateway-adapter": "^3.9.0",
     "@fiado/http-client": "^2.0.1",
     "@fiado/logger": "^1.1.3",
-    "@fiado/type-kit": "^3.189.0",
+    "@fiado/type-kit": "^3.191.0",
     "dotenv": "^16.4.7"
   },
   "peerDependencies": {

package/src/index.ts

@@ -77,6 +77,7 @@ export * from "./milestone-business/index.js";
 export * from "./cognitoBackofficeConnector/index.js";
 export * from "./platformRbac/index.js";
 export * from "./retailOrg/index.js";
+export * from "./loanConfig/index.js";
 export * from "./messages-business/index.js";
 export * from "./totp-security/index.js";
 export * from "./equality-connector/index.js";

package/src/loanConfig/api/LoanConfigBusinessApi.ts

@@ -0,0 +1,55 @@
+import { inject, injectable } from "inversify";
+import type { IHttpRequest } from "@fiado/http-client";
+import { StandardResponse } from "@fiado/gateway-adapter";
+import {
+    BulkGetParametersResponse,
+    ParameterKeyRef,
+    ParameterResponse,
+} from "@fiado/type-kit/bin/loanConfig/index.js";
+import { ILoanConfigBusinessApi } from "./interfaces/ILoanConfigBusinessApi.js";
+
+/**
+ * Publisher HTTP del lambda `loan-config-business` (componente 09 SureKeep Fase 1) para sus 3
+ * endpoints privados de lectura de parámetros. Contrato y semántica completos →
+ * `ILoanConfigBusinessApi` (tenantId obligatorio, cache 5 min del lado del consumer,
+ * `StandardResponse` → leer `result.data`).
+ *
+ * Env var requerida en el consumer: `LOAN_CONFIG_BUSINESS_URL`.
+ * El template.yml del consumer la setea con:
+ *
+ *   LOAN_CONFIG_BUSINESS_URL: '{{resolve:ssm:loan-config-business}}'
+ *
+ * Convención CLAUDE.md global: SSM key = nombre del lambda owner de la URL.
+ */
+@injectable()
+export default class LoanConfigBusinessApi implements ILoanConfigBusinessApi {
+    // El buildspec publica la URL en SSM con "/" final — se normaliza para no armar "//private".
+    private readonly baseUrl = (process.env.LOAN_CONFIG_BUSINESS_URL || "").replace(/\/+$/, "");
+
+    constructor(@inject("IHttpRequest") private httpRequest: IHttpRequest) {}
+
+    async getParameter(
+        paramType: string,
+        key: string,
+        tenantId: string,
+    ): Promise<StandardResponse<ParameterResponse>> {
+        const url = `${this.baseUrl}/private/parameters/${encodeURIComponent(paramType)}/${encodeURIComponent(key)}?tenantId=${encodeURIComponent(tenantId)}`;
+        return await this.httpRequest.get(url);
+    }
+
+    async getParametersByType(
+        paramType: string,
+        tenantId: string,
+    ): Promise<StandardResponse<{ parameters: ParameterResponse[] }>> {
+        const url = `${this.baseUrl}/private/parameters/by-type/${encodeURIComponent(paramType)}?tenantId=${encodeURIComponent(tenantId)}`;
+        return await this.httpRequest.get(url);
+    }
+
+    async bulkGetParameters(
+        items: ParameterKeyRef[],
+        tenantId: string,
+    ): Promise<StandardResponse<BulkGetParametersResponse>> {
+        const url = `${this.baseUrl}/private/parameters/bulk-get?tenantId=${encodeURIComponent(tenantId)}`;
+        return await this.httpRequest.post(url, { items });
+    }
+}

package/src/loanConfig/api/interfaces/ILoanConfigBusinessApi.ts

@@ -0,0 +1,82 @@
+import { StandardResponse } from "@fiado/gateway-adapter";
+import {
+    BulkGetParametersResponse,
+    ParameterKeyRef,
+    ParameterResponse,
+} from "@fiado/type-kit/bin/loanConfig/index.js";
+
+/**
+ * Contrato del publisher HTTP del lambda `loan-config-business` (componente 09 SureKeep Fase 1)
+ * para sus 3 endpoints privados de LECTURA de parámetros operativos (service-to-service, VPC-only).
+ *
+ * loan-config es el "centro de configuración" del SOFOM: una tabla genérica de parámetros
+ * clave/valor discriminados por `paramType` (14 sub-tipos, M6_ADMIN §8). Consumidores previstos:
+ *   - wizard de originación (F2)   → WIZARD (OTP, KYC) · CREDIT (descarte, comisión)
+ *   - motor de crédito (F3)        → SCORING · CREDIT
+ *   - cobranza / batch de mora     → MORA_BLOCK · UNBLOCK · COLLECTIONS · NOTIFICATIONS
+ *
+ * ⏱️ El spec ordena cachear del lado del CONSUMER (~5 min en el warm container, configurable vía
+ * `CONFIG_CACHE_TTL_SECONDS`): los parámetros cambian poco y el hot path no debe pagar una llamada
+ * por lectura. `bulkGetParameters` es la forma eficiente de precargar el cache.
+ *
+ * ─────────────────────────────────────────────────────────────────────────────
+ * `tenantId` es OBLIGATORIO en los 3 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 tenant explícito por query y `@fiado/tenant-context` asume el rol de ESE silo.
+ * Sin `tenantId` → `400 UNKNOWN_TENANT` (fail-closed). Nunca hay default: caer a un tenant por
+ * default sería fail-OPEN y podría devolver parámetros de otra SOFOM.
+ *
+ * ─────────────────────────────────────────────────────────────────────────────
+ * ⚠️ Patrón de retorno: `StandardResponse<T>` — el consumer accede `result.data`, NO `result.body`.
+ * ─────────────────────────────────────────────────────────────────────────────
+ * `@fiado/http-client` devuelve el body pelado (`response.data` de axios); los publishers viejos
+ * que tipan `{ statusCode, body }` son ficción del tipo (ver `IRetailOrgBusinessApi`, donde está
+ * documentado el 500 que costó descubrirlo). Los publishers nuevos dicen la verdad.
+ *
+ * Errores: el lambda destino lanza `DomainError` tipado → el publisher RECHAZA (no devuelve null).
+ * Cada consumer mapea a su propio error de dominio (ver `fiado-api-invoker § 6`):
+ *   `404 PARAMETER_NOT_FOUND` (paramType+key inexistente)
+ *   `400 UNKNOWN_TENANT` (tenantId ausente o desconocido)
+ *
+ * Env var requerida en el consumer: `LOAN_CONFIG_BUSINESS_URL`.
+ * El template.yml del consumer la setea con:
+ *
+ *   LOAN_CONFIG_BUSINESS_URL: '{{resolve:ssm:loan-config-business}}'
+ *
+ * Convención CLAUDE.md global: SSM key = nombre del lambda owner de la URL.
+ */
+export interface ILoanConfigBusinessApi {
+    /**
+     * GET /private/parameters/{paramType}/{key} — un parámetro puntual. `data.effectiveValue` es el
+     * valor a usar (= `value`, o `defaultValue` cuando `value` es null/pendiente).
+     *
+     * @throws si el parámetro no existe (`404 PARAMETER_NOT_FOUND`).
+     */
+    getParameter(
+        paramType: string,
+        key: string,
+        tenantId: string,
+    ): Promise<StandardResponse<ParameterResponse>>;
+
+    /**
+     * GET /private/parameters/by-type/{paramType} — todos los parámetros de una categoría (ej. toda
+     * la config de MORA_BLOCK de una vez). Devuelve `{ parameters: [] }` si la categoría está vacía
+     * (no 404): las 14 categorías del enum son válidas por definición.
+     */
+    getParametersByType(
+        paramType: string,
+        tenantId: string,
+    ): Promise<StandardResponse<{ parameters: ParameterResponse[] }>>;
+
+    /**
+     * POST /private/parameters/bulk-get — el hot path: varios parámetros (de cualquier categoría) en
+     * UNA llamada. Los no existentes NO hacen fallar la llamada: vuelven en `data.notFound` y el
+     * consumer decide (típicamente: usar su default local o fallar tipado).
+     */
+    bulkGetParameters(
+        items: ParameterKeyRef[],
+        tenantId: string,
+    ): Promise<StandardResponse<BulkGetParametersResponse>>;
+}

package/src/loanConfig/index.ts

@@ -0,0 +1,2 @@
+export * from "./api/interfaces/ILoanConfigBusinessApi.js";
+export { default as LoanConfigBusinessApi } from "./api/LoanConfigBusinessApi.js";

package/src/retailOrg/api/RetailOrgBusinessApi.ts

@@ -5,14 +5,15 @@ import {
     RetailerValidationDto,
     StoreValidationDto,
     RetailUserValidationDto,
+    CollectorValidationDto,
 } from "@fiado/type-kit/bin/retailOrg/index.js";
 import { IRetailOrgBusinessApi } from "./interfaces/IRetailOrgBusinessApi.js";
 
 /**
- * Publisher HTTP del lambda `retail-org-business` (componente 04 SureKeep Fase 1) para sus 4
+ * Publisher HTTP del lambda `retail-org-business` (componente 04 SureKeep Fase 1) para sus 6
  * endpoints privados de validación. Contrato y semántica completos → `IRetailOrgBusinessApi`.
  *
- * Los 4 paths y el `?tenantId=` fueron verificados contra dev (200 + negativos 400/404) el
+ * Los paths y el `?tenantId=` fueron verificados contra dev (200 + negativos 400/404) el
  * 2026-07-16 y matchean `openapi/private.yaml` del lambda destino.
  *
  * Env var requerida en el consumer: `RETAIL_ORG_BUSINESS_URL`.
@@ -69,4 +70,12 @@ export default class RetailOrgBusinessApi implements IRetailOrgBusinessApi {
         const url = `${this.baseUrl}/private/users/by-cognito-sub/${encodeURIComponent(cognitoSub)}?tenantId=${encodeURIComponent(tenantId)}`;
         return await this.httpRequest.get(url);
     }
+
+    async listActiveCollectorsByRetailer(
+        retailerId: string,
+        tenantId: string,
+    ): Promise<StandardResponse<CollectorValidationDto[]>> {
+        const url = `${this.baseUrl}/private/retailers/${encodeURIComponent(retailerId)}/collectors?tenantId=${encodeURIComponent(tenantId)}`;
+        return await this.httpRequest.get(url);
+    }
 }

package/src/retailOrg/api/interfaces/IRetailOrgBusinessApi.ts

@@ -3,17 +3,19 @@ import {
     RetailerValidationDto,
     StoreValidationDto,
     RetailUserValidationDto,
+    CollectorValidationDto,
 } from "@fiado/type-kit/bin/retailOrg/index.js";
 
 /**
  * Contrato del publisher HTTP del lambda `retail-org-business` (componente 04 SureKeep Fase 1)
- * para sus 4 endpoints privados de VALIDACIÓN (service-to-service, VPC-only).
+ * para sus 6 endpoints privados de VALIDACIÓN (service-to-service, VPC-only).
  *
  * Consumidores previstos (regla R5 — cruces entre lambdas son SOLO lecturas de validación;
  * ningún lambda escribe en tabla ajena):
- *   - `retail-catalog-business` → valida `storeId` al registrar IMEIs
- *   - `retail-cards-business`   → valida `storeId` de un lote de tarjetas PCF
- *   - `loan-*`                  → valida retailer / store / usuarios retail
+ *   - `retail-catalog-business`            → valida `storeId` al registrar IMEIs
+ *   - `retail-cards-business`              → valida `storeId` de un lote de tarjetas PCF
+ *   - `loan-*`                             → valida retailer / store / usuarios retail
+ *   - `loan-collector-assignment-business` → lista cobradores ACTIVE del retailer para asignar cartera
  *
  * ─────────────────────────────────────────────────────────────────────────────
  * `tenantId` es OBLIGATORIO en los 4 métodos — no es un detalle de firma.
@@ -113,4 +115,22 @@ export interface IRetailOrgBusinessApi {
         cognitoSub: string,
         tenantId: string,
     ): Promise<StandardResponse<RetailUserValidationDto>>;
+
+    /**
+     * GET /private/retailers/{retailerId}/collectors — lista los COBRADORES del retailer que están
+     * `status=ACTIVE`. El criterio de "cobrador" lo aplica retail-org por `commissionTier === 'collector'`
+     * (el caller no lo declara). Lo consume `loan-collector-assignment-business` para alimentar su
+     * algoritmo de asignación de cartera.
+     *
+     * `tenantId` es OBLIGATORIO (igual que el resto de privados): sin él → `400 UNKNOWN_TENANT`
+     * (fail-closed). Nunca hay tenant por default — caer a uno sería fail-OPEN y podría filtrar
+     * cobradores de otra SOFOM.
+     *
+     * Devuelve el body PELADO en `StandardResponse<CollectorValidationDto[]>` (el consumer lee
+     * `result.data`, NO `result.body`). Retorna `[]` (no 404) si el retailer no tiene cobradores activos.
+     */
+    listActiveCollectorsByRetailer(
+        retailerId: string,
+        tenantId: string,
+    ): Promise<StandardResponse<CollectorValidationDto[]>>;
 }