@fiado/api-invoker 5.19.0 → 5.21.0

package/bin/biometrics-business/BiometricsBusinessApi.d.ts

@@ -1,6 +1,6 @@
 import type { IBiometricsBusinessApi } from "./interfaces/IBiometricsBusinessApi.js";
 import type { BiometricVerificationChangedV1, BiometricVerificationResponse, CreateBiometricVerificationRequest } from "@fiado/type-kit/bin/biometrics/index.js";
-import type { ApiGatewayResponse } from "@fiado/gateway-adapter";
+import type { StandardResponse } from "@fiado/gateway-adapter";
 import type { IHttpRequest } from "@fiado/http-client";
 /**
  * Implementación del cliente de `biometrics-business`. Ver `IBiometricsBusinessApi` para el
@@ -21,9 +21,9 @@ export declare class BiometricsBusinessApi implements IBiometricsBusinessApi {
      */
     private readonly baseUrl;
     constructor(httpRequest: IHttpRequest);
-    createBiometricVerification(data: CreateBiometricVerificationRequest): Promise<ApiGatewayResponse<BiometricVerificationResponse>>;
-    getBiometricVerification(biometricVerificationId: string): Promise<ApiGatewayResponse<BiometricVerificationResponse>>;
-    applyBiometricEvent(biometricVerificationId: string, data: BiometricVerificationChangedV1): Promise<ApiGatewayResponse<void>>;
+    createBiometricVerification(data: CreateBiometricVerificationRequest): Promise<StandardResponse<BiometricVerificationResponse>>;
+    getBiometricVerification(biometricVerificationId: string): Promise<StandardResponse<BiometricVerificationResponse>>;
+    applyBiometricEvent(biometricVerificationId: string, data: BiometricVerificationChangedV1): Promise<StandardResponse<void>>;
 }
 /**
  * También como default, por simetría con el resto de los clients del paquete.

package/bin/biometrics-business/interfaces/IBiometricsBusinessApi.d.ts

@@ -1,5 +1,5 @@
 import type { BiometricVerificationChangedV1, BiometricVerificationResponse, CreateBiometricVerificationRequest } from "@fiado/type-kit/bin/biometrics/index.js";
-import type { ApiGatewayResponse } from "@fiado/gateway-adapter";
+import type { StandardResponse } from "@fiado/gateway-adapter";
 /**
  * Cliente de `biometrics-business`, el master de la lógica biométrica de Fiado.
  *
@@ -26,7 +26,7 @@ export interface IBiometricsBusinessApi {
      * soportada). **`biometrics-business` NO degrada**: no sabe qué debe pasar en tu flujo si falla.
      * Esa política es tuya — el wizard, por ejemplo, degrada a KYC completo.
      */
-    createBiometricVerification(data: CreateBiometricVerificationRequest): Promise<ApiGatewayResponse<BiometricVerificationResponse>>;
+    createBiometricVerification(data: CreateBiometricVerificationRequest): Promise<StandardResponse<BiometricVerificationResponse>>;
     /**
      * El estado actual de una verificación. Es el endpoint de polling.
      *
@@ -36,7 +36,7 @@ export interface IBiometricsBusinessApi {
      *
      * La expiración no depende de que llegue ningún evento: este `GET` la calcula y la persiste.
      */
-    getBiometricVerification(biometricVerificationId: string): Promise<ApiGatewayResponse<BiometricVerificationResponse>>;
+    getBiometricVerification(biometricVerificationId: string): Promise<StandardResponse<BiometricVerificationResponse>>;
     /**
      * Avisa que el proveedor reportó algo sobre una verificación. **Su único caller legítimo es
      * `kyc-metamap-webhook`** — un producto normal no llama acá.
@@ -51,5 +51,5 @@ export interface IBiometricsBusinessApi {
      * - `5xx` → devolver no-200 al proveedor **para que reintente**. Esto es seguro SOLO en la rama
      *   biométrica, que corta antes de escribir nada y no tiene efectos que duplicar.
      */
-    applyBiometricEvent(biometricVerificationId: string, data: BiometricVerificationChangedV1): Promise<ApiGatewayResponse<void>>;
+    applyBiometricEvent(biometricVerificationId: string, data: BiometricVerificationChangedV1): Promise<StandardResponse<void>>;
 }

package/bin/kyc/api/KycVerificationsBusinessApi.d.ts

@@ -2,10 +2,12 @@ import type { StandardResponse } from "@fiado/gateway-adapter";
 import type { IHttpRequest } from "@fiado/http-client";
 import type { KycByDirectoryResponse } from "@fiado/type-kit/bin/kyc/index.js";
 import type { IKycVerificationsBusinessApi } from "./interfaces/IKycVerificationsBusinessApi.js";
+import type { CountryWorkflowResponse } from "./dtos/CountryWorkflowResponse.js";
 /** Contrato y semántica completos → `IKycVerificationsBusinessApi` (`StandardResponse` → leer `result.data`). */
 export declare class KycVerificationsBusinessApi implements IKycVerificationsBusinessApi {
     private httpRequest;
     private readonly baseUrl;
     constructor(httpRequest: IHttpRequest);
     getByDirectory(directoryId: string): Promise<StandardResponse<KycByDirectoryResponse>>;
+    getFlowById(id: string): Promise<StandardResponse<CountryWorkflowResponse>>;
 }

package/bin/kyc/api/KycVerificationsBusinessApi.js

@@ -28,6 +28,12 @@ let KycVerificationsBusinessApi = class KycVerificationsBusinessApi {
         const url = `${this.baseUrl}/verifications/by-directory/${encodeURIComponent(directoryId)}`;
         return await this.httpRequest.get(url);
     }
+    async getFlowById(id) {
+        // SIN prefijo `/private`, por lo mismo que `getByDirectory`: la API que resuelve el SSM es
+        // PRIVADA COMPLETA y sus paths cuelgan de la raíz.
+        const url = `${this.baseUrl}/flows/${encodeURIComponent(id)}`;
+        return await this.httpRequest.get(url);
+    }
 };
 KycVerificationsBusinessApi = __decorate([
     injectable(),

package/bin/kyc/api/dtos/CountryWorkflowResponse.d.ts

@@ -0,0 +1,20 @@
+/**
+ * Una fila del catálogo `CountryWorkflow` de `kyc-verifications-business`: el mapa
+ * `id` → `workflowId` de Metamap.
+ *
+ * ⚠️ El `id` **no siempre es un país**. La tabla arrancó como "flow por país" (`484` = México,
+ * `USA`, `724` = pasaportes de España) pero ya lleva llaves sintéticas para flows que no dependen
+ * del país: `PROOF_OF_ADDRESS` (comprobante de domicilio), `000` (agentes) y `FACEMATCH`. Tratalo
+ * como una llave opaca de catálogo, no como un `CountryId`.
+ *
+ * El backoffice edita estas filas en caliente, así que el valor **puede cambiar sin un deploy**.
+ * Ese es justamente el motivo de leerlo de acá y no de una env var.
+ */
+export interface CountryWorkflowResponse {
+    /** La llave del catálogo: un `CountryId`, o una llave sintética como `FACEMATCH`. */
+    id: string;
+    /** El flow ID de Metamap. Es lo que se manda como `flowId` al widget hospedado. */
+    workflowId: string;
+    /** Texto libre que escribe el backoffice. Puede venir `null`. */
+    description: string | null;
+}

package/bin/kyc/api/dtos/CountryWorkflowResponse.js

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

package/bin/kyc/api/interfaces/IKycVerificationsBusinessApi.d.ts

@@ -1,5 +1,6 @@
 import type { StandardResponse } from "@fiado/gateway-adapter";
 import type { KycByDirectoryResponse } from "@fiado/type-kit/bin/kyc/index.js";
+import type { CountryWorkflowResponse } from "../dtos/CountryWorkflowResponse.js";
 /**
  * Publisher del privado de `kyc-verifications-business`.
  *
@@ -29,4 +30,24 @@ export interface IKycVerificationsBusinessApi {
      * @throws propaga el error del destino; nunca devuelve fallback.
      */
     getByDirectory(directoryId: string): Promise<StandardResponse<KycByDirectoryResponse>>;
+    /**
+     * Una fila del catálogo `CountryWorkflow`: la traducción `id` → `workflowId` de Metamap.
+     *
+     * Es la **fuente canónica** del flow ID. El backoffice edita estas filas en caliente, así que
+     * un consumidor que guarde el flow ID en una env var queda desincronizado en cuanto alguien lo
+     * cambia ahí — sin que nadie se entere hasta que Metamap rechaza la verificación.
+     *
+     * El `id` es una llave opaca de catálogo, NO necesariamente un país: además de los `CountryId`
+     * (`484`, `USA`, `724`) la tabla lleva llaves sintéticas como `PROOF_OF_ADDRESS`, `000` y
+     * `FACEMATCH`.
+     *
+     * ⚠️ Si la llave no existe en el catálogo el destino responde **400**, no 404 — verificado
+     * contra el PR #92 de `kyc-verifications-business`. Es el comportamiento que ya tenía
+     * `CountryWorkflowManager` para el endpoint público y no se cambió para no romperle el
+     * contrato. Un flow que falta es un error de configuración, no un caso vacío: el consumidor
+     * debe fallar ruidoso, nunca degradar a un default.
+     *
+     * @throws propaga el error del destino; nunca devuelve fallback.
+     */
+    getFlowById(id: string): Promise<StandardResponse<CountryWorkflowResponse>>;
 }

package/bin/kyc/index.d.ts

@@ -1,4 +1,5 @@
 export * from './api/interfaces/IKycVerificationsBusinessApi.js';
+export * from './api/dtos/CountryWorkflowResponse.js';
 export * from './api/KycVerificationsBusinessApi.js';
 export * from './queue/interfaces/IRetailKycInboundPublisher.js';
 export * from './queue/RetailKycInboundPublisher.js';

package/bin/kyc/index.js

@@ -1,4 +1,5 @@
 export * from './api/interfaces/IKycVerificationsBusinessApi.js';
+export * from './api/dtos/CountryWorkflowResponse.js';
 export * from './api/KycVerificationsBusinessApi.js';
 export * from './queue/interfaces/IRetailKycInboundPublisher.js';
 export * from './queue/RetailKycInboundPublisher.js';

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

@@ -1,6 +1,6 @@
 import type { IHttpRequest } from "@fiado/http-client";
 import { StandardResponse } from "@fiado/gateway-adapter";
-import { RetailerValidationDto, StoreValidationDto, RetailUserValidationDto, CollectorValidationDto } from "@fiado/type-kit/bin/retailOrg/index.js";
+import { RetailerValidationDto, StoreValidationDto, RetailUserValidationDto, CollectorValidationDto, PrivateSellerListResponse, RetailUserStatusEnum } 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 6
@@ -26,4 +26,13 @@ export default class RetailOrgBusinessApi implements IRetailOrgBusinessApi {
     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[]>>;
+    /**
+     * SureKeep F3 — el padrón de vendedores que consume el motor de comisiones al cerrar el corte.
+     * Contrato y semántica completos (incluido por qué `status` NO tiene default y por qué
+     * `callerService` es obligatorio) → `IRetailOrgBusinessApi.listSellers`.
+     *
+     * ⚠️ Es el único método de este publisher con el `retailerId` en el QUERY y no anidado en el
+     * path: el caller no está validando un recurso, está pidiendo una colección entera.
+     */
+    listSellers(retailerId: string, tenantId: string, callerService: string, status?: RetailUserStatusEnum): Promise<StandardResponse<PrivateSellerListResponse>>;
 }

package/bin/retailOrg/api/RetailOrgBusinessApi.js

@@ -55,6 +55,22 @@ let RetailOrgBusinessApi = class RetailOrgBusinessApi {
         const url = `${this.baseUrl}/private/retailers/${encodeURIComponent(retailerId)}/collectors?tenantId=${encodeURIComponent(tenantId)}`;
         return await this.httpRequest.get(url);
     }
+    /**
+     * SureKeep F3 — el padrón de vendedores que consume el motor de comisiones al cerrar el corte.
+     * Contrato y semántica completos (incluido por qué `status` NO tiene default y por qué
+     * `callerService` es obligatorio) → `IRetailOrgBusinessApi.listSellers`.
+     *
+     * ⚠️ Es el único método de este publisher con el `retailerId` en el QUERY y no anidado en el
+     * path: el caller no está validando un recurso, está pidiendo una colección entera.
+     */
+    async listSellers(retailerId, tenantId, callerService, status) {
+        // `URLSearchParams` en vez de concatenar: `status` es opcional y armar el `&status=` a mano
+        // deja un `&status=undefined` en cuanto alguien se distrae.
+        const query = new URLSearchParams({ retailerId, tenantId, callerService });
+        if (status)
+            query.set("status", status);
+        return await this.httpRequest.get(`${this.baseUrl}/private/sellers?${query.toString()}`);
+    }
 };
 RetailOrgBusinessApi = __decorate([
     injectable(),

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

@@ -1,5 +1,5 @@
 import { StandardResponse } from "@fiado/gateway-adapter";
-import { RetailerValidationDto, StoreValidationDto, RetailUserValidationDto, CollectorValidationDto } from "@fiado/type-kit/bin/retailOrg/index.js";
+import { RetailerValidationDto, StoreValidationDto, RetailUserValidationDto, CollectorValidationDto, PrivateSellerListResponse, RetailUserStatusEnum } from "@fiado/type-kit/bin/retailOrg/index.js";
 /**
  * Contrato del publisher HTTP del lambda `retail-org-business` (componente 04 SureKeep Fase 1)
  * para sus 6 endpoints privados de VALIDACIÓN (service-to-service, VPC-only).
@@ -102,4 +102,39 @@ export interface IRetailOrgBusinessApi {
      * `result.data`, NO `result.body`). Retorna `[]` (no 404) si el retailer no tiene cobradores activos.
      */
     listActiveCollectorsByRetailer(retailerId: string, tenantId: string): Promise<StandardResponse<CollectorValidationDto[]>>;
+    /**
+     * `GET /private/sellers?retailerId=…` (SureKeep F3) — el **padrón de vendedores** de una cadena.
+     *
+     * ── 🔴 Por qué este método existe ────────────────────────────────────────────────────────────
+     * Lo consume el **motor de comisiones** al cerrar el corte del periodo, para saber a quién hay
+     * que pagarle y abrir una fila de devengo por cada uno. **Sin esta lista el fan-out del cierre
+     * no arranca.** Publicarlo acá es lo que evita que el motor caiga en `DIRECT_HTTP` (antipatrón
+     * duro): entre lambdas de Fiado la comunicación va SIEMPRE por `@fiado/api-invoker`.
+     *
+     * Devuelve el shape mínimo —`sellerId`, `displayName`, `homeStoreId`, `commissionTier`,
+     * `status`— **sin PII de contacto**: nada de teléfono ni `cognitoSub`. `commissionTier` no es
+     * adorno: es lo que el motor usa para resolver CUÁNTO le toca a cada quien según el plan vigente.
+     *
+     * Excluye a los COBRADORES (`commissionTier === 'collector'`), que tienen su propio método
+     * (`listActiveCollectorsByRetailer`) — la cobranza es del otro dominio.
+     *
+     * ── ⚠️ `status` NO tiene default ─────────────────────────────────────────────────────────────
+     * Omitirlo devuelve **TODOS** los estados, no solo los activos. Es deliberado: un vendedor dado
+     * de baja el día 20 **sí tiene comisión** por lo que vendió hasta el 19, y un default `ACTIVE`
+     * lo perdería en silencio sin dejar ninguna forma de pedir el padrón completo. Si el motor
+     * quiere solo activos, que lo diga explícito.
+     *
+     * ── `callerService`: quién exportó la nómina ─────────────────────────────────────────────────
+     * El endpoint es `Feature.ANONIMUS` (sin token de usuario), así que **no hay `actorId`** al que
+     * atribuirle la lectura — y esto exporta la nómina completa de una cadena en una sola llamada.
+     * El lambda destino registra el acceso en `SharedPiiAccessLog_GT` y usa este valor para saber
+     * QUIÉN lo pidió. Si se omite, el registro queda como `m2m:unknown` (con WARN en CloudWatch);
+     * **no lo omitas**: es la única traza que existe de una exportación masiva de datos de empleados.
+     *
+     * @throws `404 RETAILER_NOT_FOUND` si el retailer no existe en ese silo. Un `[]` no distinguiría
+     *   "esta cadena no tiene vendedores" de "preguntaste por una cadena que no existe", y lo segundo
+     *   cerraría el corte sin devengos sin que nadie se entere hasta el día de pago.
+     * @throws `400 VALIDATION_ERROR` si `retailerId` no es un ULID · `400 UNKNOWN_TENANT` sin `tenantId`.
+     */
+    listSellers(retailerId: string, tenantId: string, callerService: string, status?: RetailUserStatusEnum): Promise<StandardResponse<PrivateSellerListResponse>>;
 }

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@fiado/api-invoker",
-  "version": "5.19.0",
+  "version": "5.21.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.276.0",
+    "@fiado/type-kit": "^3.278.0",
     "dotenv": "^16.4.7"
   },
   "peerDependencies": {

package/src/biometrics-business/BiometricsBusinessApi.ts

@@ -5,7 +5,7 @@ import type {
     BiometricVerificationResponse,
     CreateBiometricVerificationRequest,
 } from "@fiado/type-kit/bin/biometrics/index.js";
-import type { ApiGatewayResponse } from "@fiado/gateway-adapter";
+import type { StandardResponse } from "@fiado/gateway-adapter";
 // ⚠️ `import type` y NO un import de valor. `@fiado/http-client` se publica como CJS; importar
 // `IHttpRequest` como valor hace que jest falle al cargar el módulo bajo ESM
 // ("does not provide an export named 'IHttpRequest'"). Con `import type` se borra al compilar.
@@ -35,14 +35,14 @@ export class BiometricsBusinessApi implements IBiometricsBusinessApi {
 
     async createBiometricVerification(
         data: CreateBiometricVerificationRequest,
-    ): Promise<ApiGatewayResponse<BiometricVerificationResponse>> {
+    ): Promise<StandardResponse<BiometricVerificationResponse>> {
         const url = `${this.baseUrl}/biometric-verifications`;
         return await this.httpRequest.post(url, data);
     }
 
     async getBiometricVerification(
         biometricVerificationId: string,
-    ): Promise<ApiGatewayResponse<BiometricVerificationResponse>> {
+    ): Promise<StandardResponse<BiometricVerificationResponse>> {
         // encodeURIComponent y no interpolación pelada: el id va en el path, y aunque hoy lo genera
         // biometrics-business, el día que un caller pase basura preferimos un 404 a una URL rota.
         const url = `${this.baseUrl}/biometric-verifications/${encodeURIComponent(biometricVerificationId)}`;
@@ -52,7 +52,7 @@ export class BiometricsBusinessApi implements IBiometricsBusinessApi {
     async applyBiometricEvent(
         biometricVerificationId: string,
         data: BiometricVerificationChangedV1,
-    ): Promise<ApiGatewayResponse<void>> {
+    ): Promise<StandardResponse<void>> {
         const url = `${this.baseUrl}/biometric-verifications/${encodeURIComponent(biometricVerificationId)}/events`;
         return await this.httpRequest.post(url, data);
     }

package/src/biometrics-business/interfaces/IBiometricsBusinessApi.ts

@@ -3,7 +3,7 @@ import type {
     BiometricVerificationResponse,
     CreateBiometricVerificationRequest,
 } from "@fiado/type-kit/bin/biometrics/index.js";
-import type { ApiGatewayResponse } from "@fiado/gateway-adapter";
+import type { StandardResponse } from "@fiado/gateway-adapter";
 
 /**
  * Cliente de `biometrics-business`, el master de la lógica biométrica de Fiado.
@@ -33,7 +33,7 @@ export interface IBiometricsBusinessApi {
      */
     createBiometricVerification(
         data: CreateBiometricVerificationRequest,
-    ): Promise<ApiGatewayResponse<BiometricVerificationResponse>>;
+    ): Promise<StandardResponse<BiometricVerificationResponse>>;
 
     /**
      * El estado actual de una verificación. Es el endpoint de polling.
@@ -46,7 +46,7 @@ export interface IBiometricsBusinessApi {
      */
     getBiometricVerification(
         biometricVerificationId: string,
-    ): Promise<ApiGatewayResponse<BiometricVerificationResponse>>;
+    ): Promise<StandardResponse<BiometricVerificationResponse>>;
 
     /**
      * Avisa que el proveedor reportó algo sobre una verificación. **Su único caller legítimo es
@@ -65,5 +65,5 @@ export interface IBiometricsBusinessApi {
     applyBiometricEvent(
         biometricVerificationId: string,
         data: BiometricVerificationChangedV1,
-    ): Promise<ApiGatewayResponse<void>>;
+    ): Promise<StandardResponse<void>>;
 }

package/src/kyc/api/KycVerificationsBusinessApi.ts

@@ -3,6 +3,7 @@ import type { StandardResponse } from "@fiado/gateway-adapter";
 import type { IHttpRequest } from "@fiado/http-client";
 import type { KycByDirectoryResponse } from "@fiado/type-kit/bin/kyc/index.js";
 import type { IKycVerificationsBusinessApi } from "./interfaces/IKycVerificationsBusinessApi.js";
+import type { CountryWorkflowResponse } from "./dtos/CountryWorkflowResponse.js";
 
 /** Contrato y semántica completos → `IKycVerificationsBusinessApi` (`StandardResponse` → leer `result.data`). */
 @injectable()
@@ -22,4 +23,11 @@ export class KycVerificationsBusinessApi implements IKycVerificationsBusinessApi
         const url = `${this.baseUrl}/verifications/by-directory/${encodeURIComponent(directoryId)}`;
         return await this.httpRequest.get<StandardResponse<KycByDirectoryResponse>>(url);
     }
+
+    async getFlowById(id: string): Promise<StandardResponse<CountryWorkflowResponse>> {
+        // SIN prefijo `/private`, por lo mismo que `getByDirectory`: la API que resuelve el SSM es
+        // PRIVADA COMPLETA y sus paths cuelgan de la raíz.
+        const url = `${this.baseUrl}/flows/${encodeURIComponent(id)}`;
+        return await this.httpRequest.get<StandardResponse<CountryWorkflowResponse>>(url);
+    }
 }

package/src/kyc/api/dtos/CountryWorkflowResponse.ts

@@ -0,0 +1,20 @@
+/**
+ * Una fila del catálogo `CountryWorkflow` de `kyc-verifications-business`: el mapa
+ * `id` → `workflowId` de Metamap.
+ *
+ * ⚠️ El `id` **no siempre es un país**. La tabla arrancó como "flow por país" (`484` = México,
+ * `USA`, `724` = pasaportes de España) pero ya lleva llaves sintéticas para flows que no dependen
+ * del país: `PROOF_OF_ADDRESS` (comprobante de domicilio), `000` (agentes) y `FACEMATCH`. Tratalo
+ * como una llave opaca de catálogo, no como un `CountryId`.
+ *
+ * El backoffice edita estas filas en caliente, así que el valor **puede cambiar sin un deploy**.
+ * Ese es justamente el motivo de leerlo de acá y no de una env var.
+ */
+export interface CountryWorkflowResponse {
+    /** La llave del catálogo: un `CountryId`, o una llave sintética como `FACEMATCH`. */
+    id: string;
+    /** El flow ID de Metamap. Es lo que se manda como `flowId` al widget hospedado. */
+    workflowId: string;
+    /** Texto libre que escribe el backoffice. Puede venir `null`. */
+    description: string | null;
+}

package/src/kyc/api/interfaces/IKycVerificationsBusinessApi.ts

@@ -1,5 +1,6 @@
 import type { StandardResponse } from "@fiado/gateway-adapter";
 import type { KycByDirectoryResponse } from "@fiado/type-kit/bin/kyc/index.js";
+import type { CountryWorkflowResponse } from "../dtos/CountryWorkflowResponse.js";
 
 /**
  * Publisher del privado de `kyc-verifications-business`.
@@ -30,4 +31,25 @@ export interface IKycVerificationsBusinessApi {
      * @throws propaga el error del destino; nunca devuelve fallback.
      */
     getByDirectory(directoryId: string): Promise<StandardResponse<KycByDirectoryResponse>>;
+
+    /**
+     * Una fila del catálogo `CountryWorkflow`: la traducción `id` → `workflowId` de Metamap.
+     *
+     * Es la **fuente canónica** del flow ID. El backoffice edita estas filas en caliente, así que
+     * un consumidor que guarde el flow ID en una env var queda desincronizado en cuanto alguien lo
+     * cambia ahí — sin que nadie se entere hasta que Metamap rechaza la verificación.
+     *
+     * El `id` es una llave opaca de catálogo, NO necesariamente un país: además de los `CountryId`
+     * (`484`, `USA`, `724`) la tabla lleva llaves sintéticas como `PROOF_OF_ADDRESS`, `000` y
+     * `FACEMATCH`.
+     *
+     * ⚠️ Si la llave no existe en el catálogo el destino responde **400**, no 404 — verificado
+     * contra el PR #92 de `kyc-verifications-business`. Es el comportamiento que ya tenía
+     * `CountryWorkflowManager` para el endpoint público y no se cambió para no romperle el
+     * contrato. Un flow que falta es un error de configuración, no un caso vacío: el consumidor
+     * debe fallar ruidoso, nunca degradar a un default.
+     *
+     * @throws propaga el error del destino; nunca devuelve fallback.
+     */
+    getFlowById(id: string): Promise<StandardResponse<CountryWorkflowResponse>>;
 }

package/src/kyc/index.ts

@@ -1,4 +1,5 @@
 export * from './api/interfaces/IKycVerificationsBusinessApi.js';
+export * from './api/dtos/CountryWorkflowResponse.js';
 export * from './api/KycVerificationsBusinessApi.js';
 export * from './queue/interfaces/IRetailKycInboundPublisher.js';
 export * from './queue/RetailKycInboundPublisher.js';

package/src/retailOrg/api/RetailOrgBusinessApi.ts

@@ -6,6 +6,8 @@ import {
     StoreValidationDto,
     RetailUserValidationDto,
     CollectorValidationDto,
+    PrivateSellerListResponse,
+    RetailUserStatusEnum,
 } from "@fiado/type-kit/bin/retailOrg/index.js";
 import { IRetailOrgBusinessApi } from "./interfaces/IRetailOrgBusinessApi.js";
 
@@ -78,4 +80,25 @@ export default class RetailOrgBusinessApi implements IRetailOrgBusinessApi {
         const url = `${this.baseUrl}/private/retailers/${encodeURIComponent(retailerId)}/collectors?tenantId=${encodeURIComponent(tenantId)}`;
         return await this.httpRequest.get(url);
     }
+
+    /**
+     * SureKeep F3 — el padrón de vendedores que consume el motor de comisiones al cerrar el corte.
+     * Contrato y semántica completos (incluido por qué `status` NO tiene default y por qué
+     * `callerService` es obligatorio) → `IRetailOrgBusinessApi.listSellers`.
+     *
+     * ⚠️ Es el único método de este publisher con el `retailerId` en el QUERY y no anidado en el
+     * path: el caller no está validando un recurso, está pidiendo una colección entera.
+     */
+    async listSellers(
+        retailerId: string,
+        tenantId: string,
+        callerService: string,
+        status?: RetailUserStatusEnum,
+    ): Promise<StandardResponse<PrivateSellerListResponse>> {
+        // `URLSearchParams` en vez de concatenar: `status` es opcional y armar el `&status=` a mano
+        // deja un `&status=undefined` en cuanto alguien se distrae.
+        const query = new URLSearchParams({ retailerId, tenantId, callerService });
+        if (status) query.set("status", status);
+        return await this.httpRequest.get(`${this.baseUrl}/private/sellers?${query.toString()}`);
+    }
 }

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

@@ -4,6 +4,8 @@ import {
     StoreValidationDto,
     RetailUserValidationDto,
     CollectorValidationDto,
+    PrivateSellerListResponse,
+    RetailUserStatusEnum,
 } from "@fiado/type-kit/bin/retailOrg/index.js";
 
 /**
@@ -133,4 +135,45 @@ export interface IRetailOrgBusinessApi {
         retailerId: string,
         tenantId: string,
     ): Promise<StandardResponse<CollectorValidationDto[]>>;
+
+    /**
+     * `GET /private/sellers?retailerId=…` (SureKeep F3) — el **padrón de vendedores** de una cadena.
+     *
+     * ── 🔴 Por qué este método existe ────────────────────────────────────────────────────────────
+     * Lo consume el **motor de comisiones** al cerrar el corte del periodo, para saber a quién hay
+     * que pagarle y abrir una fila de devengo por cada uno. **Sin esta lista el fan-out del cierre
+     * no arranca.** Publicarlo acá es lo que evita que el motor caiga en `DIRECT_HTTP` (antipatrón
+     * duro): entre lambdas de Fiado la comunicación va SIEMPRE por `@fiado/api-invoker`.
+     *
+     * Devuelve el shape mínimo —`sellerId`, `displayName`, `homeStoreId`, `commissionTier`,
+     * `status`— **sin PII de contacto**: nada de teléfono ni `cognitoSub`. `commissionTier` no es
+     * adorno: es lo que el motor usa para resolver CUÁNTO le toca a cada quien según el plan vigente.
+     *
+     * Excluye a los COBRADORES (`commissionTier === 'collector'`), que tienen su propio método
+     * (`listActiveCollectorsByRetailer`) — la cobranza es del otro dominio.
+     *
+     * ── ⚠️ `status` NO tiene default ─────────────────────────────────────────────────────────────
+     * Omitirlo devuelve **TODOS** los estados, no solo los activos. Es deliberado: un vendedor dado
+     * de baja el día 20 **sí tiene comisión** por lo que vendió hasta el 19, y un default `ACTIVE`
+     * lo perdería en silencio sin dejar ninguna forma de pedir el padrón completo. Si el motor
+     * quiere solo activos, que lo diga explícito.
+     *
+     * ── `callerService`: quién exportó la nómina ─────────────────────────────────────────────────
+     * El endpoint es `Feature.ANONIMUS` (sin token de usuario), así que **no hay `actorId`** al que
+     * atribuirle la lectura — y esto exporta la nómina completa de una cadena en una sola llamada.
+     * El lambda destino registra el acceso en `SharedPiiAccessLog_GT` y usa este valor para saber
+     * QUIÉN lo pidió. Si se omite, el registro queda como `m2m:unknown` (con WARN en CloudWatch);
+     * **no lo omitas**: es la única traza que existe de una exportación masiva de datos de empleados.
+     *
+     * @throws `404 RETAILER_NOT_FOUND` si el retailer no existe en ese silo. Un `[]` no distinguiría
+     *   "esta cadena no tiene vendedores" de "preguntaste por una cadena que no existe", y lo segundo
+     *   cerraría el corte sin devengos sin que nadie se entere hasta el día de pago.
+     * @throws `400 VALIDATION_ERROR` si `retailerId` no es un ULID · `400 UNKNOWN_TENANT` sin `tenantId`.
+     */
+    listSellers(
+        retailerId: string,
+        tenantId: string,
+        callerService: string,
+        status?: RetailUserStatusEnum,
+    ): Promise<StandardResponse<PrivateSellerListResponse>>;
 }