refacil-commerce-mcp

v1.0.10

Published

16 days ago

MCP Server para la API refacil-commerce

refacil-commerce MCP Server

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

🚀 Características

32 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

`auth_login_api`

API Login

Description

Allows API users to log in using their credentials. This operation authenticates the user with 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. The token must be sent in the Authorization header using the Bearer prefix. The response includes the token type (Bearer) and the access token.

Rate limiting

To prevent abuse and repeated attempts in a short period, this endpoint applies rate limiting:

Per IP: maximum 5 requests per minute from the same IP address.
Per user: maximum 5 requests every 5 minutes for the same user.
Combined user + IP: maximum 5 requests per minute for the same user–IP combination.

If these limits are exceeded, the API will temporarily reject additional calls, effectively asking the client to wait a moment before trying again.

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.

Error Codes

Only the first validation error is returned per request. Validation errors (400) come from the API layer; business errors (400) are returned by the authentication service.

| HTTP | errorCode | Message | Condition | | --- | --- | --- | --- | | 400 | validators.username.required | El campo username es obligatorio. | username is absent | | 400 | validators.username.isString | El campo username debe ser de tipo string | username is not a string | | 400 | validators.username.isNotEmpty | El campo username no puede estar vacío. | username is empty or whitespace-only | | 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) |

Parámetros:

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

`product_list`

Retrieve Product List

Description

Returns the catalog of products enabled for query and sale. Internally queries the products engine and filters internal categories (bills, packages). All products returned are available for use in subsequent query and sell operations.

Response

messageCode (string) - Response status code.
message (string) - Response message.
data (array)
- id (number) - Product or agreement identifier.
- categoryId (number) - Category the product belongs to.
- name (string) - Commercial name.
- needValidation (boolean) - Indicates if the product requires activation steps.
- moduleId (number) - Associated module in core.
- maxFixedTip (number) - Maximum fixed tip allowed.
- description (string) - Description visible to the commerce.
- amount (number) - Fixed amount, if applicable.
- sort (number) - Suggested sort order in catalogs.
- meta (object) - Additional metadata from the products engine.
- image (string) - URL of the product image.
- status (string) - Product status (enabled / disabled).

Error Codes

| HTTP | errorCode | Message | Condition | |------|-------------|---------|----------| | 500 | server.error | Mensaje del error interno or Critical internal server error occurred! | Database or service failure when retrieving products — retry; if it persists, notify support | | 404 | — | Not Found | Blocked route — verify the URL | | 401 | error.auth.failed | Error en la autenticación | Invalid or expired authentication token. Re-authenticate and retry the request. |

`product_packages`

Retrieve Available Packages

Description

Returns the list of configured packages (e.g., combos grouping several products). Useful for frontends that need to render hierarchies of categories → subcategories → products. Use this service to keep package data up to date.

Response

messageCode (string) - Response status code.
message (string) - Response message.
data (array)
- id (number) - Package or root category identifier.
- name (string) - Commercial name of the package.
- description (string) - Functional description.
- internalName (string) - Internal name used for filtering.
- categories (array) - List of subcategories.
  - id (number) - Subcategory identifier.
  - name (string) - Subcategory name.
  - description (string) - Subcategory description.
  - internalName (string) - Internal name of the subcategory.
  - products (array) - Associated products (same structure as /product/list).

Error Codes

| HTTP | errorCode | Message | Condition | |------|-------------|---------|----------| | 500 | server.error | Mensaje del error interno or Critical internal server error occurred! | Failure retrieving categories or products — retry; if it persists, notify support | | 404 | — | Not Found | Blocked route — verify the URL | | 401 | error.auth.failed | Error en la autenticación | Invalid or expired authentication token. Re-authenticate and retry the request. |

`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"}
        }
      }
    }
  }
}

Error Codes

| HTTP | errorCode | Message | Condition | |------|-------------|---------|----------| | 401 | error.auth.failed | Error en la autenticación | Invalid or expired authentication token. Re-authenticate and retry the request. | | 404 | — | Not Found | Blocked route — verify the URL | | 500 | server.error | Mensaje del error interno or Critical internal server error occurred! | Database or service failure when retrieving commissions — retry; if it persists, notify support |

`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"
  ]
}

Error Codes

| HTTP | errorCode | Message | Condition | |------|-------------|---------|----------| | 401 | error.auth.failed | Error en la autenticación | Invalid or expired authentication token. Re-authenticate and retry the request. | | 404 | — | Not Found | Blocked route — verify the URL | | 500 | server.error | Mensaje del error interno or Critical internal server error occurred! | Database or service failure when retrieving categories — retry; if it persists, notify support |

`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.

Error Codes

| HTTP | errorCode | Message | Condition | |------|-------------|---------|----------| | 400 | validators.query.required | El campo query es obligatorio. | query field is absent from the request body | | 400 | validators.query.isString | El campo query debe ser de tipo string | query is not a string | | 401 | error.auth.failed | Error en la autenticación | Invalid or expired authentication token. Re-authenticate and retry the request. | | 404 | — | Not Found | Blocked route — verify the URL | | 500 | server.error | Mensaje del error interno or Critical internal server error occurred! | Database or service failure when searching products — retry; if it persists, notify support |

Parámetros:

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

`product_query`

Query Product

Description

Performs the pre-sale query to obtain invoice data, reference, hash, and amount. Communicates with the Movement service. The returned hash and hashEchoData values must be forwarded in the subsequent sell request when paying bills. If the response contains only one of the two hash fields, the API automatically mirrors it to the other.

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 service.

Request Body

productId (number) required - Identifier of the product to query.
queryType (string) required - Type of query expected by Movement (e.g., BILLData). Min length: 1.
ownAgreementId (number) - Identifier of the own agreement, if applicable.
data (object) - Specific provider data (reference, cellphone, etc.). Technically optional, but required by most products at the business level.
- reference (string) - Invoice or reference number to query. Used for bill products.
- cellphone (string) - Destination phone number. Used for top-ups and packages.
- plate (string) - Vehicle plate. Used for SOAT products.

Response

messageCode (string) - Response status code.
message (string) - Response message.
data (object)
- amount (number) - Calculated amount for the sale.
- productId (number) - Identifier of the queried product.
- productName (string) - Product name.
- reference (string) - Reference to be forwarded in the sell request.
- hash (string) - Hash generated by Movement. Mirror of hashEchoData if absent.
- hashEchoData (string) - Mirror hash field. Mirror of hash if absent.
- amountEditable (boolean) - Indicates if the amount can be modified at sell time.

Error Codes

| HTTP | errorCode | Message | Condition | |------|-------------|---------|----------| | 400 | validators.productId.number | El campo productId debe ser de tipo Numerico | productId is absent or not numeric | | 400 | validators.queryType.required | El campo queryType es obligatorio. | queryType is absent | | 400 | validators.queryType.isString | El campo queryType debe ser de tipo string | queryType is not a string | | 400 | validators.queryType.isNotEmpty | El campo queryType no puede estar vacío. | queryType is empty or whitespace-only | | 400 | — | data must be an object | data is present but not an object | | 400 | — | ownAgreementId must be a number | ownAgreementId is present but not a number | | 404 | products.errors.notFound / product.not.found | Producto no encontrado | Product does not exist or is unavailable | | 404 | products.errors.disabled | Producto deshabilitado | Product is disabled — re-fetch agreements using the search service | | 404 | products.errors.providers.notFound | El producto no tiene un proveedor. | No provider associated with the product | | 400 | products.errors.metadata.invalid | Los metadatos del convenio no tienen un formato válido | Agreement metadata is invalid | | 400 | overdue.reference | Esta referencia ya se encuentra vencida. | Reference is overdue — do not retry with same reference | | 400 | closed.reference | Esta referencia ya se encuentra cerrada. | Reference is closed | | 401 | error.auth.failed | Error en la autenticación | Invalid or expired authentication token. Re-authenticate and retry the request. |

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`

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 | |-------|---------------| | productId | 1587 | | queryType | "BILLData" | | data.reference | "63440172" |

Parámetros:

`sells_sell`

Description

Allows performing a sale on the platform. Send the request body with the necessary parameters for the sale in the format specified by the SellBody object. This operation will return a response that includes information about the sale in case of success.

Note: To make this request in the case of selling invoices, we need the hash and hashEchoData provided by the query response for the reference.

Request Schema

productId: Number representing the product identifier (required)
amount: Number representing the amount of the payment (required)
sellType: String indicating the type of the sell operation (required)
hash: String containing the hash value for the operation (required)
data: Object containing additional data (required)
- reference: String containing the reference number for the payment (required)
- cellphone: String containing the cellphone number associated with the payment (required)
- hashEchoData: String containing the hash echo data for the operation (required)

Response Schema

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)
- date: Number representing the timestamp of the operation (required)
- sellId: Number representing the identifier of the sell operation (required)
- payload: Object containing the main response data (required)
  - preBalance: Number representing the balance before the operation (required)
  - posBalance: Number representing the balance after the operation (required)
  - tmpBalance: Number representing the temporary balance (required)
  - debt: Number representing the debt amount (required)
  - billData: Object containing bill-related data (required)
    - fields: Array of field objects (required)
      - name: String representing the field name (required)
      - type: String representing the field type (required)
      - options: Array of option objects (required)
        label: String representing the option label (required)
        value: String representing the option value (required)
      - label: String representing the field label (required)
      - placeholder: String representing the field placeholder (required)
      - required: Boolean indicating if the field is required (required)
    - costs: Array of cost objects (required)
      - label: String representing the cost label (required)
      - value: Number representing the cost value (required)
    - messages: Array of message objects (required)
      - value: String representing the message value (required)
    - stringInformation: Array of string information objects (required)
      - value: String representing the string information value (required)
    - footerInformation: Array of footer information objects (required)
    - share: Object containing share information (required)
      - cellphone: String representing the cellphone number (required)
      - 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 | | --- | --- | --- | | amount | number | Campo del body: amount | | productId | number | Campo del body: productId | | hash | string | Campo del body: hash | | sellType | string | Campo del body: sellType | | data | object | Campo del body: data |

`query_axa`

Here you will find all the endpoints related to the sale of SOAT AXA COLPATRIA.

Note: This product includes an administrative cost for each sale made. For more information, please contact your commercial agent.

For AXA service testing: It is required to indicate in the documentation that a test environment must be requested from the commercial agent at least 15 days in advance.

Timeout Configuration

The following timeout values are configured for AXA provider operations:

| Operation | Min (seconds) | Max (seconds) | Timeout (seconds) | | --- | --- | --- | --- | | AXA | 0 | 15 | 50 |

Important: These timeout values should be considered when implementing integrations with AXA COLPATRIA services to ensure proper error handling and user experience.

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.

Below is an example of a request for vehicle SOAT insurance. The following necessary data must be provided: productId (in this case, 91), queryType (in this case SOATData), type of document, document number, vehicle plate, and phone number.

Note:

It is important to remember that in the response of this product, several of its data points are crucial as they must be sent in the service that performs the sale (/sells/sell). The necessary data are as follows: amount, cifrateAmount, and hashEchoData.

Below are the valid document types for the consultation process:

CC: Cédula de ciudadanía
CE: Cédula de extranjería
NIT: Número de identificación tributaria
PS: Pasaporte
RC: Registro civil
TI: Tarjeta de identidad
CD: Carné diplomático

Payload for Custom Query

The following payload is required for performing a custom query:

queryType: (string, required) Specifies the type of query to be performed.
productId: (number, required) Identifies the product for which the query is being made.
docType: (string, required) Specifies the type of document being used for identification.
document: (string, required) The document number for identification purposes.
cellphone: (string, required) The phone number associated with the 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 | | --- | --- | --- | | queryType | string | Campo del body: queryType | | productId | number | Campo del body: productId | | docType | string | Campo del body: docType | | document | string | Campo del body: document | | cellphone | string | Campo del body: cellphone | | license | string | Campo del body: license |

`sell_axa`

Here you will find all the endpoints related to the sale of SOAT AXA COLPATRIA.

Note: This product includes an administrative cost for each sale made. For more information, please contact your commercial agent.

For AXA service testing: It is required to indicate in the documentation that a test environment must be requested from the commercial agent at least 15 days in advance.

Timeout Configuration

The following timeout values are configured for AXA provider operations:

| Operation | Min (seconds) | Max (seconds) | Timeout (seconds) | | --- | --- | --- | --- | | AXA | 0 | 15 | 50 |

Important: These timeout values should be considered when implementing integrations with AXA COLPATRIA services to ensure proper error handling and user experience.

Allows performing a sale on the platform. Send the request body with the necessary parameters for the sale in the format specified by the SellBody object. This operation will return a response that includes information about the sale in case of success.

Example of a payment request for the AXA Colpatria product. The necessary information is provided, such as the productId (in this case, 91) and other relevant data, all attributes are mandatory.

Note:
In order to sell this product, it is important to bear in mind that it is part of a special product. Therefore, before being able to use it, it is necessary to complete the entire product activation process. This can be achieved by using the following services: /product/activation/....
It is important to remember that to perform a sale using this service, several crucial data points must be sent. Some of these data points are obtained from the /products/query service. The necessary data are as follows: amount, cifrateAmount, and hashEchoData.

Payload for Custom Sell

The following payload is required for performing a custom sell:

productId: (number, required) Identifies the product for which the sale is being made.
data: (object, required) Contains specific sale data.
- terminal:
  - id: A unique identifier for the merchant (POS) that is generating the SOAT sale transaction for the API client. If there is no merchant under the API client's network, the same merchant ID assigned by Refacil should be sent in the id field.
- amount: (object, required) Details about the sale amount.
  - amount: (number, required) Total amount of the sale.
  - runt: (number) Value for RUNT.
  - prima: (number) Prima value.
  - contributions: (number) Contributions.
  - valueDiscountLaw: (number) Value of law discount.
  - valueDiscountTotal: (number) Total discount value.
  - valuePayDiscount: (number) Amount to pay with discount.
  - amountAdministrative: (number) Administrative amount.
  - amountTotal: (number) Total amount.
  - dateStart: (string) Start date.
  - dateEnd: (string) End date.
  - discount: (number) Discount.
- license: (string) Vehicle license plate.
- hashEchoData: (string) Hash data.
- cifrateAmount: (object) Encrypted amount.
  - hash: (string) Hash.
  - hashEchoData: (string) Hash data.
- userDetail: (object, required) User details.
  - cellphone: (string, required) User's cellphone number.
  - email: (string) User's email.
  - document: (string, required) User's document number.
  - docType: (string, required) Type of user's document.
amount: (number, required) Total amount of the sale.
moveTmpBalance: (boolean) Indicates whether to move temporary balance.

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 | "[email protected]" | | data.userDetail.document | "860002964" | | data.userDetail.docType | "NIT" |

Parámetros:

| Name | Type | Description | | --- | --- | --- | | productId | number | Campo del body: productId | | data | object | Campo del body: data | | amount | number | Campo del body: amount |

`query_quote`

Here you will find all the endpoints related to the sale of SOAT PREVISORA.

Timeout Configuration

The following timeout values are configured for PREVISORA provider operations:

| Provider | Min (seconds) | Max (seconds) | Timeout (seconds) | | --- | --- | --- | --- | | PREVISORA | 0 | 300 | 300 |

Important:

Based on the current operation of the insurance company PREVISORA, the waiting time (timeout) for sales processing has been adjusted to 5 minutes (300 seconds). This change addresses the need to ensure that all transactions are processed correctly, even in scenarios where delays may occur.

In addition, the API guarantees up to 2 automatic retries in case a timeout occurs during processing. Although this behavior is not common in the API solution, it has been implemented to ensure the continuity and success of sales operations.

It is recommended to take this configuration into account when implementing integrations with PREVISORA services, in order to ensure proper error handling and an optimal user experience.

Test Environment

Available Test Scenarios

To test error scenarios and different response types, the following vehicle license plates are available:

Error Handling

| Method | Plate | Scenario | Description | | --- | --- | --- | --- | | All | TIM001 | Timeout | Simulates timeout scenario | | All | ERR400 | System Error | Ocurrió un error inesperado. Consulte con el Administrador del sistema | | All | ERR401 | Authentication Error | No ha sido posible autenticarse, el token es incorrecto o el usuario no se encuentra activo |

Quote Operations

| Method | Plate | Scenario | Description | | --- | --- | --- | --- | | Quote | ABC123 | Success Standard | Success: Vehículo, camioneta, bus | | Quote | ABC124 | Success with Discount | Standard vehicle with discount applied | | Quote | ABC125 | Electric Vehicle | Electric car pricing | | Quote | ABC126 | Law Discount | Legal discount application | | Quote | ABC127 | Transit Authority Error | La placa no está asociada a algún organismo de tránsito |

Issue Operations

| Method | Plate | Scenario | Description | | --- | --- | --- | --- | | Issue | ABC123 | Success Standard | Success: Vehículo, camioneta, bus | | Issue | ABC124 | Success with Discount | Successfully issued with discount |

Consult Operations

| Method | Plate | Scenario | Description | | --- | --- | --- | --- | | Consult | ABC123 | Issued | Policy has been issued | | Consult | ABC124 | Not Issued | Policy has not been issued |

Usage Notes

Test Plates: Use the provided test plates to simulate different scenarios during development and testing
Error Simulation: TIM001 and ERR-prefixed plates are specifically designed to test error handling
Success Flows: ABC123 generally represents successful operations across different methods
Edge Cases: ABC124-ABC127 cover various business scenarios including discounts and restrictions
There is a complementary file containing additional test scenarios not listed in this documentation. You can access it here: ⁠Additional Test Scenarios Folder

The following is an example of a SOAT insurance request for a vehicle. The following required data must be provided: productId (in this case, 1014006), queryType (in this case SOATFullData), document number and vehicle registration number.

Note:

Payload for Custom Query

The following payload is required for performing a custom query:

productId: (number, required) Identifies the product for which the query is being made.
documentType: (number, required) Specifies the type of document. Allowed values:
- 1: CEDULA DE CIUDADANIA
- 2: CEDULA DE EXTRANJERIA
- 3: NIT
- 4: TARJETA DE IDENTIDAD
document: (string, required) The document number for identification purposes.
Length validation rules based on documentType:
- For documentType = 1 (CEDULA DE CIUDADANIA):
  - Minimum length: 7 numeric characters
  - Maximum length: 10 numeric characters
- For documentType = 2 (CEDULA DE EXTRANJERIA):
  - Minimum length: 5 characters (alphanumeric allowed)
  - Maximum length: 15 characters (alphanumeric allowed)
- For documentType = 3 (NIT):
  - Minimum length: 6 numeric characters (includes verification digit – VD)
  - Maximum length: 11 numeric characters (includes VD)
  - Must be sent without hyphen (-) and must include the verification digit.
  Additional rules based on length:
  - If length is 11, must start with "1" → (new CC + VD)
  - If length is 10, must start with "8" or "9" → (NIT + VD)
  - If length is 9 or less, can start with any digit → (old CC + VD)
  💡 VD (Verification Digit): A verification digit is a number mathematically calculated by DIAN (Dirección de Impuestos y Aduanas Nacionales) to validate that the NIT was entered correctly. It is included as part of the document number.
- For documentType = 4 (TARJETA DE IDENTIDAD):
  - Minimum length: 10 numeric characters
  - Maximum length: 11 numeric characters
queryType: (string, required) Specifies the type of query to be performed.
license: (string, required) The license plate of the vehicle.

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 | |-------|---------------| | productId | 1014006 | | documentType | 1 | | document | "1032363500" | | queryType | "SOATFullData" | | license | "XAZ975" |

Parámetros:

| Name | Type | Description | | --- | --- | --- | | productId | number | Campo del body: productId | | documentType | number | Campo del body: documentType | | document | string | Campo del body: document | | queryType | string | Campo del body: queryType | | license | string | Campo del body: license |

`query_consult`

Here you will find all the endpoints related to the sale of SOAT PREVISORA.

Timeout Configuration

The following timeout values are configured for PREVISORA provider operations:

| Provider | Min (seconds) | Max (seconds) | Timeout (seconds) | | --- | --- | --- | --- | | PREVISORA | 0 | 300 | 300 |

Important:

It is recommended to take this configuration into account when implementing integrations with PREVISORA services, in order to ensure proper error handling and an optimal user experience.

Test Environment

Available Test Scenarios

To test error scenarios and different response types, the following vehicle license plates are available:

Error Handling

Quote Operations

Issue Operations

Consult Operations

| Method | Plate | Scenario | Description | | --- | --- | --- | --- | | Consult | ABC123 | Issued | Policy has been issued | | Consult | ABC124 | Not Issued | Policy has not been issued |

Usage Notes

Test Plates: Use the provided test plates to simulate different scenarios during development and testing
Error Simulation: TIM001 and ERR-prefixed plates are specifically designed to test error handling
Success Flows: ABC123 generally represents successful operations across different methods
Edge Cases: ABC124-ABC127 cover various business scenarios including discounts and restrictions
There is a complementary file containing additional test scenarios not listed in this documentation. You can access it here: ⁠Additional Test Scenarios Folder

Returns the information of the last policy issued for the license plate. If the policy is queried on days after its issuance, the service will not return the requested information. It is important to clarify that this endpoint does not retrieve failed sales in the system.

Payload for Consult Query

The following payload is required for performing a custom query:

productId: (number, required) Identifies the product for which the query is being made.
queryType: (string, required) Specifies the type of query to be performed, in this case have to be `SOATPolicy`.
license: (string, required) The license plate of the vehicle.

Test Data

Use the following example values to test this endpoint in the QA environment:

| Field | Example Value | |-------|---------------| | productId | 1014006 | | queryType | "SOATPolicy" | | license | "XAZ975" |

Parámetros:

| Name | Type | Description | | --- | --- | --- | | productId | number | Campo del body: productId | | queryType | string | Campo del body: queryType | | license | string | Campo del body: license |

`sell_previsora`

Here you will find all the endpoints related to the sale of SOAT PREVISORA.

Timeout Configuration

The following timeout values are configured for PREVISORA provider operations:

| Provider | Min (seconds) | Max (seconds) | Timeout (seconds) | | --- | --- | --- | --- | | PREVISORA | 0 | 300 | 300 |

Important:

It is recommended to take this configuration into account when implementing integrations with PREVISORA services, in order to ensure proper error handling and an optimal user experience.

Test Environment

Available Test Scenarios

To test error scenarios and different response types, the following vehicle license plates are available:

Error Handling

Quote Operations

Issue Operations

Consult Operations

| Method | Plate | Scenario | Description | | --- | --- | --- | --- | | Consult | ABC123 | Issued | Policy has been issued | | Consult | ABC124 | Not Issued | Policy has not been issued |

Usage Notes

Test Plates: Use the provided test plates to simulate different scenarios during development and testing
Error Simulation: TIM001 and ERR-prefixed plates are specifically designed to test error handling
Success Flows: ABC123 generally represents successful operations across different methods
Edge Cases: ABC124-ABC127 cover various business scenarios including discounts and restrictions
There is a complementary file containing additional test scenarios not listed in this documentation. You can access it here: ⁠Additional Test Scenarios Folder

Product restrictions

Allows selling SOAT in the name of a person who is not the owner of the vehicle.
SOAT can be sold for a PRIVATE CAR.
SOAT can be sold for a PRIVATE MOTORCYCLE.
SOAT can be sold for a PUBLIC SERVICE VEHICLE.
SOAT cannot be sold to vehicles with 0 KM.
Sales hours are from 12:30 AM to 11:30 PM.
SOAT can be sold up to 30 days before its expiration.
The definition of the Administrative Cost and Commission for the sale of SOAT can be validated with your Refacil Commercial Advisor.
The insurance companies are directly responsible for sending the issued SOAT via email. The API provides a URL from the provider for downloading the SOAT.

Example of a payment request for the Previsora product. The necessary information is provided, such as the productId (in this case, 1014006) and other relevant data, all attributes are mandatory.

Note:

It is important to remember that to perform a sale using this service, several crucial data points must be sent. Some of these data points are obtained from the /products/query Quote Service. The necessary data are as follows: amount, vehDetail, and userDetail.

Some data obtained from the /products/query service may be null; however, this data is mandatory for the sale process and must be filled in.

In addition to the userDetail object, three additional attributes must be sent: gender, RegimenTypeId, and RutId.

The possible values for each of the aforementioned attributes are as follows:

gender:
- M = Male
- F = Female
RegimenTypeId:
- 1 = Responsible for IVA
- 2 = Not responsible for IVA
RutId:
- 1 = Large taxpayer
- 2 = Self-withholding agent
- 3 = IVA withholding agent
- 4 = Simple taxation regime
- 5 = Not applicable
- 6 = Large taxpayer-Self-withholding agent-IVA withholding agent
- 7 = Self-withholding agent-IVA withholding agent
- 8 = Large taxpayer-IVA withholding agent
cityCode: DANE code
stateCode: This field is populated based on the state sheet here.
To check the values for the other parameters, please refer here.

Field Validations

Name and Last Name Format Requirements

The validation rules for the name and lastName fields in the userDetail object depend on the person type:

For Natural Persons (Personas Naturales):

Must contain only letters (uppercase and lowercase)
Allows letters with accents: á, é, í, ó, ú, Á, É, Í, Ó, Ú
Allows Spanish special characters: ñ, Ñ, ü, Ü
Allows spaces between words (for compound names)
Minimum length of 3 characters
Does not allow numbers
Does not allow special characters such as @, #

For Legal Entities (Personas Jurídicas):

Allows alphanumeric characters (letters and numbers)
Allows letters with accents: á, é, í, ó, ú, Á, É, Í, Ó, Ú
Allows Spanish special characters: ñ, Ñ, ü, Ü
Allows spaces between words
Minimum length of 3 characters
Does not allow special characters such as @, #

Email Format Requirements

The email field must comply with strict validation rules to prevent errors during the issuance process:

Allows only single separators: . (period), _ (underscore), - (hyphen)
Cannot have consecutive separators (e.g., .. or --)
Cannot start or end with separators
Domain must have at least 2 characters in the top-level domain (TLD)
Must not contain spaces or the @ symbol except as the domain separator

Valid examples:

Invalid examples:

[email protected] (separator at the end before @)
[email protected] (consecutive separators)
@domain.com (missing local part)
usuarioá@gmail.com (contains accented characters)
campoherná[email protected] (contains special characters with encoding issues)
[email protected] (multiple consecutive hyphens)

Address Format Requirements

The address field must comply with the following validation rules:

Validation Rules

Cannot start with numeric characters - The first character after trimming cannot be a digit (0-9)
First character must be:
- A letter (uppercase or lowercase): A-Z, a-z
- A vowel with Spanish acute accent: á, é, í, ó, ú, Á, É, Í, Ó, Ú
- The letter ñ/Ñ
- The letter ü/Ü (with diaeresis)
- A whitespace character (space, tab, etc.) — though after trim(), this is effectively not possible at the start
Subsequent characters (position 2 onwards) can be:
- All characters allowed for the first position, plus:
- Digits: 0-9
- Special address characters: #, -, ., ,

Allowed Characters Summary

| Category | Characters | | --- | --- | | Letters (no accent) | A-Z, a-z | | Accented vowels | á, é, í, ó, ú, Á, É, Í, Ó, Ú | | Special Spanish letters | ñ, Ñ, ü, Ü | | Digits (not at start) | 0-9 | | Whitespace | Space, tab, etc. | | Address symbols | #, -, ., , |

NOT Allowed Characters

| Category | Examples | | --- | --- | | Other punctuation | ; : ! ? ¡ ¿ " ' ( ) [ ] { } | | Mathematical/monetary | + * / % = < > ^ ~ € $ @ & | | Underscore and separators | _ | \ | | Other accented letters | ç, ã, õ, ô, ä, ö, ê, â, î, û | | Non-Latin alphabets | Cyrillic, Greek, Arabic, Chinese, etc. | | Emojis | 🙂 😁 🏠 |

Valid Examples

Calle 123 #45-67
Carrera 7 Bis #8-24
Avenida Principal, Casa 5
Avenida Pérez Galdós
Av. Simón Bolívar 123
Cl 10 Sur #45-20
Urbanización La Ñora, Bloque 3

Invalid Examples

| Address | Reason | | --- | --- | | 123 Calle Principal | Starts with a number | | Calle @Principal | Contains @ (not allowed) | | Dirección <> | Contains angle brackets | | Calle_45 #12-34 | Contains underscore _ | | Calle 5 #12-34! | Contains exclamation mark ! | | Rua São Paulo 10 | Contains ã (not in allowed accents) | | Avenida (Frente al parque) | Contains parentheses () |

Payload for Custom Sell

The following payload is required for performing a custom sell:

Note: According to the provider's official documentation, the name and lastName fields are mandatory.

productId: (number, required) Identifies the product for which the sale is being made.
data: (object, required) Contains specific sale data.
- license: (string, required) License plate of the vehicle.
- productId: (string, required) Product identification (empty in this example).
- cellphone: (string, required) User's cellphone number.
- document: (string, required) User's document number. For NIT, this field must include the verification digit and must be sent without hyphen (-).
- terminal:
  - id: A unique identifier for the merchant (POS) that is generating the SOAT sale transaction for the API client. If there is no merchant under the API client's network, the same merchant ID assigned by Refacil should be sent in the id field.
- amount: (object, required) Details about the sale amount.
  - TariffCode: (string, required) Tariff code.
  - InsurancePremium: (number, required) Insurance premium.
  - InsuranceTax: (number, required) Insurance tax.
  - InsuranceFine: (number, required) Insurance fine.
  - Total: (number, required) Total.
  - TotalWithDiscountAmount: (number, required) Total with discount amount.
  - DiscountAmount: (number, required) Discount amount.
  - ElectricDiscount: (numbe, requiredr) Electric discount.
  - PercentageElectricDiscount: (number, required) Percentage electric discount.
  - InsurancePremiumFormatted: (string, required) Formatted insurance premium.
  - InsuranceTaxFormatted: (string, required) Formatted insurance tax.
  - InsuranceFineFormatted: (string, required) Formatted insurance fine.
  - TotalFormatted: (string, required) Formatted total.
  - DiscountAmountFormatted: (string, required) Formatted discount amount.
  - TotalWithDiscountAmountFormatted: (string, required) Formatted total with discount amount.
  - createdAt: (string, required) Creation date.
  - dateStart: (string, required) Start date.
  - dateEnd: (string, required) End date.
  - amount: (number, required) Amount.
  - amountDiscount: (number, required) Discount amount.
  - amountOthers: (number, r

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

auth_login_api

API Login

Description

Rate limiting

Request Body

Response

Error Codes

product_list

Retrieve Product List

Description

Response

Error Codes

product_packages

Retrieve Available Packages

Description

Response

Error Codes

product_commissions

Retrieve Product Commissions

Description

Response

Error Codes

product_categories

Retrieve Product Categories

Description

Response

Error Codes

product_search

Search Product

Description

Request Body

Response

Error Codes

product_query

Query Product

Description

Request Body

Response

Error Codes

query_claro_telefonia

Product Query

Description

query_acueducto_de_bogota

HTTP POST /product/query

Description

Request Body

Response

Response Schema

query

Test Data

sells_sell

Description

Request Schema

Response Schema

Test Data

query_axa

Timeout Configuration

Payload for Custom Query

`auth_login_api`

`product_list`

`product_packages`

`product_commissions`

`product_categories`

`product_search`

`product_query`

`query_claro_telefonia`

`query_acueducto_de_bogota`

`query`

`sells_sell`

`query_axa`

`sell_axa`

`query_quote`

`query_consult`

`sell_previsora`