products-payment-refacil-mcp 1.2.6 → 1.2.8

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
@@ -676,13 +680,16 @@ Si el usuario decide comprar usando `/product-requests/create` con los **mismos
   "date": 1733932800000,
   "payload": {
     "quoteId": "a1b2c3d4-e5f6-7890-abcd-ef1234567890",
+    "productId": 52368,
+    "categoryId": 120,
     "amount": 150000,
-    "status": "SUCCESS",
-    "data": {
+    "additionalData": {
+      "invoiceDueDate": "2026-05-10",
       "reference": "123456789",
       "customerName": "JUAN PEREZ",
       "address": "Calle 123"
-    }
+    },
+    "quotedAt": "2024-01-11T10:30:00.000Z"
   }
 }
 ```
@@ -690,9 +697,11 @@ Si el usuario decide comprar usando `/product-requests/create` con los **mismos
 **Campos de la respuesta:**
 
 - `quoteId`: ID de la cotización guardada
+- `productId`: ID del producto cotizado
+- `categoryId`: ID de la categoría del producto
 - `amount`: Monto cotizado
-- `status`: Estado de la cotización (SUCCESS, INVALID, FAILED)
-- `data`: Datos adicionales del producto consultado
+- `additionalData`: Datos adicionales del producto consultado. Incluye `invoiceDueDate: string | null` cuando el proveedor retorna fecha de vencimiento de la factura; es `null` para productos que no aplican
+- `quotedAt`: Timestamp de la cotización
 
 **Respuesta de error (400) - Producto directo:**
 
@@ -776,7 +785,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 +807,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)
     
@@ -812,7 +821,9 @@ Los datos para crear esta solicitud provienen principalmente del endpoint `produ
     
 - `agreement` (string, opcional): Aceptación de términos (puede venir del campo `agreement` del producto)
     
-- `customer_id` (string, opcional): Identificador único del usuario o dispositivo
+- `customer_id` (string, requerido si omite `cart_id`; opcional si envía `cart_id`): Identificador único del usuario o dispositivo; persiste en `core.shopping_carts.user_temp_id` al crear carrito.
+    
+- `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 +901,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 +961,7 @@ GET /products/by-customer-and-category
         "amount": null,
         "meta": {
           "fnArgs": 20363,
+          "categoryId": 44,
           "form": [
             {
               "active": true,
@@ -986,7 +999,8 @@ GET /products/by-customer-and-category
   },
   "query_type": "BILLData",
   "sell_type": "Bill",
-  "agreement": "2010910"  
+  "agreement": "2010910",
+  "customer_id": "customer_123"
 }
 
  ```
@@ -1154,14 +1168,15 @@ Con la respuesta de este endpoint, puedes proceder a crear el pago usando `/prod
 
 | Name | Type | Description |
 | --- | --- | --- |
-| category_id * | number | mismo valor de `categoryId` usado al consultar `products/by-customer-and-category` |
+| 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 |
+| customer_id | string | Identificador único del usuario o dispositivo; persiste en `core.shopping_carts.user_temp_id` al crear carrito. |
+| 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 +1190,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)
     
@@ -1258,12 +1273,15 @@ POST /product-requests/status
       "customer_id": "customer_124"
     },
     "urlInvoice": "https://prep.refacil.co/#/factura/215765/10549",
-    "urlSummary": "https://mf-core.refacil.co/refacilpay/resumen/62/28137590-b69d-11f0-8c08-b71754a3ac6b"
+    "urlSummary": "https://mf-core.refacil.co/refacilpay/resumen/62/28137590-b69d-11f0-8c08-b71754a3ac6b",
+    "invoiceDueDate": "2026-05-31"
   }
 }
 
  ```
 
+> ⚠️ `invoiceDueDate` es `string | null` — tiene valor solo cuando el proveedor retorna fecha de vencimiento de la factura. En productos que no son facturas, siempre es `null`.
+
 **🛒 Flujo de Uso - Carrito Completo:**
 
 **1\. Consultar estado usando cartId:**
@@ -1308,7 +1326,8 @@ POST /product-requests/status
           "agreement": "2010910",
           "customer_id": "customer_124"
         },
-        "urlInvoice": "https://prep.refacil.co/#/factura/215765/10549"
+        "urlInvoice": "https://prep.refacil.co/#/factura/215765/10549",
+        "invoiceDueDate": "2026-05-31"
       }
     ]
   }
@@ -1387,7 +1406,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 +1683,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 +1701,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 +1709,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 +1834,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 +1915,12 @@ Los datos para crear este pago provienen de la respuesta del endpoint `product-r
 
 | Name | Type | Description |
 | --- | --- | --- |
-| cartId * | string | ID de la solicitud obtenido de `product-requests/create` |
+| 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 |
+| returnUrl * | string | URL de retorno después del pago |
+| webhookUrl * | string | URL para notificaciones de estado del pago |
 
 ### `products_payment_retry_sale`
 
@@ -2137,11 +2156,218 @@ Endpoints para crear reembolsos
 | email * | string | Email del cliente |
 | webhookUrl * | string | URL para notificaciones del reembolso |
 
-### `docs_cli_web_documentation`
+### `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`).
+
+ 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.