refacil-commerce-mcp 1.0.9 → 1.0.11

package/README.md

@@ -4,7 +4,7 @@ Servidor MCP (Model Context Protocol) generado automáticamente para la API refa
 
 ## 🚀 Características
 
-- **32 herramientas** generadas automáticamente desde la colección Postman
+- **33 herramientas** generadas automáticamente desde la colección Postman
 - **Autenticación flexible**: Username/SecretKey con renovación automática de tokens
 - **Servidor HTTP** con Fastify
 - **Protocolo MCP** estándar para integración con IDEs
@@ -214,6 +214,14 @@ To prevent abuse and repeated attempts in a short period, this endpoint applies
 
 If these limits are exceeded, the API will temporarily reject additional calls, effectively asking the client to **wait a moment before trying again**.
 
+### Token expiration
+
+The access token **expires after 2 hours of inactivity**—that is, after **2 consecutive hours** with **no** authenticated API request using that token. **Expiry is based on idle time, not on how long ago the token was issued.** Successful requests that send the token typically **reset the inactivity window**; integrations that may remain idle longer than **2 hours** should plan to log in again or treat auth errors as described in **Integration guidance**.
+
+### Integration guidance
+
+When a protected request fails because the token is **invalid or expired** (including after an idle timeout), the API may respond with **401 Unauthorized** or **403 Forbidden** (or another documented authentication error for this API). **Call this login again** to obtain a **new** token, update the `Authorization` header, and **retry the original request once**. Use a clear policy to avoid infinite loops: one login plus one retry per failed call is the standard pattern; if authentication still fails, stop retrying and investigate credentials, user blocking, or rate limits.
+
 ---
 
 ### Request Body
@@ -222,8 +230,6 @@ If these limits are exceeded, the API will temporarily reject additional calls,
     
 - `secretKey` (string) `required` - Secret key for authentication
     
-- `saveSession` (boolean) - Flag that, if sent as `false`, allows the generated token to have an expiration of 12 hours.
-    
 
 ---
 
@@ -237,7 +243,7 @@ If these limits are exceeded, the API will temporarily reject additional calls,
     
     - `tokenType` (string) - Type of the token (e.g., "Bearer").
         
-    - `token` (string) - The access code. It will not expire, unless the `saveSession` field is sent with the value `false`.
+    - `token` (string) - Bearer access token. It expires after **2 hours of inactivity** (see **Token expiration**).
         
 
 ---
@@ -255,7 +261,6 @@ If these limits are exceeded, the API will temporarily reject additional calls,
 | 400 | `validators.secretKey.required` | `El campo secretKey es obligatorio.` | `secretKey` is absent |
 | 400 | `validators.secretKey.isString` | `El campo secretKey debe ser de tipo string` | `secretKey` is not a string |
 | 400 | `validators.secretKey.isNotEmpty` | `El campo secretKey no puede estar vacío.` | `secretKey` is empty or whitespace-only |
-| 400 | — | `The saveSession field must be of type boolean.` | `saveSession` is present but not a boolean |
 | 400 | `auth.invalid` | `Credenciales inválidas` | User does not exist or incorrect password |
 | 400 | `user.blocked` | `Estás bloqueado` | User is blocked — do not retry; contact support (body may include `notify: true`) |
 | 400 | `auth.invalid.TimeOuthLoginFaild` | `No se ha superado el tiempo de bloqueo por intentos` | Account temporarily locked after failed login attempts. Body includes `code: 5002` and optionally `diferentTimes` (minutes remaining before unlock) |
@@ -858,19 +863,67 @@ The response will include the results of the query in case of success.
 | ownAgreementId | null | Campo del body: ownAgreementId |
 | data | object | Campo del body: data |
 
-### `query`
+### `query_convenio_vendo`
 
-**Important:** This request will be processed within a timeout of **30,000 milliseconds (30 seconds)**.
+---
+
+### Description
+
+This HTTP POST request is used to perform a custom query on the platform. The request body should be sent with the necessary parameters for the query in the format specified by the QueryBody object. The response will include the results of the query in case of success.
+
+---
+
+### Request Body Schema
+
+- productId (number) `required`: Identifier of the product to perform the query.
+    
+- queryType (string) `required`: Type of query to be performed.
+    
+- ownAgreementId (null): Identifier of the own agreement, if applicable.
+    
+- data (object) `required`: Additional data for the query.
+    
+    - reference (string) `required`: Reference for the query.
+        
 
-### Test Data
+---
 
-Use the following example values to test this endpoint in the QA environment:
+### Response Body Schema
 
-| Field | Example Value |
-|-------|---------------|
-| productId | 1587 |
-| queryType | "BILLData" |
-| data.reference | "63440172" |
+- message (string): Response message.
+    
+- messageCode (string): Code related to the response message.
+    
+- data (object): Response data object.
+    
+    - payload (object): Payload data.
+        
+        - amount (number): Amount related to the product.
+            
+        - productId (number): ID of the product.
+            
+        - productName (string): Name of the product.
+            
+        - reference (string): Reference related to the query.
+            
+        - hashEchoData (string): Hash echo data.
+            
+        - hash (string): Hash value.
+            
+        - amountEditable (boolean): Indicates if the amount is editable.
+
+**Parámetros:**
+
+| Name | Type | Description |
+| --- | --- | --- |
+| productId | number | Campo del body: productId |
+| queryType | string | Campo del body: queryType |
+| ownAgreementId | number | Campo del body: ownAgreementId |
+| data | object | Campo del body: data |
+
+### `query`
+
+**Important:** This request will be processed within a timeout of **30,000 milliseconds (30 seconds)**.
 
 **Parámetros:**
 
@@ -978,20 +1031,6 @@ Allows performing a sale on the platform. Send the request body with the necessa
                     
                 - `message`: String representing the message (required)
 
-### Test Data
-
-Use the following example values to test this endpoint in the QA environment:
-
-| Field | Example Value |
-|-------|---------------|
-| amount | 9999 |
-| productId | 1587 |
-| sellType | "Bill" |
-| data.agreement | 2010910 |
-| data.reference | "63440172" |
-| data.cellphone | "3203550000" |
-| data.hashEchoData | "eyJhZ3JlZW1lbnRJZCI6MzM3NDMsInJlZmVyZW5jZTEiOiI2MzQ0MDE3MiIsInJlZmVyZW5jZTIiOm51bGwsImFtb3VudCI6OTk5OSwiYWdyZWVtZW50TWVzc2FnZSI6IiIsImFncmVlbWVudENvZGUiOiIwMCIsInJlcXVpcmVzQW1vdW50IjoiMCIsImFkaXRpb25hbFZhbHVlNTRFY28iOiIwMTIzNDU2Nzg5MCIsImFkaXRpb25hbFZhbHVlNjJFY28iOiIxNTE2NTc4OTU1NjM0MjgxNjM4NzM5OTAyMjk1IiwiYWNjb3VudERhdGFBY3JlZGl0ZWQiOiI0NzU3NjY3MjA1ODE2Mzg3Mzk5MDIyOTUyMjc2IiwiYWRkaXRpb25hbENvbXBhbnlDb2RlIjoiMTUxNjU3ODk1NTYzNDI4MjgwNjI4MzcwMTIxMiIsImRhdGUiOiIyMDI2LTAzLTEwIiwidHJhY2UiOjUxMjF9" |
-
 **Parámetros:**
 
 | Name | Type | Description |
@@ -1061,19 +1100,6 @@ The following payload is required for performing a custom query:
     
 - `license`: (string, optional) The license plate of the vehicle.
 
-### Test Data
-
-Use the following example values to test this endpoint in the QA environment:
-
-| Field | Example Value |
-|-------|---------------|
-| queryType | "SOATData" |
-| productId | 91 |
-| docType | "NIT" |
-| document | "819000939" |
-| cellphone | "3200000000" |
-| license | "NAC854" |
-
 **Parámetros:**
 
 | Name | Type | Description |
@@ -1176,35 +1202,6 @@ The following payload is required for performing a custom sell:
 
 After the sale has been successfully completed, the response will follow a structure similar to the following. In this response, important information is provided, such as the balance of the main wallet and the balance of the profit wallet. Additionally, within the 'billData' object, you will find the fundamental information necessary to generate the sales receipt that will be delivered to the end customer. It is important to note that this step is mandatory, as it is a direct requirement from AXA Colpatria.
 
-### Test Data
-
-Use the following example values to test this endpoint in the QA environment:
-
-| Field | Example Value |
-|-------|---------------|
-| productId | 91 |
-| amount | 557400 |
-| data.amount.amount | 556400 |
-| data.amount.runt | 2100 |
-| data.amount.prima | 364700 |
-| data.amount.contributions | 189600 |
-| data.amount.valueDiscountLaw | 0 |
-| data.amount.valueDiscountTotal | 0 |
-| data.amount.valuePayDiscount | 556400 |
-| data.amount.amountAdministrative | 566 |
-| data.amount.amountTotal | 557400 |
-| data.amount.dateStart | "2024-06-04" |
-| data.amount.dateEnd | "2025-06-03" |
-| data.amount.discount | 0 |
-| data.license | "EJV885" |
-| data.hashEchoData | "eyJpZFRyYW5zYWNjaW9uIjoiMmE2MDhjY2YtZjdiOS00ZGM1LTg2OTQtYTAyY2E0ODNkOWE4IiwiaWRDb3JyZWxhY2lvbiI6MTcxNzUzNDY0MTc1MH0=" |
-| data.cifrateAmount.hash | "eyJhbW91bnQiOjU1NzQwMH0=" |
-| data.cifrateAmount.hashEchoData | "ef3e40f13fa0430eb1dfa9a8e499e3a4ea81c42159b5ee3eccac88d8ef47198e32d28339fcf656704009a0b05802363b3016d921bcfd6aa8920558535aa75218" |
-| data.userDetail.cellphone | "3200000000" |
-| data.userDetail.email | "test@email.com" |
-| data.userDetail.document | "860002964" |
-| data.userDetail.docType | "NIT" |
-
 **Parámetros:**
 
 | Name | Type | Description |
@@ -1935,40 +1932,6 @@ Allows performing a sale on the platform. Send the request body with the necessa
 
 **Important:** This response will be returned within a timeout of **60,000 milliseconds (60 seconds)**.
 
----
-
-## Request Schema
-
-- `productId`: Number representing the product identifier (required)
-    
-- `amount`: Number representing the payment amount (required)
-    
-- `data`: Object containing additional transaction data (required)
-    
-    - `cellphone`: String containing the customer's cellphone number (required)
-        
-    - `document`: String containing the customer's identification document number (required)
-        
-    - `name`: String containing the customer's first name (required)
-        
-    - `lastname`: String containing the customer's last name (required)
-        
-
----
-
-### Test Data
-
-Use the following example values to test this endpoint in the QA environment:
-
-| Field | Example Value |
-|-------|---------------|
-| productId | 603 |
-| amount | 100 |
-| data.cellphone | "3200000000" |
-| data.document | "1023900000" |
-| data.name | "Pachito" |
-| data.lastname | "Hernesto" |
-
 **Parámetros:**
 
 | Name | Type | Description |
@@ -1987,28 +1950,6 @@ Allows performing a sale on the platform. Send the request body with the necessa
 
 **Important:** This response will be returned within a timeout of **60,000 milliseconds (60 seconds)**.
 
----
-
-## Request Schema
-
-- `productId`: Number representing the product identifier (required)
-    
-- `data`: Object containing additional transaction data (required)
-    
-    - `cellphone`: String containing the customer's cellphone number (required)
-        
-
----
-
-### Test Data
-
-Use the following example values to test this endpoint in the QA environment:
-
-| Field | Example Value |
-|-------|---|
-| productId | 200048 |
-| data.cellphone | "3215302000" |
-
 **Parámetros:**
 
 | Name | Type | Description |
@@ -2108,16 +2049,6 @@ Allows performing a bill payment operation on the platform. Send the request bod
 
 **Important:** This response will be returned within a timeout of **60,000 milliseconds (60 seconds)**.
 
-### Test Data
-
-Use the following example values to test this endpoint in the QA environment:
-
-| Field | Example Value |
-|-------|---------------|
-| productId | 50 |
-| amount | 1000 |
-| data.cellphone | "3015874044" |
-
 **Parámetros:**
 
 | Name | Type | Description |
@@ -2219,17 +2150,6 @@ Allows performing a sale on the platform. Send the request body with the necessa
 
 **Important:** This response will be returned within a timeout of **60,000 milliseconds (60 seconds)**.
 
-### Test Data
-
-Use the following example values to test this endpoint in the QA environment:
-
-| Field | Example Value |
-|-------|---------------|
-| productId | 202 |
-| amount | 50 |
-| data.cellphone | "3015874029" |
-| data.email | "correo@refacil.com" |
-
 **Parámetros:**
 
 | Name | Type | Description |
@@ -2325,16 +2245,6 @@ Allows performing a bill payment operation on the platform. Send the request bod
                     
                 - `message`: String representing the message (required)
 
-### Test Data
-
-Use the following example values to test this endpoint in the QA environment:
-
-| Field | Example Value |
-|-------|---------------|
-| productId | 1014005 |
-| data.cellphone | "3104784242" |
-| data.email | "fake@refacil.com" |
-
 **Parámetros:**
 
 | Name | Type | Description |
@@ -2429,16 +2339,6 @@ Allows performing a bill payment operation on the platform. Send the request bod
                     
                 - `message`: String representing the message (required)
 
-### Test Data
-
-Use the following example values to test this endpoint in the QA environment:
-
-| Field | Example Value |
-|-------|---------------|
-| productId | 100777 |
-| data.cellphone | "3104784242" |
-| data.email | "fake@refacil.com" |
-
 **Parámetros:**
 
 | Name | Type | Description |
@@ -2533,16 +2433,6 @@ Allows performing a bill payment operation on the platform. Send the request bod
                     
                 - `message`: String representing the message (required)
 
-### Test Data
-
-Use the following example values to test this endpoint in the QA environment:
-
-| Field | Example Value |
-|-------|---------------|
-| productId | 1014004 |
-| data.cellphone | "3104784242" |
-| data.email | "fake@refacil.com" |
-
 **Parámetros:**
 
 | Name | Type | Description |
@@ -2550,7 +2440,7 @@ Use the following example values to test this endpoint in the QA environment:
 | data | object | Campo del body: data |
 | productId | number | Campo del body: productId |
 
-### `query_24`
+### `query_25`
 
 ---
 
@@ -2607,19 +2497,6 @@ If the request fails with the errorCode `product.errors.disabled` or a similar c
 
 **Important:** This request will be processed within a timeout of **30,000 milliseconds (30 seconds)**.
 
-### Test Data
-
-Use the following example values to test this endpoint in the QA environment:
-
-| Field | Example Value |
-|-------|---------------|
-| queryType | "ConfirmData" |
-| productId | 231 |
-| data.carrierId | 231 |
-| data.cellphone | "3203550000" |
-| data.amount | 10000 |
-| data.reference | "1234567" |
-
 **Parámetros:**
 
 | Name | Type | Description |
@@ -2729,19 +2606,6 @@ The timeout value specified below is directly established by the provider and mu
                     
                 - `message`: String representing the message (required)
 
-### Test Data
-
-Use the following example values to test this endpoint in the QA environment:
-
-| Field | Example Value |
-|-------|---------------|
-| productId | 231 |
-| amount | 10000 |
-| data.plan | "AP" |
-| data.reference | "1234567" |
-| data.cellphone | "3203550000" |
-| data.hashEchoData | "eyJub21icmVfY2xpZW50ZSI6IkVMU1kgU0VyVklDRSIsImRpcmVjY2lvbiI6IlVSQiBWSUxMQSBWSUNUT1JJQSBDQVNBIDEwMyAtIFNBTiBNQVJUSU4iLCJkbmlfY2xpZW50ZSI6IjM5MDIyMDMxIiwiY29udHJhdG8iOiIxMjM0NTY3IiwidmFsb3JfdmVudGEiOiIxMDAwMCIsInBsYW4iOiIiLCJ0eXBlIjoiIn0=" |
-
 **Parámetros:**
 
 | Name | Type | Description |
@@ -2752,7 +2616,7 @@ Use the following example values to test this endpoint in the QA environment:
 | sellType | string | Campo del body: sellType |
 | hash | string | Campo del body: hash |
 
-### `query_26`
+### `query_27`
 
 ---
 
@@ -2821,21 +2685,6 @@ If the request fails with the errorCode `product.errors.disabled` or a similar c
 
 **Important:** This request will be processed within a timeout of **30,000 milliseconds (30 seconds)**.
 
-### Test Data
-
-Use the following example values to test this endpoint in the QA environment:
-
-| Field | Example Value |
-|-------|---------------|
-| queryType | "ConfirmData" |
-| productId | 230 |
-| data.carrierId | 230 |
-| data.cellphone | "3203550000" |
-| data.amount | 10000 |
-| data.reference | "1234567" |
-| data.plan | "AP" |
-| data.type | "PT" |
-
 **Parámetros:**
 
 | Name | Type | Description |
@@ -2845,7 +2694,7 @@ Use the following example values to test this endpoint in the QA environment:
 | data | object | Campo del body: data |
 | ownAgreementId | null | Campo del body: ownAgreementId |
 
-### `sell_27`
+### `sell_28`
 
 ---
 
@@ -2958,22 +2807,6 @@ The timeout value specified below is directly established by the provider and mu
                     
                 - `message`: String representing the message (required)
 
-### Test Data
-
-Use the following example values to test this endpoint in the QA environment:
-
-| Field | Example Value |
-|-------|---------------|
-| productId | 230 |
-| amount | 10000 |
-| data.cellphone | "3203550000" |
-| data.plan | "AP" |
-| data.reference | "1234567" |
-| data.type | "PT" |
-| data.valorAseo | 5000 |
-| data.valorEnergia | 5000 |
-| data.hashEchoData | "eyJub21icmVfY2xpZW50ZSI6IkVMU1kgU0VyVklDRSIsImRpcmVjY2lvbiI6IlVSQiBWSUxMQSBWSUNUT1JJQSBDQVNBIDEwMyAtIFNBTiBNQVJUSU4iLCJkbmlfY2xpZW50ZSI6IjM5MDIyMDMxIiwiY29udHJhdG8iOiIxMjM0NTY3IiwidmFsb3JfdmVudGEiOiIxMDAwMCIsInZhbG9yX2FzZW8iOjUwMDAsInZhbG9yX2VuZXJnaWEiOjUwMDAsImNlbHVsYXIiOiIzMjAzNTUwMDAwIiwiaWRDb25maXJtYWNpb24iOiJzZGpha3NkamRqYS1kYXMwZGRhbnNkMDItZnNhZGthc2RrNTYiLCJwbGFuIjoiQVAiLCJ0eXBlIjoiUFQifQ==" |
-
 **Parámetros:**
 
 | Name | Type | Description |
@@ -2984,7 +2817,7 @@ Use the following example values to test this endpoint in the QA environment:
 | sellType | string | Campo del body: sellType |
 | hash | string | Campo del body: hash |
 
-### `query_28`
+### `query_29`
 
 Here you will find all the endpoints related to Transfiya correspondent selling.
 
@@ -3232,23 +3065,6 @@ curl --location --globoff 'https://acme.refacil.local/transfiYaNotifications' \
 
 **Step 9: Transaction marked as failed:** If the transaction status changes to "REJECTED," the transaction is officially marked as failed within the system.
 
----
-
-## Request Schema
-
-- `productId`: Number representing the product identifier (required)
-    
-- `amount`: Number representing the transaction amount in cents (required)
-    
-- `webhookUrl`: String containing the URL to receive transaction status notifications (required)
-    
-- `data`: Object containing additional transaction data (required)
-    
-    - `cellphone`: String containing the customer's cellphone number (required)
-        
-    - `bankName`: String containing the target bank name (required)
-        
-
 ---
 
 ### Test Phone Numbers
@@ -3416,23 +3232,6 @@ Automatically rejected: 3002491283
     
 - **No commission processing**: Since the transaction failed, no commissions are processed for this transaction.
 
----
-
-## Request Schema
-
-- `productId`: Number representing the product identifier (required)
-    
-- `amount`: Number representing the deposit amount in cents (required)
-    
-- `webhookUrl`: String containing the URL to receive transaction status notifications (required)
-    
-- `data`: Object containing additional transaction data (required)
-    
-    - `cellphone`: String containing the customer's cellphone number (required)
-        
-    - `bankName`: String containing the target bank name for the deposit (required)
-        
-
 ---
 
 ### Test Phone Numbers