@fiado/api-invoker 4.76.0 → 4.78.0

package/bin/index.d.ts

@@ -86,6 +86,7 @@ export * from "./loanConfig/index.js";
 export * from "./loanOfferings/index.js";
 export * from "./loanCollectorAssignment/index.js";
 export * from "./loanCredit/index.js";
+export * from "./loanScoring/index.js";
 export * from "./messages-business/index.js";
 export * from "./totp-security/index.js";
 export * from "./equality-connector/index.js";

package/bin/index.js

@@ -86,6 +86,7 @@ export * from "./loanConfig/index.js";
 export * from "./loanOfferings/index.js";
 export * from "./loanCollectorAssignment/index.js";
 export * from "./loanCredit/index.js";
+export * from "./loanScoring/index.js";
 export * from "./messages-business/index.js";
 export * from "./totp-security/index.js";
 export * from "./equality-connector/index.js";

package/bin/loanScoring/api/LoanScoringBusinessApi.d.ts

@@ -0,0 +1,23 @@
+import type { IHttpRequest } from "@fiado/http-client";
+import { StandardResponse } from "@fiado/gateway-adapter";
+import { EvaluateSciRequest, EvaluateSciResponse, SciEvaluationResponse } from "@fiado/type-kit/bin/loanScoring/index.js";
+import { ILoanScoringBusinessApi } from "./interfaces/ILoanScoringBusinessApi.js";
+/**
+ * Publisher HTTP del lambda `loan-scoring-business` (componente 08 SureKeep Fase 2) para sus 2
+ * endpoints privados de scoring. Contrato y semántica completos → `ILoanScoringBusinessApi`
+ * (tenantId obligatorio fail-closed, errores por `code`, `StandardResponse` → leer `result.data`).
+ *
+ * Env var requerida en el consumer: `LOAN_SCORING_BUSINESS_URL`.
+ * El template.yml del consumer la setea con:
+ *
+ *   LOAN_SCORING_BUSINESS_URL: '{{resolve:ssm:loan-scoring-business}}'
+ *
+ * Convención CLAUDE.md global: SSM key = nombre del lambda owner de la URL.
+ */
+export default class LoanScoringBusinessApi implements ILoanScoringBusinessApi {
+    private httpRequest;
+    private readonly baseUrl;
+    constructor(httpRequest: IHttpRequest);
+    evaluateScore(request: EvaluateSciRequest, tenantId: string): Promise<StandardResponse<EvaluateSciResponse>>;
+    getSciEvaluation(evaluationId: string, tenantId: string): Promise<StandardResponse<SciEvaluationResponse>>;
+}

package/bin/loanScoring/api/LoanScoringBusinessApi.js

@@ -0,0 +1,47 @@
+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-scoring-business` (componente 08 SureKeep Fase 2) para sus 2
+ * endpoints privados de scoring. Contrato y semántica completos → `ILoanScoringBusinessApi`
+ * (tenantId obligatorio fail-closed, errores por `code`, `StandardResponse` → leer `result.data`).
+ *
+ * Env var requerida en el consumer: `LOAN_SCORING_BUSINESS_URL`.
+ * El template.yml del consumer la setea con:
+ *
+ *   LOAN_SCORING_BUSINESS_URL: '{{resolve:ssm:loan-scoring-business}}'
+ *
+ * Convención CLAUDE.md global: SSM key = nombre del lambda owner de la URL.
+ */
+let LoanScoringBusinessApi = class LoanScoringBusinessApi {
+    httpRequest;
+    // El buildspec publica la URL en SSM con "/" final — se normaliza para no armar "//private".
+    baseUrl = (process.env.LOAN_SCORING_BUSINESS_URL || "").replace(/\/+$/, "");
+    constructor(httpRequest) {
+        this.httpRequest = httpRequest;
+    }
+    async evaluateScore(request, tenantId) {
+        const url = `${this.baseUrl}/private/scoring/evaluate?tenantId=${encodeURIComponent(tenantId)}`;
+        return await this.httpRequest.post(url, request);
+    }
+    async getSciEvaluation(evaluationId, tenantId) {
+        const url = `${this.baseUrl}/private/scoring/evaluations/${encodeURIComponent(evaluationId)}?tenantId=${encodeURIComponent(tenantId)}`;
+        return await this.httpRequest.get(url);
+    }
+};
+LoanScoringBusinessApi = __decorate([
+    injectable(),
+    __param(0, inject("IHttpRequest")),
+    __metadata("design:paramtypes", [Object])
+], LoanScoringBusinessApi);
+export default LoanScoringBusinessApi;

package/bin/loanScoring/api/interfaces/ILoanScoringBusinessApi.d.ts

@@ -0,0 +1,55 @@
+import { StandardResponse } from "@fiado/gateway-adapter";
+import { EvaluateSciRequest, EvaluateSciResponse, SciEvaluationResponse } from "@fiado/type-kit/bin/loanScoring/index.js";
+/**
+ * Contrato del publisher HTTP del lambda `loan-scoring-business` (componente 08 SureKeep Fase 2 —
+ * pista Loan/SOFOM) para sus 2 endpoints privados (service-to-service, VPC-only).
+ *
+ * loan-scoring es el motor del SCI (Score Crediticio Interno, 0-100): evalúa a un acreditado con
+ * proveedores intercambiables por configuración (Modelias | Círculo — el consumidor NUNCA sabe
+ * cuál corrió), lo traduce a nivel (`BRONZE/SILVER/GOLD`) + decisión, y persiste un snapshot
+ * INMUTABLE de cada evaluación. Consumidores previstos:
+ *   - retail-wizard-business (paso 05 del wizard)  → evaluateScore
+ *   - loan-credit-business (originación)           → getSciEvaluation (el `evaluationId` de la
+ *     respuesta es el `sciAtOrigination` que el crédito referencia)
+ *
+ * ─────────────────────────────────────────────────────────────────────────────
+ * `tenantId` es OBLIGATORIO en ambos 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 puede inferir el silo. Sin `tenantId` → `400 UNKNOWN_TENANT`
+ * (fail-closed). Nunca hay default: sería fail-OPEN cross-SOFOM.
+ *
+ * ⚠️ Patrón de retorno: `StandardResponse<T>` — el consumer accede `result.data`, NO `result.body`.
+ *
+ * Errores: el lambda destino lanza `DomainError` tipado → el publisher RECHAZA (no devuelve null).
+ * Discriminar por `code` (no por status HTTP):
+ *   `SCORING_PROVIDER_VALIDATION` (422) — el proveedor rechazó los DATOS del solicitante (CURP/
+ *     teléfono inválidos). NO reintentar con el mismo payload.
+ *   `SCORING_PROVIDER_UNAVAILABLE` (502) — proveedor caído/timeout. Transitorio; reintentar es
+ *     válido (cada retry genera una evaluación/snapshot NUEVOS — el lambda no dedupea).
+ *   `SCORING_CONFIG_UNAVAILABLE` (502) — loan-config no respondió las perillas del motor.
+ *   `SCI_EVALUATION_NOT_FOUND` (404) — el evaluationId no existe.
+ *   `400 UNKNOWN_TENANT` / `400 VALIDATION_ERROR` — tenant ausente/desconocido o body inválido.
+ *
+ * Env var requerida en el consumer: `LOAN_SCORING_BUSINESS_URL`.
+ * El template.yml del consumer la setea con:
+ *
+ *   LOAN_SCORING_BUSINESS_URL: '{{resolve:ssm:loan-scoring-business}}'
+ *
+ * Convención CLAUDE.md global: SSM key = nombre del lambda owner de la URL.
+ */
+export interface ILoanScoringBusinessApi {
+    /**
+     * POST /private/scoring/evaluate — evalúa el SCI del acreditado con el proveedor configurado
+     * y PERSISTE el snapshot (write crítico: si la respuesta es 200, la evaluación quedó
+     * guardada). `antiFraudPassed=false` → decisión REJECTED sin consultar al proveedor.
+     */
+    evaluateScore(request: EvaluateSciRequest, tenantId: string): Promise<StandardResponse<EvaluateSciResponse>>;
+    /**
+     * GET /private/scoring/evaluations/{evaluationId} — lee el snapshot inmutable de una
+     * evaluación (con breakdown por capas + auditoría).
+     *
+     * @throws si la evaluación no existe (`404 SCI_EVALUATION_NOT_FOUND`).
+     */
+    getSciEvaluation(evaluationId: string, tenantId: string): Promise<StandardResponse<SciEvaluationResponse>>;
+}

package/bin/loanScoring/api/interfaces/ILoanScoringBusinessApi.js

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

package/bin/loanScoring/index.d.ts

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

package/bin/loanScoring/index.js

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

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

@@ -3,7 +3,7 @@ import { StandardResponse } from "@fiado/gateway-adapter";
 import { UpsertCustomerFromKycRequest, AccountResultRequest, CustomerResponse } from "@fiado/type-kit/bin/retailCustomer/index.js";
 import { IRetailCustomerBusinessApi } from "./interfaces/IRetailCustomerBusinessApi.js";
 /**
- * Publisher HTTP del lambda `retail-customer-business` (SureKeep Fase 2, pista Retail) para sus 4
+ * Publisher HTTP del lambda `retail-customer-business` (SureKeep Fase 2, pista Retail) para sus 5
  * endpoints privados de cliente. Contrato y semántica completos → `IRetailCustomerBusinessApi`.
  *
  * Los paths y el `?tenantId=` matchean `openapi/private.yaml` del lambda destino (mismo patrón que
@@ -24,4 +24,5 @@ export default class RetailCustomerBusinessApi implements IRetailCustomerBusines
     setAccountResult(customerId: string, payload: AccountResultRequest, tenantId: string): Promise<StandardResponse<CustomerResponse>>;
     getCustomerByPhone(phone: string, tenantId: string): Promise<StandardResponse<CustomerResponse>>;
     getCustomer(customerId: string, tenantId: string): Promise<StandardResponse<CustomerResponse>>;
+    markWelcomeAccredited(customerId: string, tenantId: string): Promise<StandardResponse<CustomerResponse>>;
 }

package/bin/retailCustomer/api/RetailCustomerBusinessApi.js

@@ -12,7 +12,7 @@ var __param = (this && this.__param) || function (paramIndex, decorator) {
 };
 import { inject, injectable } from "inversify";
 /**
- * Publisher HTTP del lambda `retail-customer-business` (SureKeep Fase 2, pista Retail) para sus 4
+ * Publisher HTTP del lambda `retail-customer-business` (SureKeep Fase 2, pista Retail) para sus 5
  * endpoints privados de cliente. Contrato y semántica completos → `IRetailCustomerBusinessApi`.
  *
  * Los paths y el `?tenantId=` matchean `openapi/private.yaml` del lambda destino (mismo patrón que
@@ -47,6 +47,11 @@ let RetailCustomerBusinessApi = class RetailCustomerBusinessApi {
         const url = `${this.baseUrl}/private/customers/${encodeURIComponent(customerId)}?tenantId=${encodeURIComponent(tenantId)}`;
         return await this.httpRequest.get(url);
     }
+    async markWelcomeAccredited(customerId, tenantId) {
+        const url = `${this.baseUrl}/private/customers/${encodeURIComponent(customerId)}/welcome-accreditation?tenantId=${encodeURIComponent(tenantId)}`;
+        // Sin body: el cliente va en el path y el actor lo pone el destino desde el contexto privado.
+        return await this.httpRequest.post(url, {});
+    }
 };
 RetailCustomerBusinessApi = __decorate([
     injectable(),

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

@@ -2,14 +2,14 @@ import { StandardResponse } from "@fiado/gateway-adapter";
 import { UpsertCustomerFromKycRequest, AccountResultRequest, CustomerResponse } from "@fiado/type-kit/bin/retailCustomer/index.js";
 /**
  * Contrato del publisher HTTP del lambda `retail-customer-business` (SureKeep Fase 2, pista Retail)
- * para sus 4 endpoints privados de cliente (service-to-service, VPC-only).
+ * para sus 5 endpoints privados de cliente (service-to-service, VPC-only).
  *
  * Consumidor previsto:
  *   - `retail-wizard-business` → upsert del cliente post-KYC, aterrizaje del resultado de apertura
  *     de cuenta (D35), y lecturas del cliente por teléfono / id durante la saga de venta.
  *
  * ─────────────────────────────────────────────────────────────────────────────
- * `tenantId` es OBLIGATORIO en los 4 métodos — no es un detalle de firma.
+ * `tenantId` es OBLIGATORIO en los 5 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
@@ -73,4 +73,21 @@ export interface IRetailCustomerBusinessApi {
      * @throws si el cliente no existe (`404 CUSTOMER_NOT_FOUND`).
      */
     getCustomer(customerId: string, tenantId: string): Promise<StandardResponse<CustomerResponse>>;
+    /**
+     * POST /private/customers/{customerId}/welcome-accreditation?tenantId= — RESERVA la acreditación
+     * del bono de bienvenida (D33). Sin body: el cliente va en el path, el actor lo pone el destino.
+     *
+     * ⚠️ Reserva, NO acredita. El lambda destino es dueño del flag `welcomeAccredited` y su transición
+     * `false → true` es el candado de idempotencia PERMANENTE por cliente (una sola vez para siempre,
+     * ni una segunda venta la repite). La condición vive en la transacción DDB, así que dos requests
+     * concurrentes NO pueden ganar los dos.
+     *
+     * Orden obligatorio en el caller: reservar acá PRIMERO, mover plata en el processor DESPUÉS. Al
+     * revés, un doble click acredita dos veces plata real.
+     *
+     * @throws `409 WELCOME_ALREADY_ACCREDITED` si el bono ya se entregó. Para el caller NO es falla:
+     *   es la señal de "no acredites" — la venta sigue su curso normal.
+     * @throws `404 CUSTOMER_NOT_FOUND` si el cliente no existe.
+     */
+    markWelcomeAccredited(customerId: string, tenantId: string): Promise<StandardResponse<CustomerResponse>>;
 }

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@fiado/api-invoker",
-  "version": "4.76.0",
+  "version": "4.78.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.202.0",
+    "@fiado/type-kit": "^3.204.0",
     "dotenv": "^16.4.7"
   },
   "peerDependencies": {

package/src/index.ts

@@ -86,6 +86,7 @@ export * from "./loanConfig/index.js";
 export * from "./loanOfferings/index.js";
 export * from "./loanCollectorAssignment/index.js";
 export * from "./loanCredit/index.js";
+export * from "./loanScoring/index.js";
 export * from "./messages-business/index.js";
 export * from "./totp-security/index.js";
 export * from "./equality-connector/index.js";

package/src/loanScoring/api/LoanScoringBusinessApi.ts

@@ -0,0 +1,45 @@
+import { inject, injectable } from "inversify";
+import type { IHttpRequest } from "@fiado/http-client";
+import { StandardResponse } from "@fiado/gateway-adapter";
+import {
+    EvaluateSciRequest,
+    EvaluateSciResponse,
+    SciEvaluationResponse,
+} from "@fiado/type-kit/bin/loanScoring/index.js";
+import { ILoanScoringBusinessApi } from "./interfaces/ILoanScoringBusinessApi.js";
+
+/**
+ * Publisher HTTP del lambda `loan-scoring-business` (componente 08 SureKeep Fase 2) para sus 2
+ * endpoints privados de scoring. Contrato y semántica completos → `ILoanScoringBusinessApi`
+ * (tenantId obligatorio fail-closed, errores por `code`, `StandardResponse` → leer `result.data`).
+ *
+ * Env var requerida en el consumer: `LOAN_SCORING_BUSINESS_URL`.
+ * El template.yml del consumer la setea con:
+ *
+ *   LOAN_SCORING_BUSINESS_URL: '{{resolve:ssm:loan-scoring-business}}'
+ *
+ * Convención CLAUDE.md global: SSM key = nombre del lambda owner de la URL.
+ */
+@injectable()
+export default class LoanScoringBusinessApi implements ILoanScoringBusinessApi {
+    // El buildspec publica la URL en SSM con "/" final — se normaliza para no armar "//private".
+    private readonly baseUrl = (process.env.LOAN_SCORING_BUSINESS_URL || "").replace(/\/+$/, "");
+
+    constructor(@inject("IHttpRequest") private httpRequest: IHttpRequest) {}
+
+    async evaluateScore(
+        request: EvaluateSciRequest,
+        tenantId: string,
+    ): Promise<StandardResponse<EvaluateSciResponse>> {
+        const url = `${this.baseUrl}/private/scoring/evaluate?tenantId=${encodeURIComponent(tenantId)}`;
+        return await this.httpRequest.post(url, request);
+    }
+
+    async getSciEvaluation(
+        evaluationId: string,
+        tenantId: string,
+    ): Promise<StandardResponse<SciEvaluationResponse>> {
+        const url = `${this.baseUrl}/private/scoring/evaluations/${encodeURIComponent(evaluationId)}?tenantId=${encodeURIComponent(tenantId)}`;
+        return await this.httpRequest.get(url);
+    }
+}

package/src/loanScoring/api/interfaces/ILoanScoringBusinessApi.ts

@@ -0,0 +1,67 @@
+import { StandardResponse } from "@fiado/gateway-adapter";
+import {
+    EvaluateSciRequest,
+    EvaluateSciResponse,
+    SciEvaluationResponse,
+} from "@fiado/type-kit/bin/loanScoring/index.js";
+
+/**
+ * Contrato del publisher HTTP del lambda `loan-scoring-business` (componente 08 SureKeep Fase 2 —
+ * pista Loan/SOFOM) para sus 2 endpoints privados (service-to-service, VPC-only).
+ *
+ * loan-scoring es el motor del SCI (Score Crediticio Interno, 0-100): evalúa a un acreditado con
+ * proveedores intercambiables por configuración (Modelias | Círculo — el consumidor NUNCA sabe
+ * cuál corrió), lo traduce a nivel (`BRONZE/SILVER/GOLD`) + decisión, y persiste un snapshot
+ * INMUTABLE de cada evaluación. Consumidores previstos:
+ *   - retail-wizard-business (paso 05 del wizard)  → evaluateScore
+ *   - loan-credit-business (originación)           → getSciEvaluation (el `evaluationId` de la
+ *     respuesta es el `sciAtOrigination` que el crédito referencia)
+ *
+ * ─────────────────────────────────────────────────────────────────────────────
+ * `tenantId` es OBLIGATORIO en ambos 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 puede inferir el silo. Sin `tenantId` → `400 UNKNOWN_TENANT`
+ * (fail-closed). Nunca hay default: sería fail-OPEN cross-SOFOM.
+ *
+ * ⚠️ Patrón de retorno: `StandardResponse<T>` — el consumer accede `result.data`, NO `result.body`.
+ *
+ * Errores: el lambda destino lanza `DomainError` tipado → el publisher RECHAZA (no devuelve null).
+ * Discriminar por `code` (no por status HTTP):
+ *   `SCORING_PROVIDER_VALIDATION` (422) — el proveedor rechazó los DATOS del solicitante (CURP/
+ *     teléfono inválidos). NO reintentar con el mismo payload.
+ *   `SCORING_PROVIDER_UNAVAILABLE` (502) — proveedor caído/timeout. Transitorio; reintentar es
+ *     válido (cada retry genera una evaluación/snapshot NUEVOS — el lambda no dedupea).
+ *   `SCORING_CONFIG_UNAVAILABLE` (502) — loan-config no respondió las perillas del motor.
+ *   `SCI_EVALUATION_NOT_FOUND` (404) — el evaluationId no existe.
+ *   `400 UNKNOWN_TENANT` / `400 VALIDATION_ERROR` — tenant ausente/desconocido o body inválido.
+ *
+ * Env var requerida en el consumer: `LOAN_SCORING_BUSINESS_URL`.
+ * El template.yml del consumer la setea con:
+ *
+ *   LOAN_SCORING_BUSINESS_URL: '{{resolve:ssm:loan-scoring-business}}'
+ *
+ * Convención CLAUDE.md global: SSM key = nombre del lambda owner de la URL.
+ */
+export interface ILoanScoringBusinessApi {
+    /**
+     * POST /private/scoring/evaluate — evalúa el SCI del acreditado con el proveedor configurado
+     * y PERSISTE el snapshot (write crítico: si la respuesta es 200, la evaluación quedó
+     * guardada). `antiFraudPassed=false` → decisión REJECTED sin consultar al proveedor.
+     */
+    evaluateScore(
+        request: EvaluateSciRequest,
+        tenantId: string,
+    ): Promise<StandardResponse<EvaluateSciResponse>>;
+
+    /**
+     * GET /private/scoring/evaluations/{evaluationId} — lee el snapshot inmutable de una
+     * evaluación (con breakdown por capas + auditoría).
+     *
+     * @throws si la evaluación no existe (`404 SCI_EVALUATION_NOT_FOUND`).
+     */
+    getSciEvaluation(
+        evaluationId: string,
+        tenantId: string,
+    ): Promise<StandardResponse<SciEvaluationResponse>>;
+}

package/src/loanScoring/index.ts

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

package/src/retailCustomer/api/RetailCustomerBusinessApi.ts

@@ -9,7 +9,7 @@ import {
 import { IRetailCustomerBusinessApi } from "./interfaces/IRetailCustomerBusinessApi.js";
 
 /**
- * Publisher HTTP del lambda `retail-customer-business` (SureKeep Fase 2, pista Retail) para sus 4
+ * Publisher HTTP del lambda `retail-customer-business` (SureKeep Fase 2, pista Retail) para sus 5
  * endpoints privados de cliente. Contrato y semántica completos → `IRetailCustomerBusinessApi`.
  *
  * Los paths y el `?tenantId=` matchean `openapi/private.yaml` del lambda destino (mismo patrón que
@@ -60,4 +60,13 @@ export default class RetailCustomerBusinessApi implements IRetailCustomerBusines
         const url = `${this.baseUrl}/private/customers/${encodeURIComponent(customerId)}?tenantId=${encodeURIComponent(tenantId)}`;
         return await this.httpRequest.get(url);
     }
+
+    async markWelcomeAccredited(
+        customerId: string,
+        tenantId: string,
+    ): Promise<StandardResponse<CustomerResponse>> {
+        const url = `${this.baseUrl}/private/customers/${encodeURIComponent(customerId)}/welcome-accreditation?tenantId=${encodeURIComponent(tenantId)}`;
+        // Sin body: el cliente va en el path y el actor lo pone el destino desde el contexto privado.
+        return await this.httpRequest.post(url, {});
+    }
 }

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

@@ -7,14 +7,14 @@ import {
 
 /**
  * Contrato del publisher HTTP del lambda `retail-customer-business` (SureKeep Fase 2, pista Retail)
- * para sus 4 endpoints privados de cliente (service-to-service, VPC-only).
+ * para sus 5 endpoints privados de cliente (service-to-service, VPC-only).
  *
  * Consumidor previsto:
  *   - `retail-wizard-business` → upsert del cliente post-KYC, aterrizaje del resultado de apertura
  *     de cuenta (D35), y lecturas del cliente por teléfono / id durante la saga de venta.
  *
  * ─────────────────────────────────────────────────────────────────────────────
- * `tenantId` es OBLIGATORIO en los 4 métodos — no es un detalle de firma.
+ * `tenantId` es OBLIGATORIO en los 5 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
@@ -94,4 +94,25 @@ export interface IRetailCustomerBusinessApi {
         customerId: string,
         tenantId: string,
     ): Promise<StandardResponse<CustomerResponse>>;
+
+    /**
+     * POST /private/customers/{customerId}/welcome-accreditation?tenantId= — RESERVA la acreditación
+     * del bono de bienvenida (D33). Sin body: el cliente va en el path, el actor lo pone el destino.
+     *
+     * ⚠️ Reserva, NO acredita. El lambda destino es dueño del flag `welcomeAccredited` y su transición
+     * `false → true` es el candado de idempotencia PERMANENTE por cliente (una sola vez para siempre,
+     * ni una segunda venta la repite). La condición vive en la transacción DDB, así que dos requests
+     * concurrentes NO pueden ganar los dos.
+     *
+     * Orden obligatorio en el caller: reservar acá PRIMERO, mover plata en el processor DESPUÉS. Al
+     * revés, un doble click acredita dos veces plata real.
+     *
+     * @throws `409 WELCOME_ALREADY_ACCREDITED` si el bono ya se entregó. Para el caller NO es falla:
+     *   es la señal de "no acredites" — la venta sigue su curso normal.
+     * @throws `404 CUSTOMER_NOT_FOUND` si el cliente no existe.
+     */
+    markWelcomeAccredited(
+        customerId: string,
+        tenantId: string,
+    ): Promise<StandardResponse<CustomerResponse>>;
 }