Herramientas para agentes

Usa Markdown para explicar la tarea y OpenAPI para definir la llamada. Ninguno de los dos reemplaza la validación del servidor.

Fuentes disponibles

llms.txt enumera las APIs y guías públicas.
llms-full.txt reúne la documentación pública en un archivo.
El menú de una página permite copiar o abrir su Markdown.

Chopper es el asistente de IA de Ecomiq. El chat del Admin usa el servicio ecomiq-ai, que ejecuta el modelo, consulta herramientas autorizadas y conserva la conversación. Sus rutas viven bajo /v1/assistant; no es una interfaz MCP.

Las capacidades dependen del modo, los permisos y los servicios configurados. El chat comercial puede consultar productos y sus variantes, recomendaciones, historial de precios, pedidos completos, despachos, reclamos, clientes, carritos, inventario, publicaciones, webhooks, impuestos y ajustes. Las búsquedas devuelven los identificadores que se usan para abrir detalles. La documentación no concede permisos ni convierte una operación del Admin en una herramienta del chat.

Para contar productos de un proveedor como VTEX, Chopper consulta las fuentes por providerId y envía sus IDs juntos en sourceIds a catalog_count_products. El resultado cuenta productos únicos vinculados a esas fuentes; no deduce el origen por marcas o imágenes ni cuenta filas de sincronización como productos.

En el editor de la tienda, las herramientas habilitadas pueden preparar cambios del borrador, generar imágenes de campaña y, con el workbench configurado, inspeccionar URLs de referencia y diseños candidatos. Inspeccionar una referencia no equivale a disponer de búsqueda web general. Una propuesta no publica la tienda.

Edición de productos desde el chat

Con permisos de lectura y edición de catálogo, Chopper puede preparar cambios en productos existentes y en variantes concretas: textos, etiquetas, estado, SKU y precios. También puede seleccionar y ordenar imágenes ya adjuntas o cambiar la principal. La tarjeta presenta Antes y Después; Aprobar y guardar aplica la edición en .NET. Las variantes omitidas se conservan.

catalog_product_edit_propose crea la propuesta y catalog_product_edit_get consulta su estado. Ninguna herramienta del modelo aprueba. El servidor revalida actor, tienda, vendedor, permisos y versiones; conserva idempotencia y auditoría. Si el producto cambió, hace falta una propuesta nueva. Si una parte falla, se revierte la edición completa. Este flujo no ajusta stock ni crea o borra variantes.

Imágenes de producto

El formulario de producto incluye una acción para generar una imagen. La persona revisa el resultado y lo aplica al formulario. La generación consume créditos; aplicar la imagen la guarda como archivo y la agrega a las imágenes del producto. Solo se marca principal automáticamente cuando el producto no tenía imágenes. Para reemplazar una principal existente, selecciona la nueva imagen como principal y guarda el producto.

Generar una imagen, subirla, asignarla y guardar el producto son pasos diferentes. Actualmente el chat no tiene una herramienta que complete ese flujo de principio a fin. La herramienta de campañas del editor tampoco cambia la imagen principal. Si el proveedor de imágenes no está configurado, el servicio no puede generar.

Las imágenes generadas pueden utilizarse en el catálogo. Deben representar con fidelidad el artículo; una ilustración generada no demuestra por sí misma cómo es el producto real. Esta distinción no es una prohibición de generación.

API MCP para agentes externos

El MCP público pertenece a Api.Agent, un servicio .NET independiente del chat. El cliente se conecta al endpoint /mcp del despliegue de Agent configurado para su entorno. ecomiq-ai no expone ese endpoint ni actúa como proxy.

El cliente usa OAuth con scope api_agent y audience igual a la URL MCP canónica (https://chopper.ecomiq.pe/mcp en producción). No debe reenviar un bearer api_admin. Agent valida la instalación, el usuario, tenant, tienda, seller y permisos; el prompt no puede cambiar ese alcance. Usa la metadata OAuth del servicio y el catálogo vivo de tools/list.

El catálogo público ofrece:

Herramienta	Resultado
`organization_current_store_get`	Lee la tienda de la instalación OAuth validada.
`catalog_products_list`	Lista o busca productos por nombre, descripción, SKU o código de barras de variante, con paginación por cursor.
`catalog_products_count`	Cuenta productos con los mismos filtros e indica si el resultado es exacto o un mínimo.
`catalog_product_get`	Lee descripción, precios, estado, etiquetas, imágenes, especificaciones y variantes de un producto.
`catalog_product_draft_propose`	Crea una propuesta idempotente de producto borrador para revisión humana.
`catalog_product_draft_proposal_get`	Consulta una propuesta de esa instalación.
`analytics_metrics_list`	Consulta las métricas y dimensiones disponibles.
`analytics_metrics_query`	Consulta métricas por período y dimensiones, con comparación.
`orders_list`	Lista órdenes de la tienda y vendedor conectados.
`orders_get`	Consulta importes, artículos, pagos y estado de una orden.
`channels_sources_list`	Lista fuentes de importación y su estado.
`channels_source_get`	Consulta sincronización y errores de una fuente.
`channels_list`	Lista canales de venta.
`channels_product_publications_list`	Consulta los orígenes y publicaciones de un producto.
`channels_listings_list`	Lista productos y bloqueos de publicación de un canal.
`channels_mappings_list`	Consulta mapeos de categorías, marcas y atributos, indicando dirección y propietario.
`channels_mapping_candidates_list`	Lista candidatos de mapeo pendientes en una fuente.
`storefront_project_get`	Consulta el proyecto de la tienda.
`storefront_draft_get`	Lee el borrador y su versión.
`storefront_theme_catalog_get`	Consulta el manifiesto y schemas del theme.
`storefront_draft_patch_propose`	Prepara cambios del theme con preview y URL de aprobación.
`storefront_draft_patch_get`	Consulta el estado y recibo de una propuesta del theme.

Las consultas de productos requieren catalog:read tanto en la aplicación como en los permisos del usuario. La tienda y el vendedor provienen de la conexión; no se pueden cambiar mediante argumentos. Los registros OAuth dinámicos nuevos solicitan lectura y creación de catálogo, lectura de métricas, órdenes y canales, y lectura/edición de contenido, limitadas a los permisos del usuario. Las conexiones anteriores que solo tienen catalog:create necesitan actualizar los permisos de su aplicación u obtener un nuevo registro OAuth con lectura. Renovar el token o volver a autorizar el mismo cliente no agrega ese permiso.

Las métricas requieren analytics:read; órdenes, order:read; fuentes, canales y mapeos, channel:read. El editor requiere content:read para consultas y además content:update para propuestas. Fuentes, canales, mapeos y themes requieren alcance de tienda, sin vendedor. Las publicaciones de un producto siguen su alcance de catálogo y requieren catalog:read.

Los cambios del theme requieren leer proyecto, borrador y manifiesto antes de proponer hasta 50 operaciones con sus versiones. La respuesta incluye preview y approvalUrl: la persona revisa y aprueba en Ecomiq. El agente consulta el estado con storefront_draft_patch_get; succeeded y responseAudit confirman que cambió el borrador. La publicación es independiente. En chat interno también se puede proponer un cambio del theme sin abrir primero el builder.

En catalog_products_list, omite options.search para listar o úsalo para buscar. La página tiene 20 productos por defecto y admite hasta 100. Para continuar, envía nextCursor como options.cursor y conserva los filtros. Los borradores están incluidos; los archivados se incluyen con options.includeArchived: true o options.status: "archived". catalog_product_get recibe productId del listado, incluso para archivados. options.sourceIds filtra por IDs de fuentes obtenidos del listado de fuentes. Estas herramientas consultan catálogo; no devuelven disponibilidad de inventario.

El conteo devuelve total, precision y limit. El límite predeterminado es 10 000 y puede aumentarse hasta 100 000. precision: "exact" identifica un total exacto; precision: "atLeast" debe comunicarse como «al menos», nunca como total exacto. El número de resultados de una página no es el total del catálogo.

Crear la propuesta no crea ni publica el producto. La aprobación se realiza en la interfaz first-party autenticada y la ejecución conserva permisos, idempotencia y auditoría de dominio. El cliente delegado que propone no puede autoaprobar. Las herramientas internas del chat no forman parte de este catálogo por estar registradas en ecomiq-ai.

El servidor MCP entrega operaciones y datos estructurados; el modelo del cliente externo redacta su respuesta. Esto es distinto del chat de Chopper en Admin, donde Ecomiq ejecuta el modelo. Los embeddings de la búsqueda documental recuperan fragmentos, no generan respuestas ni ejecutan cambios.

Conectar desde ChatGPT o Claude

Agrega https://chopper.ecomiq.pe/mcp como conector personalizado, inicia sesión en Ecomiq y elige la tienda que quieres conectar. Necesitas permiso para conectar aplicaciones y acceso de lectura de catálogo para consultar productos. El registro OAuth dinámico, el consentimiento, PKCE y la renovación de tokens se gestionan entre el cliente y Ecomiq. No pegues contraseñas ni tokens en el chat.

Cada instalación conserva su tienda y sus permisos aunque otros comercios usen el mismo cliente. Para cambiar de tienda, realiza una nueva conexión. Para revocar acceso, abre Configuración → Desarrolladores → Apps y elige Desconectar. Se impiden nuevas renovaciones; un token ya emitido puede conservar acceso hasta diez minutos. Desconectar una tienda no desconecta otras.

Puedes pedir «¿Qué tienda conecté?», «Busca el SKU …», «¿Cuántos productos tengo?» o «Prepara una propuesta de producto». La disponibilidad en los directorios de ChatGPT y Claude depende de su revisión; conectar un servidor personalizado no significa que ya esté publicado en esos directorios.

Datos compartidos

El conector recibe los argumentos de las herramientas solicitadas y la identidad OAuth necesaria para comprobar permisos. Envía al cliente externo la tienda, productos, órdenes, métricas, fuentes, canales, mapeos, contenido del theme o propuestas que se consulten. No recibe automáticamente el historial completo de la conversación. ChatGPT o Claude procesan las respuestas según sus propias políticas; Ecomiq conserva los datos y registros bajo su política de privacidad. La desconexión no elimina propuestas ni registros de auditoría existentes.

Contratos OpenAPI

API	Contrato
Admin	Descargar JSON
Storefront	Descargar JSON
Auth	Descargar JSON
UCP	Descargar JSON

Entrega solo el contrato de la API que usará el agente. Admin, Storefront, Auth y UCP no comparten todas las reglas de autenticación, contexto, paginación o error.

Qué debe tomar de cada fuente

Fuente	Úsala para
Guía Markdown	Orden del flujo, decisiones y restricciones operativas.
OpenAPI	Método, ruta, parámetros, cuerpo, esquemas, respuestas y seguridad publicada.
Página del endpoint	Presentación legible del contrato de esa operación.

Si un permiso, ejemplo o regla no aparece en esas fuentes, el agente debe marcarlo como desconocido. No debe inventarlo a partir del nombre del endpoint.

Instrucción recomendada

Prompt

Implementa esta operación con la guía y el OpenAPI adjuntos.
Conserva método, ruta, operationId, parámetros y esquemas.
No inventes campos, permisos, respuestas ni ejemplos.
Distingue Admin, Storefront, Auth y UCP.
Antes de reintentar, comprueba la idempotencia de la operación.

Flujo de trabajo

Elige una API y una operación concreta.
Adjunta la guía del flujo y el fragmento OpenAPI de esa operación.
Pide un cliente tipado que use solo los campos del contrato.
Ejecuta contra credenciales y datos de desarrollo.
Compara la petición y la respuesta reales con el contrato publicado.

No deduzcas autorización

Que una operación aparezca en OpenAPI no concede acceso. Usa la seguridad publicada y la respuesta del servidor; no supongas nombres de permisos que el contrato no declara.

No compartas client_secret, access tokens, datos personales ni respuestas de producción en el prompt. Sustituye los valores antes de adjuntar ejemplos.