products-payment-refacil-mcp 1.2.5 → 1.2.7

package/README.md

@@ -4,7 +4,7 @@ Servidor MCP (Model Context Protocol) generado automáticamente para la API prod
 
 ## 🚀 Características
 
-- **13 herramientas** generadas automáticamente desde la colección Postman
+- **21 herramientas** generadas automáticamente desde la colección Postman
 - **Autenticación flexible**: secretId con renovación automática de tokens
 - **Servidor HTTP** con Fastify
 - **Protocolo MCP** estándar para integración con IDEs
@@ -353,7 +353,7 @@ Este endpoint incluye un script automático que:
 | --- | --- | --- |
 | secretId | string | Campo del body: secretId |
 
-### `status`
+### `health_check_health_check_get`
 
 Verificación del estado de la API y conectividad con servicios
 
@@ -369,7 +369,6 @@ Verificación del estado de la API y conectividad con servicios
     "status": "ok",
     "timestamp": "2024-01-15T10:30:45.123Z",
     "uptime": 3600,
-    "services": "connected",
     "version": "1.0.0",
     "environment": "development"
   }
@@ -386,7 +385,6 @@ Verificación del estado de la API y conectividad con servicios
     "status": "error",
     "timestamp": "2024-01-15T10:30:45.123Z",
     "uptime": 3600,
-    "services": "disconnected",
     "error": "Connection timeout",
     "version": "1.0.0",
     "environment": "development"
@@ -394,6 +392,12 @@ Verificación del estado de la API y conectividad con servicios
 }
 ```
 
+### `status`
+
+Verificación del estado de la API y conectividad con servicios
+
+ Verifica conectividad de la API contra el core service.
+
 ### `products_categories`
 
 Endpoints para consultar categorías y productos disponibles
@@ -613,10 +617,10 @@ Esta respuesta contiene información clave que se debe usar para crear una solic
 
 | Name | Type | Description |
 | --- | --- | --- |
-| categoryId | number | Campo del body: categoryId |
-| limit | number | Campo del body: limit |
-| offset | number | Campo del body: offset |
-| searchText | string | Campo del body: searchText |
+| categoryId * | number | ID de la categoría |
+| limit | number | Número máximo de productos (default: 10) |
+| offset | number | Número de productos a omitir (default: 0) |
+| searchText | string | Texto para buscar en productos |
 
 ### `product_requests_quote`
 
@@ -759,13 +763,13 @@ POST /product-requests/create
 
 | Name | Type | Description |
 | --- | --- | --- |
-| category_id | number | Campo del body: category_id |
-| id | number | Campo del body: id |
-| amount | null | Campo del body: amount |
-| data | object | Campo del body: data |
-| query_type | null | Campo del body: query_type |
-| sell_type | string | Campo del body: sell_type |
-| agreement | string | Campo del body: agreement |
+| category_id * | number | ID de la categoría |
+| id * | number | ID del producto |
+| amount | null | Usar `null` para productos con consulta previa |
+| data * | object | Datos específicos del producto |
+| query_type * | null | Tipo de consulta (BILLData, PLATE_QUERY, etc.) |
+| sell_type * | string | Tipo de venta (debe requerir consulta previa) |
+| agreement | string | Acuerdo del producto |
 
 ### `product_requests_create`
 
@@ -776,7 +780,7 @@ Endpoints para crear solicitudes de productos
 **📋 Relación con Endpoint de Productos:**  
 Los datos para crear esta solicitud provienen principalmente del endpoint `products/by-customer-and-category`:
 
-- **`category_id`**: Debe usar el mismo valor de `categoryId` enviado en la consulta a `products/by-customer-and-category`
+- **`category_id`**: ID de la categoría (del endpoint de productos)
     
 - **`id`**: ID del producto seleccionado (del campo `id` del producto)
     
@@ -798,7 +802,7 @@ Los datos para crear esta solicitud provienen principalmente del endpoint `produ
 
 **Body (JSON):**
 
-- `category_id` (number, requerido): mismo valor de `categoryId` usado al consultar `products/by-customer-and-category`
+- `category_id` (number, requerido): ID de la categoría (obtenido del endpoint de productos)
     
 - `id` (number, requerido): ID del producto seleccionado (obtenido del campo `id` del producto)
     
@@ -814,6 +818,8 @@ Los datos para crear esta solicitud provienen principalmente del endpoint `produ
     
 - `customer_id` (string, opcional): Identificador único del usuario o dispositivo
     
+- `subcustomer_id` (string, opcional): Identificador del subcliente o cuenta hija asociada al `customer_id`
+    
 - cart_id (string, opcional): identificador del carrito de compra al que se quiere agregar la solicictud de producto
     
 
@@ -890,7 +896,8 @@ const customerId = deviceId || sessionId;
   "query_type": "BILLData",
   "sell_type": "Bill",
   "agreement": "2010910",
-  "customer_id": "device_abc123def456"
+  "customer_id": "device_abc123def456",
+  "subcustomer_id": "subcust_01"
 }
 
  ```
@@ -949,6 +956,7 @@ GET /products/by-customer-and-category
         "amount": null,
         "meta": {
           "fnArgs": 20363,
+          "categoryId": 44,
           "form": [
             {
               "active": true,
@@ -1154,15 +1162,16 @@ Con la respuesta de este endpoint, puedes proceder a crear el pago usando `/prod
 
 | Name | Type | Description |
 | --- | --- | --- |
-| category_id | number | Campo del body: category_id |
-| id | number | Campo del body: id |
-| amount | null | Campo del body: amount |
-| data | object | Campo del body: data |
-| query_type | string | Campo del body: query_type |
-| sell_type | string | Campo del body: sell_type |
-| agreement | string | Campo del body: agreement |
-| customer_id | string | Campo del body: customer_id |
-| cart_id | string | Campo del body: cart_id |
+| category_id * | number | ID de la categoría (obtenido del endpoint de productos) |
+| id * | number | ID del producto seleccionado (obtenido del campo `id` del producto) |
+| amount | null | Monto del producto (ver reglas de uso) |
+| data * | object | Datos específicos del producto basados en `template_data_request` del producto |
+| query_type * | string | Tipo de consulta del producto (PHONE_QUERY, PLATE_QUERY, etc.) |
+| sell_type * | string | Tipo de venta del producto (DIRECT_SALE, QUERY_FIRST) |
+| agreement | string | Aceptación de términos (puede venir del campo `agreement` del producto) |
+| customer_id | string | Identificador único del usuario o dispositivo |
+| subcustomer_id | string | Identificador del subcliente o cuenta hija asociada al `customer_id` |
+| cart_id | string | identificador del carrito de compra al que se quiere agregar la solicictud de producto |
 
 ### `product_requests_status`
 
@@ -1175,7 +1184,7 @@ Este endpoint incluye validación de seguridad que garantiza que solo puedas con
 
 **📋 Parámetros:**
 
-Debes proporcionar **uno** de los siguientes parámetros (no ambos obligatorios):
+Debes proporcionar al menos uno de los siguientes parámetros:
 
 - **`requestId`** (string, opcional): ID único de la solicitud de producto individual (UUID)
     
@@ -1387,7 +1396,7 @@ Este endpoint incluye validación de seguridad que garantiza que solo puedas des
 
 **📋 Parámetros:**
 
-Debes proporcionar **uno** de los siguientes parámetros (no ambos obligatorios):
+Debes proporcionar al menos uno de los siguientes parámetros:
 
 - **`requestId`** (string, opcional): ID único de la solicitud de producto individual (UUID)
     
@@ -1664,7 +1673,7 @@ Crea el pago de un producto usando el medio de pago seleccionado. Esta es la eta
 **📋 Relación con Endpoint de Solicitud:**  
 Los datos para crear este pago provienen de la respuesta del endpoint `product-requests/create`:
 
-- **`cartId`**: Del campo `cartId` de la respuesta de solicitud
+- **`cartId`**: Del campo `cartId` de la respuesta del carrito
     
 - **`id`**: Del campo `id` del medio de pago seleccionado
     
@@ -1682,7 +1691,7 @@ Los datos para crear este pago provienen de la respuesta del endpoint `product-r
 
 **Body (JSON):**
 
-- `cartId` (string, requerido): ID de la solicitud obtenido de `product-requests/create`
+- `cartId` (string, requerido): ID del carrito obtenido de `product-requests/create`
     
 - `id` (number, requerido): ID del medio de pago seleccionado
     
@@ -1690,9 +1699,9 @@ Los datos para crear este pago provienen de la respuesta del endpoint `product-r
     
 - `data` (object, requerido): Datos del pagador basados en `template_data_request` del medio de pago
     
-- `returnUrl` (string, opcional): URL de retorno después del pago
+- `returnUrl` (string, requerido): URL de retorno después del pago
     
-- `webhookUrl` (string, opcional): URL para notificaciones de estado del pago
+- `webhookUrl` (string, requerido): URL para notificaciones de estado del pago
     
 
 **🔄 Flujo de Creación de Pago:**
@@ -1815,7 +1824,7 @@ Los datos para crear este pago provienen de la respuesta del endpoint `product-r
         "cartId": "88d0b575-80f4-4f9b-af8f-5d09ec2cb877",
         "url": "https://mf-core.refacil.co/refacilpay/resumen/62/5ff47b60-77b1-11f0-b5e9-6f43bd8928c1",
         "reference": "5ff47b60-77b1-11f0-b5e9-6f43bd8928c1",
-        "amount": 19000
+        "amount": 19000,
         "expiresIn": "2025-08-13T07:20:15.038Z"
     }
 }
@@ -1896,12 +1905,12 @@ Los datos para crear este pago provienen de la respuesta del endpoint `product-r
 
 | Name | Type | Description |
 | --- | --- | --- |
-| cartId | string | Campo del body: cartId |
-| id | number | Campo del body: id |
-| categoryid | number | Campo del body: categoryid |
-| data | object | Campo del body: data |
-| returnUrl | string | Campo del body: returnUrl |
-| webhookUrl | string | Campo del body: webhookUrl |
+| cartId * | string | ID del carrito obtenido de `product-requests/create` |
+| id * | number | ID del medio de pago seleccionado |
+| categoryid * | number | ID de la categoría del medio de pago |
+| data * | object | Datos del pagador basados en `template_data_request` del medio de pago |
+| returnUrl * | string | URL de retorno después del pago |
+| webhookUrl * | string | URL para notificaciones de estado del pago |
 
 ### `products_payment_retry_sale`
 
@@ -2132,16 +2141,223 @@ Endpoints para crear reembolsos
 
 | Name | Type | Description |
 | --- | --- | --- |
-| requestId | string | Campo del body: requestId |
-| keyBreB | string | Campo del body: keyBreB |
-| email | string | Campo del body: email |
-| webhookUrl | string | Campo del body: webhookUrl |
+| requestId * | string | ID del request a reembolsar |
+| keyBreB * | string | Clave BreB del cliente (número de celular u otro identificador) |
+| email * | string | Email del cliente |
+| webhookUrl * | string | URL para notificaciones del reembolso |
+
+### `dashboard_summary`
+
+Endpoints read-only para dashboards de cliente. Los siete `POST /dashboard/*` requieren autenticación (Bearer + `x-secret-id`) y filtran por el `user_api_id` del token. `customer_id` es obligatorio y mapea a `core.product_requests.user_temp_id`. El campo opcional `subcustomer_id` (string o null) se acepta en **todas** las rutas y mapea a `core.product_requests.subcustomer_id`: si se omite, es null o queda en blanco tras trim, no hay filtro por subcliente (todo el subsegmento bajo ese `customer_id`); si se envía, los resultados se limitan a ese subcliente. El rango `from`/`to` (ISO-8601 UTC) sigue las reglas de cada endpoint. Cada request documenta ambos patrones (con y sin `subcustomer_id`).
+
+ Devuelve KPIs agregados del cliente: totalRequests, totalSales, totalSalesAmount, totalRefunds, totalRefundsAmount, failedRequests, conversionRate (0..1).
+
+**Body:**
+- `customer_id` (string, requerido)
+- `subcustomer_id` (string, opcional) → `core.product_requests.subcustomer_id`
+- `from`/`to` (ISO-8601 UTC, opcional; ambos o ninguno; from <= to)
+
+Si no se envía rango, se aplican los últimos 30 días en UTC.
+
+La pestaña **Body** incluye `subcustomer_id` y un rango de fechas explícito.
+
+**Ejemplo — sin filtro por subcliente (omite `subcustomer_id`):**
+```json
+{
+  "customer_id": "customer_123",
+  "from": "2026-03-01T00:00:00.000Z",
+  "to": "2026-03-31T23:59:59.000Z"
+}
+```
+
+**Parámetros:**
+
+| Name | Type | Description |
+| --- | --- | --- |
+| customer_id | string | Campo del body: customer_id |
+| subcustomer_id | string | Campo del body: subcustomer_id |
+| from | string | Campo del body: from |
+| to | string | Campo del body: to |
+
+### `dashboard_sales`
+
+Endpoints read-only para dashboards de cliente. Los siete `POST /dashboard/*` requieren autenticación (Bearer + `x-secret-id`) y filtran por el `user_api_id` del token. `customer_id` es obligatorio y mapea a `core.product_requests.user_temp_id`. El campo opcional `subcustomer_id` (string o null) se acepta en **todas** las rutas y mapea a `core.product_requests.subcustomer_id`: si se omite, es null o queda en blanco tras trim, no hay filtro por subcliente (todo el subsegmento bajo ese `customer_id`); si se envía, los resultados se limitan a ese subcliente. El rango `from`/`to` (ISO-8601 UTC) sigue las reglas de cada endpoint. Cada request documenta ambos patrones (con y sin `subcustomer_id`).
+
+ Listado paginado de ventas exitosas (`product_sales.status = SUCCESS`) enriquecido con datos del `product_request`.
+
+**Body adicional:**
+- `subcustomer_id` (opcional) → `core.product_requests.subcustomer_id`
+- `page` (default 1, min 1)
+- `limit` (default 20, max 100)
+- `product_type` (opcional)
+
+Filtro de fechas: `COALESCE(executed_at, created_at)` de la venta.
+
+La pestaña **Body** trae un ejemplo **con** `subcustomer_id` para que se vea directo en la colección.
+
+**Ejemplo — todo el segmento de `customer_id` (sin `subcustomer_id` o null):**
+```json
+{
+  "customer_id": "customer_123",
+  "page": 1,
+  "limit": 20,
+  "product_type": "RECARGA"
+}
+```
+
+**Parámetros:**
+
+| Name | Type | Description |
+| --- | --- | --- |
+| customer_id | string | Campo del body: customer_id |
+| subcustomer_id | string | Campo del body: subcustomer_id |
+| page | number | Campo del body: page |
+| limit | number | Campo del body: limit |
+| product_type | string | Campo del body: product_type |
+
+### `dashboard_transactions`
+
+Endpoints read-only para dashboards de cliente. Los siete `POST /dashboard/*` requieren autenticación (Bearer + `x-secret-id`) y filtran por el `user_api_id` del token. `customer_id` es obligatorio y mapea a `core.product_requests.user_temp_id`. El campo opcional `subcustomer_id` (string o null) se acepta en **todas** las rutas y mapea a `core.product_requests.subcustomer_id`: si se omite, es null o queda en blanco tras trim, no hay filtro por subcliente (todo el subsegmento bajo ese `customer_id`); si se envía, los resultados se limitan a ese subcliente. El rango `from`/`to` (ISO-8601 UTC) sigue las reglas de cada endpoint. Cada request documenta ambos patrones (con y sin `subcustomer_id`).
+
+ Listado paginado de `product_requests` con el estado consolidado del flujo (request + payment + topup + sale). Filtros opcionales: `status` (array de ProductRequestStatus) y `product_type`. `subcustomer_id` opcional → `core.product_requests.subcustomer_id`.
+
+La pestaña **Body** incluye `subcustomer_id` para que el campo se vea en la colección.
+
+**Ejemplo — sin filtro por subcliente (omite `subcustomer_id`):**
+```json
+{
+  "customer_id": "customer_123",
+  "page": 1,
+  "limit": 20,
+  "status": ["SOLD", "REFUNDED"],
+  "product_type": "FACTURA"
+}
+```
+
+**Parámetros:**
+
+| Name | Type | Description |
+| --- | --- | --- |
+| customer_id | string | Campo del body: customer_id |
+| subcustomer_id | string | Campo del body: subcustomer_id |
+| page | number | Campo del body: page |
+| limit | number | Campo del body: limit |
+| status | array | Campo del body: status |
+| product_type | string | Campo del body: product_type |
+
+### `dashboard_stats_by_status`
+
+Endpoints read-only para dashboards de cliente. Los siete `POST /dashboard/*` requieren autenticación (Bearer + `x-secret-id`) y filtran por el `user_api_id` del token. `customer_id` es obligatorio y mapea a `core.product_requests.user_temp_id`. El campo opcional `subcustomer_id` (string o null) se acepta en **todas** las rutas y mapea a `core.product_requests.subcustomer_id`: si se omite, es null o queda en blanco tras trim, no hay filtro por subcliente (todo el subsegmento bajo ese `customer_id`); si se envía, los resultados se limitan a ese subcliente. El rango `from`/`to` (ISO-8601 UTC) sigue las reglas de cada endpoint. Cada request documenta ambos patrones (con y sin `subcustomer_id`).
 
-### `docs_cli_web_documentation`
+ Agrupa `product_requests` por `ProductRequestStatus`. La respuesta SIEMPRE incluye una entrada por cada estado del enum (count=0, totalAmount=0 si no hay registros). `subcustomer_id` opcional → `core.product_requests.subcustomer_id`.
+
+La pestaña **Body** incluye `subcustomer_id`.
+
+**Ejemplo — sin filtro por subcliente:**
+```json
+{
+  "customer_id": "customer_123"
+}
+```
+
+**Parámetros:**
+
+| Name | Type | Description |
+| --- | --- | --- |
+| customer_id | string | Campo del body: customer_id |
+| subcustomer_id | string | Campo del body: subcustomer_id |
+
+### `dashboard_stats_by_product_type`
+
+Endpoints read-only para dashboards de cliente. Los siete `POST /dashboard/*` requieren autenticación (Bearer + `x-secret-id`) y filtran por el `user_api_id` del token. `customer_id` es obligatorio y mapea a `core.product_requests.user_temp_id`. El campo opcional `subcustomer_id` (string o null) se acepta en **todas** las rutas y mapea a `core.product_requests.subcustomer_id`: si se omite, es null o queda en blanco tras trim, no hay filtro por subcliente (todo el subsegmento bajo ese `customer_id`); si se envía, los resultados se limitan a ese subcliente. El rango `from`/`to` (ISO-8601 UTC) sigue las reglas de cada endpoint. Cada request documenta ambos patrones (con y sin `subcustomer_id`).
+
+ Agrupa por `product_type`. Por defecto solo `status=SOLD`. Acepta `statuses` (array) para overridear. `subcustomer_id` opcional → `core.product_requests.subcustomer_id`.
+
+La pestaña **Body** incluye `subcustomer_id`.
+
+**Ejemplo — sin filtro por subcliente:**
+```json
+{
+  "customer_id": "customer_123",
+  "statuses": ["SOLD"]
+}
+```
+
+**Parámetros:**
+
+| Name | Type | Description |
+| --- | --- | --- |
+| customer_id | string | Campo del body: customer_id |
+| subcustomer_id | string | Campo del body: subcustomer_id |
+| statuses | array | Campo del body: statuses |
+
+### `dashboard_stats_timeseries`
+
+Endpoints read-only para dashboards de cliente. Los siete `POST /dashboard/*` requieren autenticación (Bearer + `x-secret-id`) y filtran por el `user_api_id` del token. `customer_id` es obligatorio y mapea a `core.product_requests.user_temp_id`. El campo opcional `subcustomer_id` (string o null) se acepta en **todas** las rutas y mapea a `core.product_requests.subcustomer_id`: si se omite, es null o queda en blanco tras trim, no hay filtro por subcliente (todo el subsegmento bajo ese `customer_id`); si se envía, los resultados se limitan a ese subcliente. El rango `from`/`to` (ISO-8601 UTC) sigue las reglas de cada endpoint. Cada request documenta ambos patrones (con y sin `subcustomer_id`).
+
+ Serie temporal de ventas SOLD agrupada por `granularity` (`day` | `month`, default `day`). Buckets vacíos vienen con `count=0` y `totalAmount=0`. `subcustomer_id` opcional → `core.product_requests.subcustomer_id`.
+
+La pestaña **Body** incluye `subcustomer_id`.
+
+**Ejemplo — todos los subsegmentos en el rango (omite `subcustomer_id`):**
+```json
+{
+  "customer_id": "customer_123",
+  "granularity": "day",
+  "from": "2026-03-01T00:00:00.000Z",
+  "to": "2026-03-07T23:59:59.000Z"
+}
+```
+
+**Parámetros:**
+
+| Name | Type | Description |
+| --- | --- | --- |
+| customer_id | string | Campo del body: customer_id |
+| subcustomer_id | string | Campo del body: subcustomer_id |
+| granularity | string | Campo del body: granularity |
+| from | string | Campo del body: from |
+| to | string | Campo del body: to |
+
+### `dashboard_refunds`
+
+Endpoints read-only para dashboards de cliente. Los siete `POST /dashboard/*` requieren autenticación (Bearer + `x-secret-id`) y filtran por el `user_api_id` del token. `customer_id` es obligatorio y mapea a `core.product_requests.user_temp_id`. El campo opcional `subcustomer_id` (string o null) se acepta en **todas** las rutas y mapea a `core.product_requests.subcustomer_id`: si se omite, es null o queda en blanco tras trim, no hay filtro por subcliente (todo el subsegmento bajo ese `customer_id`); si se envía, los resultados se limitan a ese subcliente. El rango `from`/`to` (ISO-8601 UTC) sigue las reglas de cada endpoint. Cada request documenta ambos patrones (con y sin `subcustomer_id`).
+
+ Listado paginado de reembolsos del customer con datos del `product_request` asociado. Filtro opcional `status` (array). `subcustomer_id` opcional → `core.product_requests.subcustomer_id`. Filtro de fechas sobre `refunds.created_at`.
+
+La pestaña **Body** incluye `subcustomer_id`.
+
+**Ejemplo — sin filtro por subcliente:**
+```json
+{
+  "customer_id": "customer_123",
+  "page": 1,
+  "limit": 20,
+  "status": ["CONFIRMED"]
+}
+```
+
+**Parámetros:**
+
+| Name | Type | Description |
+| --- | --- | --- |
+| customer_id | string | Campo del body: customer_id |
+| subcustomer_id | string | Campo del body: subcustomer_id |
+| page | number | Campo del body: page |
+| limit | number | Campo del body: limit |
+| status | array | Campo del body: status |
+
+### `about_webhook_guide`
 
 Guía para implementar webhooks del lado del cliente para recibir notificaciones de pagos y reembolsos
 
- **📋 IMPORTANTE: Implementación de Webhooks del Cliente Requerida**
+ **⚠️ ESTE ITEM NO ES UN ENDPOINT EJECUTABLE DE LA API.**
+
+Es una referencia informativa para integradores. La URL `about:client-webhook-guide` se usa a propósito para evitar que Postman lo ejecute como request HTTP del microservicio (no generará 404 contra el API). El contenido debe leerse solo como guía.
+
+---
+
+**📋 IMPORTANTE: Implementación de Webhooks del Cliente Requerida**
 
 Este NO es un endpoint de la API, sino una guía para implementar webhooks en TU sistema.