Agent API y herramientas MCP. Elige un SDK o integra con cURL; todos los ejemplos usan la misma autenticación HMAC.
Agentes
Para automatización y asistentes (Cursor), crea un token de agente en el panel /merchant/agentes con scopes granulares. Las rutas Agent API usan Authorization: Bearer hanix_agt_live_… bajo el prefijo /api/v1/agent/business/ (espejo de Business API).
Requiere cualquier token de agente válido. La respuesta incluye solo las tools cuyo scope está en el token.
{
"jsonrpc": "2.0",
"id": 1,
"method": "tools/list",
"params": {}
}curl -sS -X POST 'https://api.hanix.io/api/v1/mcp' \
-H 'Authorization: Bearer hanix_agt_live_…' \
-H 'Content-Type: application/json' \
-d '{"jsonrpc":"2.0","id":1,"method":"tools/list","params":{}}'Cada tool documenta permiso, sensibilidad, parámetros requeridos y ejemplo de respuesta en su descripción MCP.
hanix_create_payment_order · scope business.payment_orders.create
{
"jsonrpc": "2.0",
"id": 2,
"method": "tools/call",
"params": {
"name": "hanix_create_payment_order",
"arguments": {
"body": {
"merchant_reference": "orden-mcp-001",
"amount_in_cents": 50000,
"currency_id": "uuid-moneda",
"country_id": "uuid-pais",
"customer_email": "cliente@email.com",
"success_url": "https://tu-tienda.com/ok",
"cancel_url": "https://tu-tienda.com/cancel"
}
}
}
}hanix_create_payment_order (con items[] de catálogo)
{
"jsonrpc": "2.0",
"id": 3,
"method": "tools/call",
"params": {
"name": "hanix_create_payment_order",
"arguments": {
"body": {
"merchant_reference": "orden-catalogo-mcp",
"country_id": "uuid-pais",
"items": [
{
"variant_id": "uuid-variante",
"quantity": 2
}
],
"success_url": "https://tu-tienda.com/ok",
"cancel_url": "https://tu-tienda.com/cancel"
}
}
}
}hanix_quote_business_cart · scope business.cart.quote
{
"jsonrpc": "2.0",
"id": 4,
"method": "tools/call",
"params": {
"name": "hanix_quote_business_cart",
"arguments": {
"body": {
"items": [
{
"variant_id": "uuid-variante",
"quantity": 1
}
],
"country_id": "uuid-pais"
}
}
}
}hanix_list_payment_orders · scope business.payment_orders.read
{
"jsonrpc": "2.0",
"id": 5,
"method": "tools/call",
"params": {
"name": "hanix_list_payment_orders",
"arguments": {
"query": {
"page": 1,
"limit": 20,
"status": "pending"
}
}
}
}hanix_get_payment_order · pathParams.id
{
"jsonrpc": "2.0",
"id": 6,
"method": "tools/call",
"params": {
"name": "hanix_get_payment_order",
"arguments": {
"pathParams": {
"id": "uuid-orden-pago"
}
}
}
}*.read| Tool MCP | Scope requerido | HTTP | Sensibilidad | SDK |
|---|---|---|---|---|
hanix_list_catalog_categoriesLista categorías del catálogo. | business.merchant_catalog.categories.read | GET /agent/business/merchant-catalog/categories | low | listCatalogCategories |
hanix_upsert_catalog_categoriesCrea o actualiza categorías en lote. | business.merchant_catalog.categories.write | PUT /agent/business/merchant-catalog/categories/bulk | medium | upsertCatalogCategories |
hanix_delete_catalog_categoriesElimina categorías en lote. | business.merchant_catalog.categories.write | DELETE /agent/business/merchant-catalog/categories/bulk | high | deleteCatalogCategories |
hanix_request_category_image_uploadsSolicita URLs de subida de imagen de categoría. | business.merchant_catalog.images.write | POST /agent/business/merchant-catalog/categories/images/direct-uploads | medium | requestCatalogCategoryImageDirectUploads |
hanix_register_category_imagesRegistra imágenes de categoría. | business.merchant_catalog.images.write | PUT /agent/business/merchant-catalog/categories/images/bulk | medium | registerCatalogCategoryImages |
hanix_delete_category_imagesElimina imágenes de categorías. | business.merchant_catalog.images.write | DELETE /agent/business/merchant-catalog/categories/images/bulk | high | deleteCatalogCategoryImages |
| Tool MCP | Scope requerido | HTTP | Sensibilidad | SDK |
|---|---|---|---|---|
hanix_list_catalog_currenciesLista monedas disponibles para productos. | business.merchant_catalog.products.read | GET /agent/business/merchant-catalog/currencies | low | listCatalogCurrencies |
hanix_create_catalog_productCrea un producto en el catálogo. | business.merchant_catalog.products.write | POST /agent/business/merchant-catalog/products | medium | createCatalogProduct |
hanix_list_catalog_productsLista productos del comerciante, incluidos borrador y archivado. Con q, si el texto no coincide, agrega parecidos por significado (match_type=similar) y su estado. | business.merchant_catalog.products.read | GET /agent/business/merchant-catalog/products | low | listCatalogProducts |
hanix_get_catalog_productObtiene un producto por id. Devuelve la foto de portada y image_count. query.include_images=true trae la galería completa. | business.merchant_catalog.products.read | GET /agent/business/merchant-catalog/products/:productId | low | getCatalogProduct |
hanix_update_catalog_productActualiza un producto. | business.merchant_catalog.products.write | PATCH /agent/business/merchant-catalog/products/:productId | medium | updateCatalogProduct |
hanix_delete_catalog_productsElimina productos en lote. | business.merchant_catalog.products.write | DELETE /agent/business/merchant-catalog/products/bulk | high | deleteCatalogProducts |
hanix_update_catalog_product_variantActualiza una variante. Antes localiza el producto con hanix_search_business_catalog_products y lee la variante con hanix_get_catalog_product. El precio nuevo sale de la fila leída, no de un recuerdo. | business.merchant_catalog.variants.write | PATCH /agent/business/merchant-catalog/products/:productId/variants/:variantId | medium | updateCatalogProductVariant |
hanix_set_variant_warehouse_stockEstablece stock en almacén de una variante. | business.merchant_catalog.inventory.write | PATCH /agent/business/merchant-catalog/products/:productId/variants/:variantId/warehouse-stock | high | setCatalogVariantWarehouseStock |
hanix_upsert_catalog_variantsCrea o actualiza variantes en lote. body.locale=en guarda name en traducción sin pisar el ES canónico. | business.merchant_catalog.variants.write | PUT /agent/business/merchant-catalog/variants/bulk | medium | upsertCatalogVariants |
hanix_delete_catalog_variantsElimina variantes en lote. | business.merchant_catalog.variants.write | DELETE /agent/business/merchant-catalog/variants/bulk | high | deleteCatalogVariants |
hanix_request_product_image_uploadsSolicita URLs de subida de imagen de producto. | business.merchant_catalog.images.write | POST /agent/business/merchant-catalog/images/direct-uploads | medium | requestCatalogImageDirectUploads |
hanix_register_product_imagesRegistra imágenes de producto. | business.merchant_catalog.images.write | PUT /agent/business/merchant-catalog/images/bulk | medium | registerCatalogImages |
hanix_update_product_imagesActualiza imágenes de producto (isPrimary = imagen de tarjeta en listados, variantId, altText, sortOrder). | business.merchant_catalog.images.write | PATCH /agent/business/merchant-catalog/images/bulk | medium | updateCatalogImages |
hanix_delete_product_imagesElimina imágenes de producto. | business.merchant_catalog.images.write | DELETE /agent/business/merchant-catalog/images/bulk | high | deleteCatalogImages |
hanix_adjust_catalog_inventoryAjusta inventario en lote. Arma adjustments desde hanix_list_catalog_restock (variantId y physicalStoreId de esa fila) y pide confirmación humana antes de escribir. | business.merchant_catalog.inventory.write | POST /agent/business/merchant-catalog/inventory/adjustments/bulk | high | adjustCatalogInventory |
hanix_list_catalog_restockLectura: unidades vendidas en 7 días por variante y sede, con stock actual. No escribe. Confirma antes de hanix_adjust_catalog_inventory. | business.merchant_catalog.products.read | GET /agent/business/merchant-catalog/inventory/restock | low | listCatalogRestock |
| Tool MCP | Scope requerido | HTTP | Sensibilidad | SDK |
|---|---|---|---|---|
hanix_search_business_catalog_productsBusca productos públicos por texto. Si no hay match literal, el primer ítem es el parecido de mayor similitud (match_type=similar). Ábrelo y responde con sus datos. | business.catalog.read | GET /agent/business/catalog/products/search | low | searchBusinessCatalogProducts |
hanix_get_business_catalog_product_search_facetsFacetas de búsqueda de productos públicos. | business.catalog.read | GET /agent/business/catalog/products/search/facets | low | getBusinessCatalogProductSearchFacets |
hanix_suggest_business_catalog_productsSugerencias de producto. Si el autocompletado no alcanza, incluye parecidos por significado con match_type=similar. | business.catalog.read | GET /agent/business/catalog/products/search/suggest | low | suggestBusinessCatalogProducts |
hanix_get_business_catalog_product_by_slugDetalle de producto público por slug. | business.catalog.read | GET /agent/business/catalog/products/by-slug/:slug | low | getBusinessCatalogProductBySlug |
hanix_resolve_business_catalog_variantResuelve una combinación de opciones a la variante vendible exacta (o indica opciones faltantes). | business.catalog.read | POST /agent/business/catalog/variants/resolve | low | resolveBusinessCatalogVariant |
hanix_list_business_catalog_categoriesListado público de categorías del catálogo storefront. | business.catalog.read | GET /agent/business/catalog/categories | low | listBusinessCatalogCategories |