refacil-commerce-mcp

v1.0.0

Published

16 hours ago

MCP Server para la API refacil-commerce

0High
0Medium
0Low

erik-rodriguez

mcp model-context-protocol mcp-server refacil-commerce api anthropic claude cursor

refacil-commerce MCP Server

Servidor MCP (Model Context Protocol) generado automáticamente para la API refacil-commerce.

🚀 Características

71 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

📋 Requisitos

Node.js 20+
npm o yarn

📦 Instalación desde NPM

Si este paquete está publicado en npm, puedes instalarlo globalmente:

# Instalación global (recomendado)
npm install -g refacil-commerce-mcp

# Verificar instalación
refacil-commerce-mcp --version

Configuración Rápida en IDEs

Cursor

Abrir Settings → Features → Model Context Protocol
Click en "Edit Config"
Agregar:

Windows: %APPDATA%\Cursor\User\globalStorage\saoudrizwan.claude-dev\settings\cline_mcp_settings.json

macOS/Linux: ~/.config/Cursor/User/globalStorage/saoudrizwan.claude-dev/settings/cline_mcp_settings.json

{
  "mcpServers": {
    "refacil-commerce": {
      "command": "refacil-commerce-mcp",
      "env": {
        "BASE_URL": "https://commerce-api.qa.refacil.co",
        "USERNAME": "tu-usuario",
        "SECRET_KEY": "tu-secret-key",
        "AUTH_ENDPOINT": "/auth/login-api",
        "TOKEN_CACHE_TTL": "3600"
      }
    }
  }
}

Reiniciar Cursor

Claude Desktop

Editar archivo de configuración:

Windows: %APPDATA%\Claude\claude_desktop_config.json

macOS: ~/Library/Application Support/Claude/claude_desktop_config.json

Linux: ~/.config/Claude/claude_desktop_config.json

{
  "mcpServers": {
    "refacil-commerce": {
      "command": "refacil-commerce-mcp",
      "env": {
        "BASE_URL": "https://commerce-api.qa.refacil.co",
        "USERNAME": "tu-usuario",
        "SECRET_KEY": "tu-secret-key",
        "AUTH_ENDPOINT": "/auth/login-api",
        "TOKEN_CACHE_TTL": "3600"
      }
    }
  }
}

Reiniciar Claude Desktop.

Visual Studio Code

Instalar extensión MCP for VS Code
Editar settings.json:

{
  "mcp.servers": {
    "refacil-commerce": {
      "command": "refacil-commerce-mcp",
      "env": {
        "BASE_URL": "https://commerce-api.qa.refacil.co",
        "USERNAME": "tu-usuario",
        "SECRET_KEY": "tu-secret-key",
        "AUTH_ENDPOINT": "/auth/login-api",
        "TOKEN_CACHE_TTL": "3600"
      }
    }
  }
}

Recargar VS Code

🛠️ Instalación para Desarrollo

Si quieres contribuir o ejecutar desde el código fuente:

# Clonar el repositorio
git clone https://github.com/refacil/refacil-commerce-mcp.git
cd refacil-commerce-mcp

# Instalar dependencias
npm install

# Construir el proyecto
npm run build

# Iniciar en desarrollo
npm run dev

# Iniciar en producción
npm start

🔧 Configuración

El servidor se configura mediante variables de entorno:

# Copiar archivo de ejemplo
cp .env.example .env

# Editar configuración
nano .env

Variables de Entorno

| Variable | Descripción | Valor por defecto | |----------|-------------|-------------------| | PORT | Puerto del servidor | 3009 | | ENVIRONMENT | Entorno de ejecución | development | | BASE_URL | URL base de la API | https://commerce-api.qa.refacil.co | | USERNAME | Usuario para autenticación | your_username_here | | SECRET_KEY | Secret key para autenticación | your_secret_key_here | | AUTH_ENDPOINT | Endpoint de autenticación | /auth/login-api | | TOKEN_CACHE_TTL | TTL del caché de tokens (segundos) | 3600 | | MCP_TOKEN | Token de autenticación del MCP | mcp-secret-token-refacil-pay |

🐳 Docker

# Construir imagen
docker build -t refacil-commerce-mcp .

# Ejecutar contenedor
docker run -p 3009:3009 refacil-commerce-mcp

# O usar docker-compose
docker-compose up

☸️ Kubernetes

# Aplicar manifests
kubectl apply -f k8s/

# Verificar despliegue
kubectl get pods -l app=refacil-commerce-mcp

🔌 Uso del MCP

Endpoints Disponibles

/mcp: Endpoint principal del protocolo MCP
/health: Health check del servidor
/tools: Lista de herramientas disponibles

🛠️ Herramientas Disponibles

`admin_update_balance`

Description

It allows you to transfer funds from the main users money bag to the bag of the user who is being added. The token of the user who will be the beneficiary and the amount must be added.

Request Body

userToken (string, required): The user token for which the balance will be updated
amount (number, required): Amount to be updated

Response

message: String containing a message about the operation result (required)
messageCode: String code indicating the operation result (required)
data: Object containing additional response data.

Parámetros:

| Name | Type | Description | | --- | --- | --- | | userToken | string | Campo del body: userToken | | amount | number | Campo del body: amount |

`admin_locations_states`

Description

Get all states, then you can search cities by state id in the /locations/cities/{stateId} service

Request Body

This endpoint does not require a request body.

Response

message: String containing a message about the operation result (required)
messageCode: String code indicating the operation result (required)
data: Object containing additional response data (required)
- items: Array of objects containing the states

`admin_locations_cities`

Description

Get all cities by state id

Parameters Path

stateId (number, required): State Id

Response

message: String containing a message about the operation result (required)
messageCode: String code indicating the operation result (required)
data: Object containing additional response data (required)
- items: Array of objects containing the cities by state id

`auth_login_api`

API Login

Description

Allows API users to log in using their credentials. This operation authenticates the API user using the information provided in the request body. If the credentials are valid, an access token is issued, which must be included in subsequent requests to access protected resources on the platform. Make sure to include the token in the authorization header using the "Bearer" prefix in future requests. The response will include the token type ("Bearer") and the access token.

Request Body

username (string) required- Username for authentication.
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.

Response

messageCode (string) - Code for the message.
message (string) - The message from the response.
data
- 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.

Parámetros:

| Name | Type | Description | | --- | --- | --- | | username | string | Campo del body: username | | secretKey | string | Campo del body: secretKey |

`commerce_register`

Register Commerce

Description

Registers a new commerce in the system using the information provided in the request body. This method returns a response that includes the unique identifier of the user associated with the commerce.

Request Body

name (string) required: Owner's name of the commerce.
lastname (string) required: Owner's last name of the commerce
docType (string)required: Document type of the commerce owner.
docNumber (string)required: Document number of the commerce owner.
expeditionDate (string): Expedition date of the document of the commerce owner. The date must have the following structure YYYY-MM-DD
username (string)required: Username of the commerce owner.
cellphone (string)required: Commerce owner's mobile phone number. Please enter a valid mobile phone number for Colombia. It must contain 10 digits and start with the prefix '3'.
email (string)required: Commerce owner's email.
commerceType (number): Identifier of the commerce type. To get valid values, consult the /base-info/commerce-types service. Make sure to provide a valid number for this field. This field is optional, and if not provided, it will default to "1," which corresponds to the "Store" commerce type.
commerceName (string)required: The name of the commerce.
latitude (number): Latitude of the commerce location.
longitude (number): Longitude of the commerce location.
address (string)required: Commerce address. Since the field is of type string, the address can be provided in any standard format.
cityName (string)required: City name where the commerce is located. It is recommended to enter only valid city names. If no matches are found, 'Bogota' will be used as the default city.

Response Body

message (string): A message related to the response.
messageCode (string): A code associated with the message.
data (object): An object containing the following fields:
- tokenType (string): The type of token.
- token (string): The token for authentication. It will not expire.
- userId (number): The unique identifier of the user associated with the commerce.
- message (string): A message related to the response.

Parámetros:

| Name | Type | Description | | --- | --- | --- | | name | string | Campo del body: name | | lastname | string | Campo del body: lastname | | docType | string | Campo del body: docType | | docNumber | string | Campo del body: docNumber | | username | string | Campo del body: username | | cellphone | string | Campo del body: cellphone | | email | string | Campo del body: email | | commerceType | number | Campo del body: commerceType | | commerceName | string | Campo del body: commerceName | | address | string | Campo del body: address | | cityName | string | Campo del body: cityName | | balance | string | Campo del body: balance |

`commerce_get_info`

Description

Retrieve detailed information about a commerce using its identification. This operation requires sending an object in the request body with the "userId" property specifying the user ID. The response will include information about balances, additional data, and more. Balances include: "tmpBalance" (Earnings Bag), "posBalance" (Multiproduct Bag), and "debt" (Debt Bag).

Request Body

userId (number, required): The user ID for which detailed information is to be retrieved.

Response

message: String containing a message about the operation result (required)
messageCode: String code indicating the operation result (required)
data: Object containing additional response data (required)
- additionalData: Object containing user-related data (required)
  - username: String representing the username (required)
  - token: String representing the token. It will not expire. (required)
- balances: Object containing balance-related data (required)
  - tmpBalance: Number representing the temporary balance (required)
  - posBalance: Number representing the balance after the operation (required)
    debt: Number representing the debt amount (required)

Parámetros:

| Name | Type | Description | | --- | --- | --- | | userId | number | Campo del body: userId |

`commerce_users`

Description

Retrieve a list of users associated with a commerce using the token provided in the request header. This method supports pagination and search by name or user id.

Request Body

This endpoint does not require a request body.

Response

message: String containing a message about the operation result (required)
messageCode: String code indicating the operation result (required)
data: Object containing additional response data (required)
- items: Array of objects containing the users associated with the commerce

`commerce_updatebalance`

Update Commerce Balance

Description

UpdateBalance:

This service allows loading balance to the different merchants created, by deducting from the Parent Merchant’s balance pool. The transactions generated will be reflected in the reports assigned to the merchant within the portal provided by Super Pagos.

The required sending parameters are the token and ID, which were returned when the merchant was created.

Request Body Schema

token (string)required: Owner's balance of the commerce.
balance (number)required: Owner's balance of the commerce.

Response Body Schema

message (string): A message related to the response.
messageCode (string): A code associated with the message.

Parámetros:

| Name | Type | Description | | --- | --- | --- | | token | string | Campo del body: token | | balance | number | Campo del body: balance |

`base_info_commerce_types`

Retrieve Commerce Types

Description

Retrieve the available commerce types in the application. This operation provides detailed information about the different types of commercial establishments that can operate on the platform.

Request Body

This endpoint does not require a request body.

Response Body

message (string): A message indicating the status of the response.
messageCode (string): A code associated with the message.
data (array): An array containing the commerce types information.
- id (number): The unique identifier for the commerce type.
- name (string): The name of the commerce type.

`report_details`

Retrieve Commerce Report Details

Description

Get details to build a report. This service is responsible for returning the necessary details to generate a report. To provide more context about the service, it will return an array of objects. Each object in this array will contain attributes that are essential for the construction of a report. These attributes may include, but are not limited to, type of report, the bag to consult, options to load in a select and other relevant data that are needed for a complete and detailed report. The use of this method will facilitate the generation of reports by providing all the necessary data in a structured and easy-to-use way.

Request Body

No request body is required for this GET request.

Response Body

description (string, optional): Description of the commerce report.
form (object):
- fields (array):
  - name (string): Name of the field.
  - type (string): Type of the field.
  - options (array):
    - label (string): Label for the option.
    - value (null): Value of the option.
  - label (string): Label for the field.
  - placeholder (string): Placeholder for the field.
  - required (boolean): Indicates if the field is required.
- bag (string): Bag information.
- typeReport (string): Type of the report.
endpoint (string): The endpoint for the commerce report generate.

`report_generate`

Sales report

Description

This service is responsible for generating different types of reports depending on the filters that are sent.

Request Body

filters (object, required): Filters for the report
- dateStart (string, required)
- dateEnd (string, required)
- carrierId (null, optional)
- number (string, optional)
- status (string, optional)
- bag (string, optional)
typeReport (string, required): Type of the report

Response

messageCode (string)
message (string)
data (object)
- title (string)
- header (array of strings)
- data (array of arrays)

Parámetros:

| Name | Type | Description | | --- | --- | --- | | filters | object | Campo del body: filters | | typeReport | string | Campo del body: typeReport |

`generate_purchase_report`

Purchase report

Description

This service is responsible for generating different types of reports depending on the filters that are sent.

Request Body

filters (object, required): Filters for the report
- dateStart (string, required): Start date for the report.
- dateEnd (string, required): End date for the report.
- carrierId (string, optional): ID of the carrier.
- number (string, optional): Commerce number.
- status (string, optional): Status of the commerce.
- bag (string, optional): Bag information.
typeReport (string, required): Type of the report.

Response

messageCode (string): Code for the message.
message (string): Details of the message.
data (object)
- title (string): Title of the report.
- header (array of strings): Headers for the report data.
- total (number): Total count of the report data.
- data (array of arrays): Report data.

Parámetros:

| Name | Type | Description | | --- | --- | --- | | filters | object | Campo del body: filters | | typeReport | string | Campo del body: typeReport |

`generate_statement_report`

Statement report

Description

This endpoint allows you to generate a report with the specified filters and report type.

Request Body

Type: JSON

Response

Type: JSON

| Property | Type | Description | | --- | --- | --- | | messageCode | string | A code associated with the response message. | | message | string | A human-readable message providing information about the response. | | data | object | An object containing report title, header, and totals. | | title | string | The title of the report. | | header | array | An array containing report headers. | | totals | object | An object containing various total amounts for the report. | | data | array | An array containing report data. |

Note: The actual data in the response may vary based on the report generated.

Parámetros:

| Name | Type | Description | | --- | --- | --- | | filters | object | Campo del body: filters | | typeReport | string | Campo del body: typeReport |

`generate_payment_report`

Payment report

Description

This service is responsible for generating different types of reports depending on the filters that are sent.

Request Body

Type: JSON

Response

Type: JSON

Parámetros:

| Name | Type | Description | | --- | --- | --- | | filters | object | Campo del body: filters | | typeReport | string | Campo del body: typeReport |

`generate_transfer_report`

Transfer report

Description

This endpoint allows you to generate a report based on the specified filters.

Request Body

filters (object, required): An object containing the filters for the report.
- dateStart (string, required): The start date for the report.
- dateEnd (string, required): The end date for the report.
- carrierId (null): The ID of the carrier for the report.
- number (string): The report number.
- status (string): The status for the report.
- bag (string): The bag for the report.
typeReport (string, required): The type of report to be generated.

Response

messageCode (string): The code for the message.
message (string): The message related to the response.
data (object): An object containing the report data.
- title (string): The title of the report.
- header (array): An array containing the headers for the report data.
- data (array): An array containing the report data.

Parámetros:

| Name | Type | Description | | --- | --- | --- | | filters | object | Campo del body: filters | | typeReport | string | Campo del body: typeReport |

`generate_reverse_report`

Reverse report

Description

This endpoint allows you to generate a report based on the specified filters.

Request Body

filters (object, required): An object containing the filters for the report.
- dateStart (string, required): The start date for the report.
- dateEnd (string, required): The end date for the report.
- carrierId (null): The ID of the carrier for the report.
- number (string): The report number.
- status (string): The status for the report.
- bag (string): The bag for the report.
typeReport (string, required): The type of report to be generated.

Response

messageCode (string): The code for the message.
message (string): The message related to the response.
data (object): An object containing the report data.
- title (string): The title of the report.
- header (array): An array containing the headers for the report data.
- data (array): An array containing the report data.

Parámetros:

| Name | Type | Description | | --- | --- | --- | | filters | object | Campo del body: filters | | typeReport | string | Campo del body: typeReport |

`generate_consumption_report`

Consumption report

Description

This endpoint allows you to generate a report based on the specified filters.

Request Body

filters (object, required): An object containing the filters for the report.
- dateStart (string, required): The start date for the report.
- dateEnd (string, required): The end date for the report.
- carrierId (null): The ID of the carrier for the report.
- number (string): The report number.
- status (string): The status for the report.
- bag (string): The bag for the report.
typeReport (string, required): The type of report to be generated.

Response

messageCode (string): The code for the message.
message (string): The message related to the response.
data (object): An object containing the report data.
- title (string): The title of the report.
- header (array): An array containing the headers for the report data.
- data (array): An array containing the report data.

Parámetros:

| Name | Type | Description | | --- | --- | --- | | filters | object | Campo del body: filters | | typeReport | string | Campo del body: typeReport |

`payment_generate_resource`

Description

Generates a payment resource in the system using the information provided in the request body. This method returns a response that includes details about the generated resource, such as the URL, reference, resource identifier, and expiration time.

Request Body

productId (number, required): Identifier of the product for which the resource will be generated.
amount (number, required): Amount of the resource to be generated.
moduleId (number, required): Identifier of the module to which the generated resource will be associated.
form (object): Optional form associated with the resource.
- cellphone (string): The cellphone number.
customerReference (string, required): A reference to the customer.

Response Body

message (string): A message related to the response.
messageCode (string): A code related to the message.
data (object): An object containing the response data.
- message (string): A message related to the response data.
- date (number): The date related to the response data.
- payload (object): An object containing the payload data.
  - url (string): The URL of the generated resource.
  - reference (string): The reference of the generated resource.
  - resourceId (string): The identifier of the generated resource.
  - expiresIn (string): The expiration time of the generated resource.
  - type (string): The type of the generated resource.
  - data (string): Additional data related to the generated resource.
  - status (number): The status of the generated resource.

Parámetros:

| Name | Type | Description | | --- | --- | --- | | productId | number | Campo del body: productId | | amount | number | Campo del body: amount | | moduleId | number | Campo del body: moduleId | | form | object | Campo del body: form | | customerReference | string | Campo del body: customerReference |

`generate_resource_nequi`

Description

Request Body

productId (number, required): Identifier of the product for which the resource will be generated.
amount (number, required): Amount of the resource to be generated.
moduleId (number, required): Identifier of the module to which the generated resource will be associated.
form (object): Optional form associated with the resource.
- cellphone (string): The cellphone number.
customerReference (string, required): A reference to the customer.

Response Body

message (string): A message related to the response.
messageCode (string): A code associated with the message.
data (object): An object containing data related to the response.
- message (string): A message related to the data.
- date (number): The date associated with the data.
- payload (object): An object containing the payload data.
  - url (string): The URL of the generated resource.
  - reference (string): The reference of the generated resource.
  - resourceId (string): The identifier of the generated resource.
  - expiresIn (string): The expiration time of the resource.
  - type (string): The type of the resource.
  - data (string): Additional data related to the resource.
  - status (number): The status of the resource.

Parámetros:

`generate_resource_daviplata`

Description

Request Body

productId (number, required): Identifier of the product for which the resource will be generated.
amount (number, required): Amount of the resource to be generated.
moduleId (number, required): Identifier of the module to which the generated resource will be associated.
form (object):
- typePerson (string): Type of person.
- documentType (string): Type of document.
- documentNumber (string): Document number.
- name (string): Name of the customer.
- email (string): Email of the customer.
- cellphone (string): Cellphone number of the customer.
customerReference (string, required): Reference related to the customer.

Response Body

message (string): A message related to the response.
messageCode (string): A code related to the message.
data (object):
- message (string): A message related to the data.
- date (number): Date related to the data.
- payload (object):
  - url (string): The URL of the generated resource.
  - reference (string): Reference of the resource.
  - resourceId (string): Identifier of the resource.
  - expiresIn (string): Expiration time of the resource.
  - type (string): Type of the resource.
  - data (string): Additional data related to the resource.
  - status (number): Status of the resource.

Parámetros:

`generate_resource_bancolombia`

Generate Payment Resource

Description

Creates a payment resource in the system using the provided information.

Request Body

productId (number, required): Identifier of the product for which the resource will be generated.
amount (number, required): Amount of the resource to be generated.
moduleId (number, required): Identifier of the module to which the generated resource will be associated.
form (object): Optional form associated with the resource.
customerReference (string): Customer reference information.

Response Body

message (string): A message related to the response.
messageCode (string): A code related to the message.
data (object): The response data.
- message (string): A message related to the data.
- date (number): The date related to the data.
- payload (object): The payload data.
  - url (string): The URL of the generated resource.
  - reference (string): The reference of the resource.
  - resourceId (string): The identifier of the resource.
  - expiresIn (string): The expiration time of the resource.
  - type (string): The type of the resource.
  - data (string): Additional data related to the resource.
  - status (number): The status of the resource.

Parámetros:

`generate_resource_nequi_22`

Description

Request Body

productId (number, required): Identifier of the product for which the resource will be generated.
amount (number, required): Amount of the resource to be generated.
moduleId (number, required): Identifier of the module to which the generated resource will be associated.
form (object): Optional form associated with the resource.
- cellphone (string): The cellphone number.
customerReference (string, required): A reference to the customer.

Response Body

message (string): A message related to the response.
messageCode (string): A code associated with the message.
data (object): An object containing data related to the response.
- message (string): A message related to the data.
- date (number): The date associated with the data.
- payload (object): An object containing the payload data.
  - url (string): The URL of the generated resource.
  - reference (string): The reference of the generated resource.
  - resourceId (string): The identifier of the generated resource.
  - expiresIn (string): The expiration time of the resource.
  - type (string): The type of the resource.
  - data (string): Additional data related to the resource.
  - status (number): The status of the resource.

Parámetros:

`generate_resource_daviplata_23`

Description

Request Body

productId (number, required): Identifier of the product for which the resource will be generated.
amount (number, required): Amount of the resource to be generated.
moduleId (number, required): Identifier of the module to which the generated resource will be associated.
form (object):
- typePerson (string): Type of person.
- documentType (string): Type of document.
- documentNumber (string): Document number.
- name (string): Name of the customer.
- email (string): Email of the customer.
- cellphone (string): Cellphone number of the customer.
customerReference (string, required): Reference related to the customer.

Response Body

message (string): A message related to the response.
messageCode (string): A code related to the message.
data (object):
- message (string): A message related to the data.
- date (number): Date related to the data.
- payload (object):
  - url (string): The URL of the generated resource.
  - reference (string): Reference of the resource.
  - resourceId (string): Identifier of the resource.
  - expiresIn (string): Expiration time of the resource.
  - type (string): Type of the resource.
  - data (string): Additional data related to the resource.
  - status (number): Status of the resource.

Parámetros:

`generate_resource_pse`

Generate Payment Resource

Description

This endpoint allows you to generate a payment resource in the system.

Request Body

productId (number, required): Identifier of the product for which the resource will be generated.
amount (number, required): Amount of the resource to be generated.
moduleId (number, required): Identifier of the module to which the generated resource will be associated.
form (object): Optional form associated with the resource.
- bankId (string): The ID of the bank.
- typePerson (string): The type of person.
- documentType (string): The type of document.
- documentNumber (string): The document number.
- name (string): The name of the customer.
- email (string): The email of the customer.
- cellphone (string): The cellphone number of the customer.
customerReference (string, required): The reference for the customer.

Response

message (string): A message related to the response.
messageCode (string): A code related to the message.
data (object):
- message (string): A message related to the data.
- date (number): The date of the response.
- payload (object):
  - url (string): The URL of the generated resource.
  - reference (string): The reference of the generated resource.
  - resourceId (string): The identifier of the generated resource.
  - expiresIn (string): The expiration time of the resource.
  - type (string): The type of the resource.
  - data (string): Additional data related to the resource.
  - status (number): The status of the resource.

Parámetros:

`generate_res_ban_dir_al_banco`

Description

Request Body

productId (number, required): Identifier of the product for which the resource will be generated.
amount (number, required): Amount of the resource to be generated.
moduleId (number, required): Identifier of the module to which the generated resource will be associated.
customerReference (string, required): A reference related to the customer.

Response Body

message (string): A message related to the response.
messageCode (string): A code related to the message.
data (object)
- message (string): A message related to the data.
- date (number): The date related to the data.
- payload (object)
  - url (string): The URL of the generated resource.
  - reference (string): The reference of the generated resource.
  - resourceId (string): The identifier of the generated resource.
  - expiresIn (string): The expiration time of the generated resource.
  - type (string): The type of the generated resource.
  - data (string): Additional data related to the generated resource.
  - status (number): The status of the generated resource.

Parámetros:

| Name | Type | Description | | --- | --- | --- | | productId | number | Campo del body: productId | | amount | number | Campo del body: amount | | moduleId | number | Campo del body: moduleId | | customerReference | string | Campo del body: customerReference |

`generate_res_ban_esc_qr`

Generate Payment Resource

Description

Generates a payment resource in the system using the information provided in the request body.

Request Body

productId (number, required): Identifier of the product for which the resource will be generated.
amount (number, required): Amount of the resource to be generated.
moduleId (number, required): Identifier of the module to which the generated resource will be associated.
customerReference (string, required): Reference to the customer.

Response

The response is a JSON object with the following properties:

message (string): A message, if any.
messageCode (string): A code associated with the message.
data (object): The data object containing the following properties:
- message (string): A message, if any.
- date (number): The date associated with the response.
- payload (object): The payload object containing the following properties:
  - url (string): The URL of the generated resource.
  - reference (string): The reference of the resource.
  - resourceId (string): The identifier of the resource.
  - expiresIn (string): The expiration time of the resource.
  - type (string): The type of resource.
  - data (string): Additional data associated with the resource.
  - status (number): The status of the resource.

Parámetros:

| Name | Type | Description | | --- | --- | --- | | productId | number | Campo del body: productId | | amount | number | Campo del body: amount | | moduleId | number | Campo del body: moduleId | | customerReference | string | Campo del body: customerReference |

`generate_resource_tarjeta_de_recaudo`

Description

Request Body

productId (number, required): Identifier of the product for which the resource will be generated.
moduleId (number, required): Identifier of the module to which the generated resource will be associated.
customerReference (string): The reference of the customer.

Response

message (string): A message from the response.
messageCode (string): A code associated with the message.
data (object)
- message (string): A message within the data object.
- date (number): The date associated with the response.
- payload (object)
  - url (string): The URL of the generated resource.
  - reference (string): The reference of the resource.
  - resourceId (string): The identifier of the resource.
  - expiresIn (string): The expiration time of the resource.
  - type (string): The type of the resource.
  - data (string): Additional data associated with the resource.
  - status (number): The status of the resource.

Parámetros:

| Name | Type | Description | | --- | --- | --- | | productId | number | Campo del body: productId | | moduleId | number | Campo del body: moduleId | | customerReference | string | Campo del body: customerReference |

`payment_get_resource`

Retrieve Payment Resource

Description

Retrieve a payment resource in the system using the provided customer reference as a parameter. This method returns a response that includes details about the retrieved resource.

Request Body Schema

There is no request body for this GET request.

Response Body Schema

message (string): A message related to the response.
messageCode (string): A code associated with the message.
data (object)
- payload (object)
  - url (string): The URL associated with the resource.
  - reference (string): The reference of the resource.
  - resourceId (string): The ID of the resource.
  - expiresIn (string): The expiration time of the resource.
  - type (string): The type of the resource.
  - data (string): Additional data related to the resource.
  - status (number): The status of the resource.

This method returns a response that includes details about the retrieved resource.

`payment_pse_banks`

PSE Banks

Description

This service allows you to obtain the banks available to make PSE payments.

Request Body Schema

There is no request body for this GET request.

Response Body Schema

message (string): A message related to the response.
messageCode (string): A code associated with the message.
data (object)
- banks: An array of object with the banks information (id, name and image)

`product_list`

Retrieve Product List

Retrieve a list of active products in the system. This service provides detailed information about the available products for querying. You can filter the results using the optional "type" parameter.

Query Parameters

type (optional): Type of products to list. If provided and set to "bills," it will list products related to invoices; otherwise, it will list all products except those related to invoices and packages.

Example:

type: bills

Response

The response of this request is a JSON schema representing the list of products. An example response schema is as follows:

{
    "message": "",
    "messageCode": "",
    "data": [
        {
            "id": 0,
            "categoryId": 0,
            "name": "",
            "needValidation": true,
            "moduleId": 0,
            "maxFixedTip": 0,
            "description": "",
            "amount": 0,
            "sort": 0,
            "meta": {},
            "image": "",
            "status": ""
        }
    ]
}

Type of products to list. If provided and set to "bills," it will list products related to invoices; otherwise, it will list all products except those related to invoices and packages.

Example : bills

`product_packages`

Retrieve Available Packages

Description

This endpoint retrieves a list of available packages in the system. The response is in JSON format and provides detailed information about the packages, which may contain multiple products.

Note: It is necessary to use this service to keep the packages updated for any changes that occur.

Response

The response for this request can be documented as a JSON schema:

{
  "type": "object",
  "properties": {
    "message": {
      "type": "string"
    },
    "messageCode": {
      "type": "string"
    },
    "data": {
      "type": "array",
      "items": {
        "type": "object",
        "properties": {
          "id": {
            "type": "integer"
          },
          "name": {
            "type": "string"
          },
          "description": {
            "type": "string"
          },
          "categories": {
            "type": "array",
            "items": {
              "type": "object",
              "properties": {
                "id": {
                  "type": "integer"
                },
                "name": {
                  "type": "string"
                },
                "description": {
                  "type": "string"
                },
                "products": {
                  "type": "array",
                  "items": {
                    "type": "object",
                    "properties": {
                      "id": {
                        "type": "integer"
                      },
                      "categoryId": {
                        "type": "integer"
                      },
                      "name": {
                        "type": "string"
                      },
                      "needValidation": {
                        "type": "boolean"
                      },
                      "moduleId": {
                        "type": "integer"
                      },
                      "maxFixedTip": {
                        "type": "integer"
                      },
                      "description": {
                        "type": "string"
                      },
                      "amount": {
                        "type": "integer"
                      },
                      "sort": {
                        "type": "integer"
                      },
                      "meta": {
                        "type": "object"
                      },
                      "image": {
                        "type": "string"
                      },
                      "status": {
                        "type": "string"
                      }
                    },
                    "required": [
                      "id",
                      "categoryId",
                      "name",
                      "needValidation",
                      "moduleId",
                      "maxFixedTip",
                      "description",
                      "amount",
                      "sort",
                      "meta",
                      "image",
                      "status"
                    ]
                  }
                },
                "internalName": {
                  "type": "string"
                }
              },
              "required": [
                "id",
                "name",
                "description",
                "products",
                "internalName"
              ]
            }
          },
          "internalName": {
            "type": "string"
          }
        },
        "required": [
          "id",
          "name",
          "description",
          "categories",
          "internalName"
        ]
      }
    }
  },
  "required": [
    "message",
    "messageCode",
    "data"
  ]
}

`product_commissions`

Retrieve Product Commissions

Description

Retrieve detailed information about the commissions associated with registered products.

Response

The response for this request is a JSON object with the following schema:

{
  "type": "object",
  "properties": {
    "message": {"type": "string"},
    "messageCode": {"type": "string"},
    "data": {
      "type": "array",
      "items": {
        "type": "object",
        "properties": {
          "id": {"type": "number"},
          "name": {"type": "string"},
          "image": {"type": "string"},
          "fixedCommission": {"type": "object"},
          "maxFixedCommission": {"type": "number"},
          "commission": {"type": "number"},
          "commissionType": {"type": "string"},
          "amount": {"type": "object"},
          "category": {"type": "string"},
          "key": {"type": "string"},
          "overdraft": {"type": "number"}
        }
      }
    }
  }
}

`product_categories`

Retrieve Product Categories

Description

This service provides detailed information on the categories and their subcategories.

Response

The response for this request can be documented as a JSON schema:

{
  "type": "object",
  "properties": {
    "message": {
      "type": "string"
    },
    "messageCode": {
      "type": "string"
    },
    "data": {
      "type": "array",
      "items": {
        "type": "object",
        "properties": {
          "id": {
            "type": "integer"
          },
          "name": {
            "type": "string"
          },
          "description": {
            "type": "string"
          },
          "categories": {
            "type": "array",
            "items": {
              "type": "object",
              "properties": {
                "id": {
                  "type": "integer"
                },
                "name": {
                  "type": "string"
                },
                "description": {
                  "type": "string"
                },
                "products": {
                  "type": "array",
                  "items": {
                    "type": "object",
                    "properties": {
                      "id": {
                        "type": "integer"
                      },
                      "categoryId": {
                        "type": "integer"
                      },
                      "name": {
                        "type": "string"
                      },
                      "needValidation": {
                        "type": "boolean"
                      },
                      "moduleId": {
                        "type": "integer"
                      },
                      "maxFixedTip": {
                        "type": "integer"
                      },
                      "description": {
                        "type": "string"
                      },
                      "amount": {
                        "type": "integer"
                      },
                      "sort": {
                        "type": "integer"
                      },
                      "meta": {
                        "type": "object"
                      },
                      "image": {
                        "type": "string"
                      },
                      "status": {
                        "type": "string"
                      }
                    },
                    "required": [
                      "id",
                      "categoryId",
                      "name",
                      "needValidation",
                      "moduleId",
                      "maxFixedTip",
                      "description",
                      "amount",
                      "sort",
                      "meta",
                      "image",
                      "status"
                    ]
                  }
                }
              },
              "required": [
                "id",
                "name",
                "description",
                "products"
              ]
            }
          },
          "internalName": {
            "type": "string"
          }
        },
        "required": [
          "id",
          "name",
          "description",
          "categories",
          "internalName"
        ]
      }
    }
  },
  "required": [
    "message",
    "messageCode",
    "data"
  ]
}

`product_search`

Search Product

Description

Allows searching for invoice agreements on the platform using specific terms. Send the request body with the necessary parameters in the format specified by the SearchBody object. The operation returns results that match the provided search terms.

Request Body

The request body should be in JSON format with the following parameter:
- query: The search term.

Response

The response will be a JSON object with the following properties:

message: A message related to the response.
messageCode: A code related to the message.
data: An array of objects containing product information with the following properties:
- id: The ID of the product.
- name: The name of the product.
- key: The key of the product.
- productId: The ID of the product.
- needsAmountInQuery: Boolean value that indicates wheter the invoice value should be include in the query.
- form: Array of objects that shows me the necessary references to consult the invoice. In case it arrives empty you must send a reference of preference.

Parámetros:

| Name | Type | Description | | --- | --- | --- | | query | string | Campo del body: query |

`product_query`

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.

It is important that when the request fails with the errorCode "product.errors.disabled" or similar indicating that the product is inactive, the agreements are consulted again using the search.

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.

Response Body Schema

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 | null | Campo del body: ownAgreementId | | data | object | Campo del body: data |

`query_claro_telefonia`

Product Query

Description

Allows performing a custom query on the platform. Send the request body 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:

productId (integer, required): Identifier of the product to perform the query.
queryType (string, required): The type of query to be performed.
ownAgreementId (string, optional): Identifier of the own agreement, if applicable.
data (object, required): Additional data for the query in object format.
- reference (string, required): The reference for the query data.

Response JSON Schema:

{
    "type": "object",
    "properties": {
        "message": {
            "type": "string"
        },
        "messageCode": {
            "type": "string"
        },
        "data": {
            "type": "object",
            "properties": {
                "payload": {
                    "type": "object",
                    "properties": {
                        "amount": {
                            "type": "integer"
                        },
                        "productId": {
                            "type": "integer"
                        },
                        "productName": {
                            "type": "string"
                        },
                        "reference": {
                            "type": "string"
                        },
                        "hashEchoData": {
                            "type": "string"
                        },
                        "hash": {
                            "type": "string"
                        },
                        "amountEditable": {
                            "type": "boolean"
                        }
                    }
                }
            }
        }
    }
}

Parámetros:

`query_acueducto_de_bogota`

HTTP POST /product/query

Description

Allows performing a custom query on the platform.

Request Body

raw (application/json)
- productId (number, required): Identifier of the product to perform the query.
- queryType (string. required): Additional data for the query in object format.
- ownAgreementId (number, optional): Identifier of the own agreement, if applicable
- data (object): Additional data for the query in object format.
  - reference (string): Reference data.

Response

The response will include the results of the query in case of success.

Response Schema

message (string): The message from the response.
messageCode (string): The code related to the message.
data (object)
- payload (object)
  - amount (number): The amount related to the query result.
  - productId (number): The ID of the product related to the query result.
  - productName (string): The name of the product related to the query result.
  - reference (string): The reference related to the query result.
  - hashEchoData (string): The echoed hash data.
  - hash (string): The hash data.
  - amountEditable (boolean): Indicates whether the amount is editable or not.
code (string): The code from the response.
errorCode (string): The error code from the response.
statusCode (number): The status code from the response.
timestamp (number): The timestamp of the response.

Parámetros:

`query_convenio_vendo`

Description

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.

Response Body Schema

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 |

`product_act_val_pro_state`

Description

Allows users to verify the activation status of a special product. The user making the request can determine the stage of their special product activation request. Below is a list of status codes along with their corresponding messages, indicating whether the request is pending review, approved, rejected, confirmed, managed by the affiliations area, or if the linking process for the product has already started. This information is useful for keeping the user informed about the progress of their request and for them to take necessary actions based on the current process status.

The following is a list of product status codes and their messages.

  | id | name       | message                                                                                               |
  |----|------------|-------------------------------------------------------------------------------------------------------|
  | P  | PENDING    | Your application is pending review

Published

Vulnerabilities

Links

Maintainers

Keywords

Readme

refacil-commerce MCP Server

🚀 Características

📋 Requisitos

📦 Instalación desde NPM

Configuración Rápida en IDEs

Cursor

Claude Desktop

Visual Studio Code

🛠️ Instalación para Desarrollo

🔧 Configuración

Variables de Entorno

🐳 Docker

☸️ Kubernetes

🔌 Uso del MCP

Endpoints Disponibles

🛠️ Herramientas Disponibles

admin_update_balance

Description

Request Body

Response

admin_locations_states

Description

Request Body

Response

admin_locations_cities

Description

Parameters Path

Response

auth_login_api

API Login

Description

Request Body

Response

commerce_register

Register Commerce

Description

Request Body

Response Body

commerce_get_info

Description

Request Body

Response

commerce_users

Description

Request Body

Response

commerce_updatebalance

Update Commerce Balance

Description

Request Body Schema

Response Body Schema

base_info_commerce_types

Retrieve Commerce Types

Description

Request Body

Response Body

report_details

Retrieve Commerce Report Details

Description

Request Body

Response Body

report_generate

Sales report

Description

Request Body

Response

generate_purchase_report

Purchase report

Description

Request Body

Response

generate_statement_report

Statement report

Description

`admin_update_balance`

`admin_locations_states`

`admin_locations_cities`

`auth_login_api`

`commerce_register`

`commerce_get_info`

`commerce_users`

`commerce_updatebalance`

`base_info_commerce_types`

`report_details`

`report_generate`

`generate_purchase_report`

`generate_statement_report`

`generate_payment_report`

`generate_transfer_report`

`generate_reverse_report`

`generate_consumption_report`

`payment_generate_resource`

`generate_resource_nequi`

`generate_resource_daviplata`

`generate_resource_bancolombia`