@fiado/api-invoker 5.142.0 → 5.144.0

package/bin/platformRbac/api/PlatformRbacBusinessApi.d.ts

@@ -39,7 +39,7 @@ export default class PlatformRbacBusinessApi implements IPlatformRbacBusinessApi
     listLevelEntities(tenantId: string, level: PermissionScope, parentId?: string): Promise<APIGatewayProxyResultBody<ListLevelEntitiesResponse>>;
     /** GET /internal/tenants/{tenantId}/levels/{level}/entities/{id} — detalle de un grupo. */
     getLevelEntity(tenantId: string, level: PermissionScope, id: string): Promise<APIGatewayProxyResultBody<LevelEntityResponse>>;
-    /** PUT /internal/tenants/{tenantId}/levels/{level}/entities/{id} — renombra un grupo. */
+    /** PUT /internal/tenants/{tenantId}/levels/{level}/entities/{id} — renombra un grupo o lo mueve de padre con `parentId`. */
     updateLevelEntity(tenantId: string, level: PermissionScope, id: string, input: UpdateLevelEntityRequest): Promise<APIGatewayProxyResultBody<LevelEntityResponse>>;
     /** DELETE /internal/tenants/{tenantId}/levels/{level}/entities/{id} — borra un grupo. El `actedBy` viaja en el cuerpo. */
     deleteLevelEntity(tenantId: string, level: PermissionScope, id: string, input: DeleteLevelEntityRequest): Promise<APIGatewayProxyResultBody<DeleteLevelEntityResponse>>;

package/bin/platformRbac/api/PlatformRbacBusinessApi.js

@@ -111,7 +111,7 @@ let PlatformRbacBusinessApi = class PlatformRbacBusinessApi {
         const url = `${this._levelEntitiesUrl(tenantId, level)}/${encodeURIComponent(id)}`;
         return await this.httpRequest.get(url);
     }
-    /** PUT /internal/tenants/{tenantId}/levels/{level}/entities/{id} — renombra un grupo. */
+    /** PUT /internal/tenants/{tenantId}/levels/{level}/entities/{id} — renombra un grupo o lo mueve de padre con `parentId`. */
     async updateLevelEntity(tenantId, level, id, input) {
         const url = `${this._levelEntitiesUrl(tenantId, level)}/${encodeURIComponent(id)}`;
         return await this.httpRequest.put(url, input);

package/bin/platformRbac/api/interfaces/IPlatformRbacBusinessApi.d.ts

@@ -82,7 +82,7 @@ export interface IPlatformRbacBusinessApi {
     listLevelEntities(tenantId: string, level: PermissionScope, parentId?: string): Promise<APIGatewayProxyResultBody<ListLevelEntitiesResponse>>;
     /** GET /internal/tenants/{tenantId}/levels/{level}/entities/{id} — detalle de un grupo. */
     getLevelEntity(tenantId: string, level: PermissionScope, id: string): Promise<APIGatewayProxyResultBody<LevelEntityResponse>>;
-    /** PUT /internal/tenants/{tenantId}/levels/{level}/entities/{id} — renombra un grupo. */
+    /** PUT /internal/tenants/{tenantId}/levels/{level}/entities/{id} — renombra un grupo o lo mueve de padre con `parentId`. */
     updateLevelEntity(tenantId: string, level: PermissionScope, id: string, input: UpdateLevelEntityRequest): Promise<APIGatewayProxyResultBody<LevelEntityResponse>>;
     /** DELETE /internal/tenants/{tenantId}/levels/{level}/entities/{id} — borra un grupo. El `actedBy` viaja en el cuerpo. */
     deleteLevelEntity(tenantId: string, level: PermissionScope, id: string, input: DeleteLevelEntityRequest): Promise<APIGatewayProxyResultBody<DeleteLevelEntityResponse>>;

package/bin/retailCatalog/api/RetailCatalogBusinessApi.d.ts

@@ -3,7 +3,7 @@ import { StandardResponse } from "@fiado/gateway-adapter";
 import type { GetStoreStockCatalogResponse, HoldStockRequest, HoldStockResponse, InventoryLensQuery, InventoryLensResponse, ReleaseStockRequest, ReleaseStockResponse, RenewReservationsRequest, RenewReservationsResponse, ReserveStockRequest, ReserveStockResponse, ReturnStockRequest, ReturnStockResponse, SellStockRequest, SellStockResponse, SuggestPiecesQuery, SuggestPiecesResponse, SyncInventoryRequest, SyncInventoryResponse, ValidateProductResponse, StoreCatalogItem as StockCatalogItem } from "@fiado/type-kit/bin/retailCatalog/index.js";
 import type { PaginatedResult } from "@fiado/type-kit/bin/retailOrg/index.js";
 import type { ApplyInventoryEventRequest, ApplyInventoryEventResponse, ApplyProductEventRequest, ApplyProductEventResponse } from "@fiado/type-kit/bin/retailIntegration/index.js";
-import { IRetailCatalogBusinessApi, ProductsByRetailersResponse, ReleaseReservationBody, ReserveInventoryBody, ReserveInventoryResult, SellInventoryBody, StoreCatalogItem } from "./interfaces/IRetailCatalogBusinessApi.js";
+import { IRetailCatalogBusinessApi, ProductsByRetailersResponse, ReleaseReservationBody, ReserveInventoryBody, ReserveInventoryResult, SellInventoryInput, StoreCatalogItem } from "./interfaces/IRetailCatalogBusinessApi.js";
 /**
  * Publisher HTTP del lambda `retail-catalog-business` (SureKeep Fase 1, pista Retail) para sus
  * endpoints privados del ciclo de venta del IMEI. Contrato y semántica completos →
@@ -26,7 +26,7 @@ export default class RetailCatalogBusinessApi implements IRetailCatalogBusinessA
     validateProduct(retailerId: string, sku: string, issuer: string): Promise<StandardResponse<ValidateProductResponse>>;
     getProductsByRetailers(retailerIds: string[], tenantId: string): Promise<StandardResponse<ProductsByRetailersResponse>>;
     reserveInventory(imei: string, body: ReserveInventoryBody, issuer: string): Promise<StandardResponse<ReserveInventoryResult>>;
-    sellInventory(imei: string, body: SellInventoryBody, issuer: string): Promise<StandardResponse<void>>;
+    sellInventory(imei: string, body: SellInventoryInput, issuer: string): Promise<StandardResponse<void>>;
     releaseInventory(imei: string, body: ReleaseReservationBody, issuer: string): Promise<StandardResponse<void>>;
     returnInventory(imei: string, issuer: string): Promise<StandardResponse<void>>;
     /** URL de una ruta de tienda con `tenantId` y los parámetros extra en query. */

package/bin/retailCatalog/api/RetailCatalogBusinessApi.js

@@ -60,7 +60,9 @@ let RetailCatalogBusinessApi = class RetailCatalogBusinessApi {
     }
     async sellInventory(imei, body, issuer) {
         const url = `${this.baseUrl}/private/inventory/${encodeURIComponent(imei)}/sell`;
-        return await this.httpRequest.put(url, body, this.tenantHeader(issuer));
+        const { saleId, ...rest } = body;
+        const payload = saleId === undefined ? rest : { ...rest, saleId };
+        return await this.httpRequest.put(url, payload, this.tenantHeader(issuer));
     }
     async releaseInventory(imei, body, issuer) {
         const url = `${this.baseUrl}/private/inventory/${encodeURIComponent(imei)}/release`;

package/bin/retailCatalog/api/interfaces/IRetailCatalogBusinessApi.d.ts

@@ -1,5 +1,5 @@
 import { StandardResponse } from "@fiado/gateway-adapter";
-import type { GetStoreStockCatalogResponse, HoldStockRequest, HoldStockResponse, InventoryLensQuery, InventoryLensResponse, MdmLockModeEnum, MdmProviderEnum, ReleaseStockRequest, ReleaseStockResponse, RenewReservationsRequest, RenewReservationsResponse, ReserveStockRequest, ReserveStockResponse, ReturnStockRequest, ReturnStockResponse, SellStockRequest, SellStockResponse, SuggestPiecesQuery, SuggestPiecesResponse, SyncInventoryRequest, StoreCatalogItem as StockCatalogItem, SyncInventoryResponse, ValidateProductResponse } from "@fiado/type-kit/bin/retailCatalog/index.js";
+import type { GetStoreStockCatalogResponse, HoldStockRequest, HoldStockResponse, InventoryLensQuery, InventoryLensResponse, MdmLockModeEnum, MdmProviderEnum, ReleaseStockRequest, ReleaseStockResponse, RenewReservationsRequest, RenewReservationsResponse, ReserveStockRequest, ReserveStockResponse, ReturnStockRequest, ReturnStockResponse, SellStockRequest, SellStockResponse, SellInventoryRequest, SuggestPiecesQuery, SuggestPiecesResponse, SyncInventoryRequest, StoreCatalogItem as StockCatalogItem, SyncInventoryResponse, ValidateProductResponse } from "@fiado/type-kit/bin/retailCatalog/index.js";
 import type { PaginatedResult } from "@fiado/type-kit/bin/retailOrg/index.js";
 import type { ApplyInventoryEventRequest, ApplyInventoryEventResponse, ApplyProductEventRequest, ApplyProductEventResponse } from "@fiado/type-kit/bin/retailIntegration/index.js";
 /**
@@ -93,11 +93,12 @@ export interface ReserveInventoryBody {
     sku: string;
     sessionId: string;
 }
-/** Body de PUT `/private/inventory/{imei}/sell` (DEC-020 del destino: `customerId` puebla `soldToCustomerId`). */
-export interface SellInventoryBody {
-    sessionId: string;
-    customerId: string;
-}
+/** Body de PUT `/private/inventory/{imei}/sell`; `saleId` opcional mientras el wizard de main no lo mande (catalog lo exige en runtime). */
+export type SellInventoryInput = Omit<SellInventoryRequest, 'saleId'> & {
+    saleId?: string;
+};
+/** Alias de `SellInventoryInput`; se conserva por compatibilidad con consumidores. */
+export type SellInventoryBody = SellInventoryInput;
 /** Body de PUT `/private/inventory/{imei}/release` (DEC-018 del destino: verifica titularidad de la sesión). */
 export interface ReleaseReservationBody {
     sessionId: string;
@@ -149,7 +150,7 @@ export interface IRetailCatalogBusinessApi {
     /** PUT `/private/inventory/{imei}/reserve` — reserva atómica del IMEI para una sesión (AVAILABLE → RESERVED). */
     reserveInventory(imei: string, body: ReserveInventoryBody, issuer: string): Promise<StandardResponse<ReserveInventoryResult>>;
     /** PUT `/private/inventory/{imei}/sell` — vende el IMEI (RESERVED → SOLD). */
-    sellInventory(imei: string, body: SellInventoryBody, issuer: string): Promise<StandardResponse<void>>;
+    sellInventory(imei: string, body: SellInventoryInput, issuer: string): Promise<StandardResponse<void>>;
     /** PUT `/private/inventory/{imei}/release` — libera la reserva (RESERVED → AVAILABLE, titularidad de la sesión). */
     releaseInventory(imei: string, body: ReleaseReservationBody, issuer: string): Promise<StandardResponse<void>>;
     /** PUT `/private/inventory/{imei}/return` — devuelve el IMEI vendido al stock (SOLD → AVAILABLE, sin body). */

package/bin/retailCustomer/api/RetailCustomerBusinessApi.js

@@ -72,6 +72,10 @@ let RetailCustomerBusinessApi = class RetailCustomerBusinessApi {
         // El cursor viaja tal cual lo entregó el destino: componerlo o re-codificarlo lo rompe.
         if (query.nextToken)
             params.set("nextToken", query.nextToken);
+        if (query.retailerId)
+            params.set("retailerId", query.retailerId);
+        if (query.originStoreId)
+            params.set("originStoreId", query.originStoreId);
         const url = `${this.baseUrl}/private/customers?${params.toString()}`;
         return await this.httpRequest.get(url);
     }

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

@@ -8,6 +8,10 @@ export interface CustomersPageQuery {
     limit?: number;
     /** Cursor opaco de la página anterior. Ausente = primera página. */
     nextToken?: string;
+    /** Solo los clientes de esa cadena. */
+    retailerId?: string;
+    /** Solo los clientes dados de alta en esa tienda; va junto con `retailerId`. */
+    originStoreId?: string;
 }
 /**
  * Lo mínimo para pintar el renglón de un cliente. `fullName: null` significa que el cliente existe

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

@@ -146,8 +146,9 @@ export interface IRetailCustomerBusinessApi {
      */
     getCustomersBatch(payload: CustomersBatchRequest, tenantId: string): Promise<StandardResponse<CustomersBatchResponse>>;
     /**
-     * GET /private/customers?limit&nextToken&tenantId= — UNA página del padrón de clientes del
-     * tenant, del alta más reciente a la más vieja. Es el listado que alimenta las tablas de
+     * GET /private/customers?limit&nextToken&retailerId&originStoreId&tenantId= — UNA página del
+     * padrón de clientes del tenant, del alta más reciente a la más vieja. `retailerId` y
+     * `originStoreId` son filtros opcionales; sin ellos es el padrón completo del tenant. Es el listado que alimenta las tablas de
      * backoffice: una sola Query sobre el GSI de listado, sin fan-out por negocio.
      *
      * `nextToken` es OPACO: se pasea tal cual, no se compone ni se re-codifica. Ausente en la

package/bin/retailIntegration/api/RetailIntegrationConnectorApi.d.ts

@@ -1,6 +1,6 @@
 import type { IHttpRequest } from "@fiado/http-client";
 import { StandardResponse } from "@fiado/gateway-adapter";
-import type { GetRetailInventoryRequest, GetRetailInventoryResponse, ListRetailCatalogRequest, ListRetailCatalogResponse, ListRetailStoresRequest, ListRetailStoresResponse, ListRetailUsersRequest, ListRetailUsersResponse, RegisterRetailSaleRequest, RegisterRetailSaleResponse, RetailSystemSale } from "@fiado/type-kit/bin/retailIntegration/index.js";
+import type { CancelRetailSaleRequest, CancelRetailSaleResponse, CheckRetailInventoryRequest, CheckRetailInventoryResponse, GetRetailInventoryRequest, GetRetailInventoryResponse, ListRetailCatalogRequest, ListRetailCatalogResponse, ListRetailStoresRequest, ListRetailStoresResponse, ListRetailUsersRequest, ListRetailUsersResponse, RegisterRetailSaleRequest, RegisterRetailSaleResponse, RetailSystemSale, RetailTenantQuery } from "@fiado/type-kit/bin/retailIntegration/index.js";
 import { IRetailIntegrationConnectorApi } from "./interfaces/IRetailIntegrationConnectorApi.js";
 /** Publisher de la salida privada de `retail-integration-connector`. */
 export default class RetailIntegrationConnectorApi implements IRetailIntegrationConnectorApi {
@@ -12,6 +12,10 @@ export default class RetailIntegrationConnectorApi implements IRetailIntegration
     getRetailInventory(request: GetRetailInventoryRequest): Promise<StandardResponse<GetRetailInventoryResponse>>;
     listRetailUsers(request: ListRetailUsersRequest): Promise<StandardResponse<ListRetailUsersResponse>>;
     registerRetailSale(request: RegisterRetailSaleRequest, sale: RetailSystemSale): Promise<StandardResponse<RegisterRetailSaleResponse>>;
+    cancelRetailSale(query: RetailTenantQuery, cancellation: CancelRetailSaleRequest): Promise<StandardResponse<CancelRetailSaleResponse>>;
+    checkRetailInventory(request: CheckRetailInventoryRequest): Promise<StandardResponse<CheckRetailInventoryResponse>>;
     private getWithTimeout;
+    private tenantQuery;
+    private listQuery;
     private toQuery;
 }

package/bin/retailIntegration/api/RetailIntegrationConnectorApi.js

@@ -13,6 +13,8 @@ var __param = (this && this.__param) || function (paramIndex, decorator) {
 import { inject, injectable } from "inversify";
 /** Mayor que el Timeout de 10 s del connector, para no cortar una venta en vuelo. */
 const RETAIL_INTEGRATION_CONNECTOR_TIMEOUT_MS = 12000;
+/** Mayor que los 2.5 s del connector hacia el retailer; la consulta en vivo no debe frenar la venta. */
+const RETAIL_LIVE_CHECK_TIMEOUT_MS = 3000;
 /** Publisher de la salida privada de `retail-integration-connector`. */
 let RetailIntegrationConnectorApi = class RetailIntegrationConnectorApi {
     httpRequest;
@@ -22,42 +24,66 @@ let RetailIntegrationConnectorApi = class RetailIntegrationConnectorApi {
     }
     async listRetailStores(request) {
         return await this.getWithTimeout("/private/retail/stores", {
-            tenantId: request.tenantId,
+            ...this.listQuery(request),
             limit: request.limit,
             nextToken: request.nextToken,
         });
     }
     async listRetailCatalog(request) {
         return await this.getWithTimeout("/private/retail/catalog", {
-            tenantId: request.tenantId,
+            ...this.listQuery(request),
             limit: request.limit,
             nextToken: request.nextToken,
         });
     }
     async getRetailInventory(request) {
         return await this.getWithTimeout("/private/retail/inventory", {
-            tenantId: request.tenantId,
+            ...this.tenantQuery(request),
             storeId: request.storeId,
+            runId: request.runId,
         });
     }
     async listRetailUsers(request) {
         return await this.getWithTimeout("/private/retail/users", {
-            tenantId: request.tenantId,
+            ...this.tenantQuery(request),
             storeId: request.storeId,
+            runId: request.runId,
             limit: request.limit,
             nextToken: request.nextToken,
         });
     }
     async registerRetailSale(request, sale) {
-        const url = `${this.baseUrl}/private/retail/sales?${this.toQuery({ tenantId: request.tenantId })}`;
+        const url = `${this.baseUrl}/private/retail/sales?${this.toQuery(this.tenantQuery(request))}`;
         return await this.httpRequest.post(url, sale, {}, undefined, false, {
             timeout: RETAIL_INTEGRATION_CONNECTOR_TIMEOUT_MS,
         });
     }
+    async cancelRetailSale(query, cancellation) {
+        const url = `${this.baseUrl}/private/retail/sales/cancel?${this.toQuery(this.tenantQuery(query))}`;
+        return await this.httpRequest.post(url, cancellation, {}, undefined, false, {
+            timeout: RETAIL_INTEGRATION_CONNECTOR_TIMEOUT_MS,
+        });
+    }
+    async checkRetailInventory(request) {
+        const fields = {
+            ...this.tenantQuery(request),
+            storeId: request.storeId,
+            identifiers: request.identifiers.join(","),
+            sessionId: request.sessionId,
+        };
+        return await this.getWithTimeout("/private/retail/inventory/live-check", fields, RETAIL_LIVE_CHECK_TIMEOUT_MS);
+    }
     // GET con timeout propio; nunca `enableTimeout`, que tomaría el timeout corto del consumidor.
-    async getWithTimeout(path, fields) {
+    async getWithTimeout(path, fields, timeout = RETAIL_INTEGRATION_CONNECTOR_TIMEOUT_MS) {
         const url = `${this.baseUrl}${path}?${this.toQuery(fields)}`;
-        return await this.httpRequest.get(url, {}, {}, undefined, { timeout: RETAIL_INTEGRATION_CONNECTOR_TIMEOUT_MS }, false);
+        return await this.httpRequest.get(url, {}, {}, undefined, { timeout }, false);
+    }
+    // El connector coteja tenantId y retailerId contra el secreto del tenant.
+    tenantQuery(query) {
+        return { tenantId: query.tenantId, retailerId: query.retailerId };
+    }
+    listQuery(query) {
+        return { ...this.tenantQuery(query), runId: query.runId };
     }
     toQuery(fields) {
         const params = new URLSearchParams();

package/bin/retailIntegration/api/interfaces/IRetailIntegrationConnectorApi.d.ts

@@ -1,5 +1,5 @@
 import { StandardResponse } from "@fiado/gateway-adapter";
-import type { GetRetailInventoryRequest, GetRetailInventoryResponse, ListRetailCatalogRequest, ListRetailCatalogResponse, ListRetailStoresRequest, ListRetailStoresResponse, ListRetailUsersRequest, ListRetailUsersResponse, RegisterRetailSaleRequest, RegisterRetailSaleResponse, RetailSystemSale } from "@fiado/type-kit/bin/retailIntegration/index.js";
+import type { CancelRetailSaleRequest, CancelRetailSaleResponse, CheckRetailInventoryRequest, CheckRetailInventoryResponse, GetRetailInventoryRequest, GetRetailInventoryResponse, ListRetailCatalogRequest, ListRetailCatalogResponse, ListRetailStoresRequest, ListRetailStoresResponse, ListRetailUsersRequest, ListRetailUsersResponse, RegisterRetailSaleRequest, RegisterRetailSaleResponse, RetailSystemSale, RetailTenantQuery } from "@fiado/type-kit/bin/retailIntegration/index.js";
 /**
  * Salida privada de `retail-integration-connector` hacia el sistema del retailer del tenant.
  * Env var del consumidor: `RETAIL_INTEGRATION_CONNECTOR_URL: '{{resolve:ssm:retail-integration-connector}}'`.
@@ -15,4 +15,8 @@ export interface IRetailIntegrationConnectorApi {
     listRetailUsers(request: ListRetailUsersRequest): Promise<StandardResponse<ListRetailUsersResponse>>;
     /** `POST /private/retail/sales` — registra la venta; ante timeout o 502, reintenta con el mismo `saleId`. */
     registerRetailSale(request: RegisterRetailSaleRequest, sale: RetailSystemSale): Promise<StandardResponse<RegisterRetailSaleResponse>>;
+    /** `POST /private/retail/sales/cancel` — cancela la venta con el mismo `saleId` del registro; 12 s. */
+    cancelRetailSale(query: RetailTenantQuery, cancellation: CancelRetailSaleRequest): Promise<StandardResponse<CancelRetailSaleResponse>>;
+    /** `GET /private/retail/inventory/live-check` — qué identificadores lista hoy la tienda; 3 s. */
+    checkRetailInventory(request: CheckRetailInventoryRequest): Promise<StandardResponse<CheckRetailInventoryResponse>>;
 }

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

@@ -2,7 +2,7 @@ import type { IHttpRequest } from "@fiado/http-client";
 import { StandardResponse } from "@fiado/gateway-adapter";
 import { RetailerValidationDto, StoreValidationDto, RetailUserValidationDto, CollectorValidationDto, PrivateSellerListResponse, PrivateGoalListResponse, GoalTargetTypeEnum, RetailUserStatusEnum, PrivateRetailUserWalletResponse } from "@fiado/type-kit/bin/retailOrg/index.js";
 import type { ApplyRetailUserEventRequest, ApplyRetailUserEventResponse, ApplyStoreEventRequest, ApplyStoreEventResponse } from "@fiado/type-kit/bin/retailIntegration/index.js";
-import { IRetailOrgBusinessApi, RetailerRosterStatusFilter, StoreRosterStatusFilter } from "./interfaces/IRetailOrgBusinessApi.js";
+import { IRetailOrgBusinessApi, RetailOrgRequestOptions, RetailerRosterStatusFilter, StoreRosterStatusFilter } from "./interfaces/IRetailOrgBusinessApi.js";
 /**
  * Publisher HTTP del lambda `retail-org-business` (componente 04 SureKeep Fase 1) para sus 9
  * endpoints privados de validación. Contrato y semántica completos → `IRetailOrgBusinessApi`.
@@ -27,8 +27,10 @@ export default class RetailOrgBusinessApi implements IRetailOrgBusinessApi {
      * qué `status` SÍ tiene default y por qué acá el estado es el CRUDO, sin cascada del padre)
      * → `IRetailOrgBusinessApi.listRetailers`.
      */
-    listRetailers(tenantId: string, status?: RetailerRosterStatusFilter): Promise<StandardResponse<RetailerValidationDto[]>>;
-    getRetailer(retailerId: string, tenantId: string): Promise<StandardResponse<RetailerValidationDto>>;
+    listRetailers(tenantId: string, status?: RetailerRosterStatusFilter, integrated?: boolean, options?: RetailOrgRequestOptions): Promise<StandardResponse<RetailerValidationDto[]>>;
+    getRetailer(retailerId: string, tenantId: string, options?: RetailOrgRequestOptions): Promise<StandardResponse<RetailerValidationDto>>;
+    /** Aplica el timeout solo si el caller lo pide; sin él, el GET queda igual que siempre. */
+    private getWithOptionalTimeout;
     getRetailerByStore(storeId: string, tenantId: string): Promise<StandardResponse<RetailerValidationDto>>;
     getStore(retailerId: string, storeId: string, tenantId: string): Promise<StandardResponse<StoreValidationDto>>;
     /**

package/bin/retailOrg/api/RetailOrgBusinessApi.js

@@ -37,17 +37,24 @@ let RetailOrgBusinessApi = class RetailOrgBusinessApi {
      * qué `status` SÍ tiene default y por qué acá el estado es el CRUDO, sin cascada del padre)
      * → `IRetailOrgBusinessApi.listRetailers`.
      */
-    async listRetailers(tenantId, status) {
-        // `URLSearchParams` en vez de concatenar: `status` es opcional y armar el `&status=` a mano
-        // deja un `&status=undefined` en cuanto alguien se distrae.
+    async listRetailers(tenantId, status, integrated, options) {
         const query = new URLSearchParams({ tenantId });
         if (status)
             query.set("status", status);
-        return await this.httpRequest.get(`${this.baseUrl}/private/retailers?${query.toString()}`);
+        if (integrated !== undefined)
+            query.set("integrated", String(integrated));
+        const url = `${this.baseUrl}/private/retailers?${query.toString()}`;
+        return await this.getWithOptionalTimeout(url, options);
     }
-    async getRetailer(retailerId, tenantId) {
+    async getRetailer(retailerId, tenantId, options) {
         const url = `${this.baseUrl}/private/retailers/${encodeURIComponent(retailerId)}?tenantId=${encodeURIComponent(tenantId)}`;
-        return await this.httpRequest.get(url);
+        return await this.getWithOptionalTimeout(url, options);
+    }
+    /** Aplica el timeout solo si el caller lo pide; sin él, el GET queda igual que siempre. */
+    async getWithOptionalTimeout(url, options) {
+        if (options?.timeoutMs === undefined)
+            return await this.httpRequest.get(url);
+        return await this.httpRequest.get(url, undefined, undefined, undefined, { timeout: options.timeoutMs });
     }
     async getRetailerByStore(storeId, tenantId) {
         const url = `${this.baseUrl}/private/retailers/by-store/${encodeURIComponent(storeId)}?tenantId=${encodeURIComponent(tenantId)}`;

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

@@ -1,6 +1,14 @@
 import { StandardResponse } from "@fiado/gateway-adapter";
 import { RetailerValidationDto, StoreValidationDto, RetailUserValidationDto, CollectorValidationDto, PrivateSellerListResponse, PrivateGoalListResponse, GoalTargetTypeEnum, RetailUserStatusEnum, RetailerStatusEnum, StoreStatusEnum, PrivateRetailUserWalletResponse } from "@fiado/type-kit/bin/retailOrg/index.js";
 import type { ApplyRetailUserEventRequest, ApplyRetailUserEventResponse, ApplyStoreEventRequest, ApplyStoreEventResponse } from "@fiado/type-kit/bin/retailIntegration/index.js";
+/** Timeout que el connector y el wizard pasan a `getRetailer`: cabe en los 3 s por evento del connector. */
+export declare const RETAIL_ORG_GET_RETAILER_TIMEOUT_MS = 1500;
+/** Timeout que el connector pasa a `listRetailers`: el padrón trae el árbol completo del silo. */
+export declare const RETAIL_ORG_LIST_RETAILERS_TIMEOUT_MS = 5000;
+/** Opciones por llamada. Sin `timeoutMs` no se aplica timeout propio. */
+export interface RetailOrgRequestOptions {
+    timeoutMs?: number;
+}
 /**
  * Filtro de `listStoresByRetailer`. `"ALL"` no es un estado de tienda: es la ausencia de filtro, y
  * va en el MISMO parámetro que los estados porque los dos hablan del mismo eje — un segundo flag
@@ -87,17 +95,23 @@ export interface IRetailOrgBusinessApi {
      * Devuelve `[]` si ningún retailer pasa el filtro. **No hay 404**: el silo siempre existe — lo
      * garantiza el `tenantId`, que es lo que resolvió el contexto del tenant.
      *
+     * `integrated = true` deja solo los retailers con la bandera de integración prendida; cada
+     * retailer trae `integrationSystem` e `integrationActivatedAt` cuando la tiene. Timeout opt-in vía
+     * `options.timeoutMs` (ver `RETAIL_ORG_LIST_RETAILERS_TIMEOUT_MS`).
+     *
      * @throws `400 RETAILER_STATUS_FILTER_INVALID` si `status` no es del catálogo ·
      *   `400 UNKNOWN_TENANT` sin `tenantId`.
      */
-    listRetailers(tenantId: string, status?: RetailerRosterStatusFilter): Promise<StandardResponse<RetailerValidationDto[]>>;
+    listRetailers(tenantId: string, status?: RetailerRosterStatusFilter, integrated?: boolean, options?: RetailOrgRequestOptions): Promise<StandardResponse<RetailerValidationDto[]>>;
     /**
      * GET /private/retailers/{retailerId} — valida que el retailer exista y devuelve su shape mínimo
-     * (id, name, type, status, parentId). `status` ya viene con la cascada aplicada (estado efectivo).
+     * (id, name, type, status, parentId) y la bandera de integración. `status` ya viene con la cascada
+     * aplicada (estado efectivo). Timeout opt-in vía `options.timeoutMs` (ver
+     * `RETAIL_ORG_GET_RETAILER_TIMEOUT_MS`).
      *
      * @throws si el retailer no existe (`404 RETAILER_NOT_FOUND`).
      */
-    getRetailer(retailerId: string, tenantId: string): Promise<StandardResponse<RetailerValidationDto>>;
+    getRetailer(retailerId: string, tenantId: string, options?: RetailOrgRequestOptions): Promise<StandardResponse<RetailerValidationDto>>;
     /**
      * GET /private/retailers/by-store/{storeId} — resuelve el retailer DUEÑO de una tienda teniendo
      * SOLO el `storeId`, sin conocer el retailer. Es el único privado que no va anidado, porque es el

package/bin/retailOrg/api/interfaces/IRetailOrgBusinessApi.js

@@ -1 +1,4 @@
-export {};
+/** Timeout que el connector y el wizard pasan a `getRetailer`: cabe en los 3 s por evento del connector. */
+export const RETAIL_ORG_GET_RETAILER_TIMEOUT_MS = 1500;
+/** Timeout que el connector pasa a `listRetailers`: el padrón trae el árbol completo del silo. */
+export const RETAIL_ORG_LIST_RETAILERS_TIMEOUT_MS = 5000;

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@fiado/api-invoker",
-  "version": "5.142.0",
+  "version": "5.144.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.14.0",
     "@fiado/http-client": "^2.0.1",
     "@fiado/logger": "^1.1.3",
-    "@fiado/type-kit": "^3.575.0",
+    "@fiado/type-kit": "^3.579.0",
     "dotenv": "^16.4.7"
   },
   "peerDependencies": {

package/src/platformRbac/api/PlatformRbacBusinessApi.ts

@@ -204,7 +204,7 @@ export default class PlatformRbacBusinessApi implements IPlatformRbacBusinessApi
         return await this.httpRequest.get(url);
     }
 
-    /** PUT /internal/tenants/{tenantId}/levels/{level}/entities/{id} — renombra un grupo. */
+    /** PUT /internal/tenants/{tenantId}/levels/{level}/entities/{id} — renombra un grupo o lo mueve de padre con `parentId`. */
     async updateLevelEntity(
         tenantId: string,
         level: PermissionScope,

package/src/platformRbac/api/interfaces/IPlatformRbacBusinessApi.ts

@@ -174,7 +174,7 @@ export interface IPlatformRbacBusinessApi {
         id: string,
     ): Promise<APIGatewayProxyResultBody<LevelEntityResponse>>;
 
-    /** PUT /internal/tenants/{tenantId}/levels/{level}/entities/{id} — renombra un grupo. */
+    /** PUT /internal/tenants/{tenantId}/levels/{level}/entities/{id} — renombra un grupo o lo mueve de padre con `parentId`. */
     updateLevelEntity(
         tenantId: string,
         level: PermissionScope,

package/src/retailCatalog/api/RetailCatalogBusinessApi.ts

@@ -41,7 +41,7 @@ import {
     ReserveInventoryBody,
     ReserveInventoryResult,
     RETAILER_PRODUCTS_BATCH_MAX,
-    SellInventoryBody,
+    SellInventoryInput,
     StoreCatalogItem,
 } from "./interfaces/IRetailCatalogBusinessApi.js";
 
@@ -114,9 +114,11 @@ export default class RetailCatalogBusinessApi implements IRetailCatalogBusinessA
         return await this.httpRequest.put(url, body, this.tenantHeader(issuer));
     }
 
-    async sellInventory(imei: string, body: SellInventoryBody, issuer: string): Promise<StandardResponse<void>> {
+    async sellInventory(imei: string, body: SellInventoryInput, issuer: string): Promise<StandardResponse<void>> {
         const url = `${this.baseUrl}/private/inventory/${encodeURIComponent(imei)}/sell`;
-        return await this.httpRequest.put(url, body, this.tenantHeader(issuer));
+        const { saleId, ...rest } = body;
+        const payload = saleId === undefined ? rest : { ...rest, saleId };
+        return await this.httpRequest.put(url, payload, this.tenantHeader(issuer));
     }
 
     async releaseInventory(imei: string, body: ReleaseReservationBody, issuer: string): Promise<StandardResponse<void>> {

package/src/retailCatalog/api/interfaces/IRetailCatalogBusinessApi.ts

@@ -17,6 +17,7 @@ import type {
     ReturnStockResponse,
     SellStockRequest,
     SellStockResponse,
+    SellInventoryRequest,
     SuggestPiecesQuery,
     SuggestPiecesResponse,
     SyncInventoryRequest,
@@ -137,11 +138,11 @@ export interface ReserveInventoryBody {
     sessionId: string;
 }
 
-/** Body de PUT `/private/inventory/{imei}/sell` (DEC-020 del destino: `customerId` puebla `soldToCustomerId`). */
-export interface SellInventoryBody {
-    sessionId: string;
-    customerId: string;
-}
+/** Body de PUT `/private/inventory/{imei}/sell`; `saleId` opcional mientras el wizard de main no lo mande (catalog lo exige en runtime). */
+export type SellInventoryInput = Omit<SellInventoryRequest, 'saleId'> & { saleId?: string };
+
+/** Alias de `SellInventoryInput`; se conserva por compatibilidad con consumidores. */
+export type SellInventoryBody = SellInventoryInput;
 
 /** Body de PUT `/private/inventory/{imei}/release` (DEC-018 del destino: verifica titularidad de la sesión). */
 export interface ReleaseReservationBody {
@@ -206,7 +207,7 @@ export interface IRetailCatalogBusinessApi {
     reserveInventory(imei: string, body: ReserveInventoryBody, issuer: string): Promise<StandardResponse<ReserveInventoryResult>>;
 
     /** PUT `/private/inventory/{imei}/sell` — vende el IMEI (RESERVED → SOLD). */
-    sellInventory(imei: string, body: SellInventoryBody, issuer: string): Promise<StandardResponse<void>>;
+    sellInventory(imei: string, body: SellInventoryInput, issuer: string): Promise<StandardResponse<void>>;
 
     /** PUT `/private/inventory/{imei}/release` — libera la reserva (RESERVED → AVAILABLE, titularidad de la sesión). */
     releaseInventory(imei: string, body: ReleaseReservationBody, issuer: string): Promise<StandardResponse<void>>;

package/src/retailCustomer/api/RetailCustomerBusinessApi.ts

@@ -124,6 +124,8 @@ export default class RetailCustomerBusinessApi implements IRetailCustomerBusines
         if (query.limit !== undefined) params.set("limit", String(query.limit));
         // El cursor viaja tal cual lo entregó el destino: componerlo o re-codificarlo lo rompe.
         if (query.nextToken) params.set("nextToken", query.nextToken);
+        if (query.retailerId) params.set("retailerId", query.retailerId);
+        if (query.originStoreId) params.set("originStoreId", query.originStoreId);
         const url = `${this.baseUrl}/private/customers?${params.toString()}`;
         return await this.httpRequest.get(url);
     }

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

@@ -9,6 +9,10 @@ export interface CustomersPageQuery {
     limit?: number;
     /** Cursor opaco de la página anterior. Ausente = primera página. */
     nextToken?: string;
+    /** Solo los clientes de esa cadena. */
+    retailerId?: string;
+    /** Solo los clientes dados de alta en esa tienda; va junto con `retailerId`. */
+    originStoreId?: string;
 }
 
 /**

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

@@ -202,8 +202,9 @@ export interface IRetailCustomerBusinessApi {
     ): Promise<StandardResponse<CustomersBatchResponse>>;
 
     /**
-     * GET /private/customers?limit&nextToken&tenantId= — UNA página del padrón de clientes del
-     * tenant, del alta más reciente a la más vieja. Es el listado que alimenta las tablas de
+     * GET /private/customers?limit&nextToken&retailerId&originStoreId&tenantId= — UNA página del
+     * padrón de clientes del tenant, del alta más reciente a la más vieja. `retailerId` y
+     * `originStoreId` son filtros opcionales; sin ellos es el padrón completo del tenant. Es el listado que alimenta las tablas de
      * backoffice: una sola Query sobre el GSI de listado, sin fan-out por negocio.
      *
      * `nextToken` es OPACO: se pasea tal cual, no se compone ni se re-codifica. Ausente en la

package/src/retailIntegration/api/RetailIntegrationConnectorApi.ts

@@ -2,6 +2,10 @@ import { inject, injectable } from "inversify";
 import type { IHttpRequest } from "@fiado/http-client";
 import { StandardResponse } from "@fiado/gateway-adapter";
 import type {
+    CancelRetailSaleRequest,
+    CancelRetailSaleResponse,
+    CheckRetailInventoryRequest,
+    CheckRetailInventoryResponse,
     GetRetailInventoryRequest,
     GetRetailInventoryResponse,
     ListRetailCatalogRequest,
@@ -12,13 +16,18 @@ import type {
     ListRetailUsersResponse,
     RegisterRetailSaleRequest,
     RegisterRetailSaleResponse,
+    RetailListQuery,
     RetailSystemSale,
+    RetailTenantQuery,
 } from "@fiado/type-kit/bin/retailIntegration/index.js";
 import { IRetailIntegrationConnectorApi } from "./interfaces/IRetailIntegrationConnectorApi.js";
 
 /** Mayor que el Timeout de 10 s del connector, para no cortar una venta en vuelo. */
 const RETAIL_INTEGRATION_CONNECTOR_TIMEOUT_MS = 12000;
 
+/** Mayor que los 2.5 s del connector hacia el retailer; la consulta en vivo no debe frenar la venta. */
+const RETAIL_LIVE_CHECK_TIMEOUT_MS = 3000;
+
 type QueryFields = Record<string, string | number | undefined>;
 
 /** Publisher de la salida privada de `retail-integration-connector`. */
@@ -30,7 +39,7 @@ export default class RetailIntegrationConnectorApi implements IRetailIntegration
 
     async listRetailStores(request: ListRetailStoresRequest): Promise<StandardResponse<ListRetailStoresResponse>> {
         return await this.getWithTimeout("/private/retail/stores", {
-            tenantId: request.tenantId,
+            ...this.listQuery(request),
             limit: request.limit,
             nextToken: request.nextToken,
         });
@@ -38,7 +47,7 @@ export default class RetailIntegrationConnectorApi implements IRetailIntegration
 
     async listRetailCatalog(request: ListRetailCatalogRequest): Promise<StandardResponse<ListRetailCatalogResponse>> {
         return await this.getWithTimeout("/private/retail/catalog", {
-            tenantId: request.tenantId,
+            ...this.listQuery(request),
             limit: request.limit,
             nextToken: request.nextToken,
         });
@@ -46,15 +55,17 @@ export default class RetailIntegrationConnectorApi implements IRetailIntegration
 
     async getRetailInventory(request: GetRetailInventoryRequest): Promise<StandardResponse<GetRetailInventoryResponse>> {
         return await this.getWithTimeout("/private/retail/inventory", {
-            tenantId: request.tenantId,
+            ...this.tenantQuery(request),
             storeId: request.storeId,
+            runId: request.runId,
         });
     }
 
     async listRetailUsers(request: ListRetailUsersRequest): Promise<StandardResponse<ListRetailUsersResponse>> {
         return await this.getWithTimeout("/private/retail/users", {
-            tenantId: request.tenantId,
+            ...this.tenantQuery(request),
             storeId: request.storeId,
+            runId: request.runId,
             limit: request.limit,
             nextToken: request.nextToken,
         });
@@ -64,16 +75,51 @@ export default class RetailIntegrationConnectorApi implements IRetailIntegration
         request: RegisterRetailSaleRequest,
         sale: RetailSystemSale,
     ): Promise<StandardResponse<RegisterRetailSaleResponse>> {
-        const url = `${this.baseUrl}/private/retail/sales?${this.toQuery({ tenantId: request.tenantId })}`;
+        const url = `${this.baseUrl}/private/retail/sales?${this.toQuery(this.tenantQuery(request))}`;
         return await this.httpRequest.post(url, sale, {}, undefined, false, {
             timeout: RETAIL_INTEGRATION_CONNECTOR_TIMEOUT_MS,
         });
     }
 
+    async cancelRetailSale(
+        query: RetailTenantQuery,
+        cancellation: CancelRetailSaleRequest,
+    ): Promise<StandardResponse<CancelRetailSaleResponse>> {
+        const url = `${this.baseUrl}/private/retail/sales/cancel?${this.toQuery(this.tenantQuery(query))}`;
+        return await this.httpRequest.post(url, cancellation, {}, undefined, false, {
+            timeout: RETAIL_INTEGRATION_CONNECTOR_TIMEOUT_MS,
+        });
+    }
+
+    async checkRetailInventory(
+        request: CheckRetailInventoryRequest,
+    ): Promise<StandardResponse<CheckRetailInventoryResponse>> {
+        const fields = {
+            ...this.tenantQuery(request),
+            storeId: request.storeId,
+            identifiers: request.identifiers.join(","),
+            sessionId: request.sessionId,
+        };
+        return await this.getWithTimeout("/private/retail/inventory/live-check", fields, RETAIL_LIVE_CHECK_TIMEOUT_MS);
+    }
+
     // GET con timeout propio; nunca `enableTimeout`, que tomaría el timeout corto del consumidor.
-    private async getWithTimeout<T>(path: string, fields: QueryFields): Promise<StandardResponse<T>> {
+    private async getWithTimeout<T>(
+        path: string,
+        fields: QueryFields,
+        timeout = RETAIL_INTEGRATION_CONNECTOR_TIMEOUT_MS,
+    ): Promise<StandardResponse<T>> {
         const url = `${this.baseUrl}${path}?${this.toQuery(fields)}`;
-        return await this.httpRequest.get(url, {}, {}, undefined, { timeout: RETAIL_INTEGRATION_CONNECTOR_TIMEOUT_MS }, false);
+        return await this.httpRequest.get(url, {}, {}, undefined, { timeout }, false);
+    }
+
+    // El connector coteja tenantId y retailerId contra el secreto del tenant.
+    private tenantQuery(query: RetailTenantQuery): QueryFields {
+        return { tenantId: query.tenantId, retailerId: query.retailerId };
+    }
+
+    private listQuery(query: RetailListQuery): QueryFields {
+        return { ...this.tenantQuery(query), runId: query.runId };
     }
 
     private toQuery(fields: QueryFields): string {

package/src/retailIntegration/api/interfaces/IRetailIntegrationConnectorApi.ts

@@ -1,5 +1,9 @@
 import { StandardResponse } from "@fiado/gateway-adapter";
 import type {
+    CancelRetailSaleRequest,
+    CancelRetailSaleResponse,
+    CheckRetailInventoryRequest,
+    CheckRetailInventoryResponse,
     GetRetailInventoryRequest,
     GetRetailInventoryResponse,
     ListRetailCatalogRequest,
@@ -11,6 +15,7 @@ import type {
     RegisterRetailSaleRequest,
     RegisterRetailSaleResponse,
     RetailSystemSale,
+    RetailTenantQuery,
 } from "@fiado/type-kit/bin/retailIntegration/index.js";
 
 /**
@@ -35,4 +40,13 @@ export interface IRetailIntegrationConnectorApi {
         request: RegisterRetailSaleRequest,
         sale: RetailSystemSale,
     ): Promise<StandardResponse<RegisterRetailSaleResponse>>;
+
+    /** `POST /private/retail/sales/cancel` — cancela la venta con el mismo `saleId` del registro; 12 s. */
+    cancelRetailSale(
+        query: RetailTenantQuery,
+        cancellation: CancelRetailSaleRequest,
+    ): Promise<StandardResponse<CancelRetailSaleResponse>>;
+
+    /** `GET /private/retail/inventory/live-check` — qué identificadores lista hoy la tienda; 3 s. */
+    checkRetailInventory(request: CheckRetailInventoryRequest): Promise<StandardResponse<CheckRetailInventoryResponse>>;
 }

package/src/retailOrg/api/RetailOrgBusinessApi.ts

@@ -22,6 +22,7 @@ import type {
 } from "@fiado/type-kit/bin/retailIntegration/index.js";
 import {
     IRetailOrgBusinessApi,
+    RetailOrgRequestOptions,
     RetailerRosterStatusFilter,
     StoreRosterStatusFilter,
 } from "./interfaces/IRetailOrgBusinessApi.js";
@@ -55,20 +56,29 @@ export default class RetailOrgBusinessApi implements IRetailOrgBusinessApi {
     async listRetailers(
         tenantId: string,
         status?: RetailerRosterStatusFilter,
+        integrated?: boolean,
+        options?: RetailOrgRequestOptions,
     ): Promise<StandardResponse<RetailerValidationDto[]>> {
-        // `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({ tenantId });
         if (status) query.set("status", status);
-        return await this.httpRequest.get(`${this.baseUrl}/private/retailers?${query.toString()}`);
+        if (integrated !== undefined) query.set("integrated", String(integrated));
+        const url = `${this.baseUrl}/private/retailers?${query.toString()}`;
+        return await this.getWithOptionalTimeout(url, options);
     }
 
     async getRetailer(
         retailerId: string,
         tenantId: string,
+        options?: RetailOrgRequestOptions,
     ): Promise<StandardResponse<RetailerValidationDto>> {
         const url = `${this.baseUrl}/private/retailers/${encodeURIComponent(retailerId)}?tenantId=${encodeURIComponent(tenantId)}`;
-        return await this.httpRequest.get(url);
+        return await this.getWithOptionalTimeout(url, options);
+    }
+
+    /** Aplica el timeout solo si el caller lo pide; sin él, el GET queda igual que siempre. */
+    private async getWithOptionalTimeout<T>(url: string, options?: RetailOrgRequestOptions): Promise<StandardResponse<T>> {
+        if (options?.timeoutMs === undefined) return await this.httpRequest.get(url);
+        return await this.httpRequest.get(url, undefined, undefined, undefined, { timeout: options.timeoutMs });
     }
 
     async getRetailerByStore(

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

@@ -19,6 +19,17 @@ import type {
     ApplyStoreEventResponse,
 } from "@fiado/type-kit/bin/retailIntegration/index.js";
 
+/** Timeout que el connector y el wizard pasan a `getRetailer`: cabe en los 3 s por evento del connector. */
+export const RETAIL_ORG_GET_RETAILER_TIMEOUT_MS = 1500;
+
+/** Timeout que el connector pasa a `listRetailers`: el padrón trae el árbol completo del silo. */
+export const RETAIL_ORG_LIST_RETAILERS_TIMEOUT_MS = 5000;
+
+/** Opciones por llamada. Sin `timeoutMs` no se aplica timeout propio. */
+export interface RetailOrgRequestOptions {
+    timeoutMs?: number;
+}
+
 /**
  * Filtro de `listStoresByRetailer`. `"ALL"` no es un estado de tienda: es la ausencia de filtro, y
  * va en el MISMO parámetro que los estados porque los dos hablan del mismo eje — un segundo flag
@@ -107,23 +118,32 @@ export interface IRetailOrgBusinessApi {
      * Devuelve `[]` si ningún retailer pasa el filtro. **No hay 404**: el silo siempre existe — lo
      * garantiza el `tenantId`, que es lo que resolvió el contexto del tenant.
      *
+     * `integrated = true` deja solo los retailers con la bandera de integración prendida; cada
+     * retailer trae `integrationSystem` e `integrationActivatedAt` cuando la tiene. Timeout opt-in vía
+     * `options.timeoutMs` (ver `RETAIL_ORG_LIST_RETAILERS_TIMEOUT_MS`).
+     *
      * @throws `400 RETAILER_STATUS_FILTER_INVALID` si `status` no es del catálogo ·
      *   `400 UNKNOWN_TENANT` sin `tenantId`.
      */
     listRetailers(
         tenantId: string,
         status?: RetailerRosterStatusFilter,
+        integrated?: boolean,
+        options?: RetailOrgRequestOptions,
     ): Promise<StandardResponse<RetailerValidationDto[]>>;
 
     /**
      * GET /private/retailers/{retailerId} — valida que el retailer exista y devuelve su shape mínimo
-     * (id, name, type, status, parentId). `status` ya viene con la cascada aplicada (estado efectivo).
+     * (id, name, type, status, parentId) y la bandera de integración. `status` ya viene con la cascada
+     * aplicada (estado efectivo). Timeout opt-in vía `options.timeoutMs` (ver
+     * `RETAIL_ORG_GET_RETAILER_TIMEOUT_MS`).
      *
      * @throws si el retailer no existe (`404 RETAILER_NOT_FOUND`).
      */
     getRetailer(
         retailerId: string,
         tenantId: string,
+        options?: RetailOrgRequestOptions,
     ): Promise<StandardResponse<RetailerValidationDto>>;
 
     /**