Conectá ChatGPT, Claude, Gemini o Copilot a tu tienda

Antes de empezar: qué vas a conectar

La tienda tiene una API REST que expone lo mismo que ves en el panel: productos, precios por lista, categorías, listas de precios, clientes y pedidos. Un agente de IA es, en el fondo, un programa que sabe leer una referencia de API y hacer llamadas HTTP. Al conectarlo, le das manos para operar la tienda y vos te quedás con la voz: le pedís en castellano, él llama a la API.

Hay tres cosas que necesitás tener a mano antes del primer paso:

• La API activa en tu cuenta. Es un servicio adicional. Si en Configuración → ERP no aparece la opción API Token, o si todas las llamadas devuelven 403, pedí la activación por soporte.
• Un usuario administrador. Solo los administradores (o un usuario con permiso ERP) ven y generan el token.
• La referencia de la API. Está en el panel, en la misma tarjeta del token (enlace a la documentación técnica), y resumida en el centro de ayuda. Es lo que le vas a pasar a la IA para que aprenda los endpoints.

Paso 1: generá el token de la API

1. En el panel de administración, entrá a Configuración → ERP.
2. Elegí la opción API Token entre las integraciones disponibles.
3. Apretá Generar Token. Se muestra una sola vez: copialo o descargalo (botón Descargar) en ese momento.
4. Anotá también la URL base: es el dominio de tu panel, y todos los endpoints cuelgan de /api/v1/.

Probá que funciona antes de seguir. Desde una terminal, con el token en una variable:

export VXM_TOKEN="pegá-acá-tu-token"
export VXM_URL="https://tu-panel.ventasxmayor.com"
curl -s "$VXM_URL/api/v1/products?limit=3" \
-H "Authorization: Bearer $VXM_TOKEN"

Si vuelve un JSON con data, total, offset y limit, la puerta está abierta. Si vuelve 401 el token no viaja bien; si vuelve 403 la API no está activa en tu cuenta.

Paso 2: elegí la vía según la IA que uses

Todas las IA llegan a la misma API; lo que cambia es el enchufe. Hay cuatro vías, de la más rápida a la más a medida:

Vía A: un agente con terminal (Claude Code, Codex, Gemini CLI, Copilot)

Estos agentes corren en tu computadora y pueden ejecutar comandos, así que llaman a la API directamente, sin ningún conector en el medio. Lo único que hay que hacer es dejarles el token a mano y explicarles la tienda en un archivo de contexto.

1. Creá una carpeta de trabajo (por ejemplo mi-tienda-ia) y abrí ahí el agente: claude, codex, gemini o copilot.
2. Dejá el token en una variable de entorno, nunca dentro de un archivo del proyecto: en la terminal, antes de abrir el agente, export VXM_TOKEN="…" y export VXM_URL="https://tu-panel…".
3. Escribí el archivo de contexto que cada agente lee al arrancar: CLAUDE.md para Claude Code, AGENTS.md para Codex, GEMINI.md para Gemini CLI, .github/copilot-instructions.md para Copilot. Mismo contenido para todos (abajo hay una plantilla).
4. Pedile algo de solo lectura para arrancar: «Listame los últimos 10 pedidos con cliente y total». El agente lee la referencia, arma el curl y te muestra la tabla.

Plantilla del archivo de contexto

Pegalo tal cual y ajustá la URL. Es lo que hace que la IA se comporte como un empleado prolijo y no como un script suelto:

# Tienda mayorista — reglas para operar por la API
Base URL: $VXM_URL/api/v1  (token en $VXM_TOKEN, header Authorization: Bearer)
Referencia: la documentación de la API del panel (Configuración → ERP → API Token)
y https://ventasxmayor.com.ar/centro-de-ayuda/integ-api
## Qué podés tocar
- products (por código), products/{code}/images, products/{code}/prices (por lista y variante)
- categories, price-lists
- customers (crear, editar, bloquear con blocked:true — nunca borrar)
- orders (listar, leer, PUT solo void o internal_notes — no se crean)
## Cómo trabajar
1. Antes de cualquier POST/PUT/DELETE, mostrame qué vas a cambiar y esperá mi OK.
2. En cambios masivos, primero una tabla previa (antes → después) y un conteo.
3. Paginá con limit=100. Si recibís 429, esperá y reintentá. Si recibís 409, releé el recurso.
4. Nunca imprimas el token ni lo guardes en archivos.
5. Al terminar, resumí qué cambió, cuántos registros y qué quedó pendiente.

Vía B: un conector MCP para las apps de chat (Claude, ChatGPT, Gemini, Copilot)

Las apps de chat no ejecutan comandos en tu computadora: usan MCP (Model Context Protocol), el estándar con el que un asistente descubre y usa herramientas externas. Como VentasxMayor todavía no publica un conector MCP oficial, se levanta un puente: un pequeño servidor MCP que traduce cada herramienta («listar pedidos», «cambiar precio») a la llamada REST correspondiente, con el token guardado adentro del puente y no en el chat.

B1. Pedile a la IA que escriba el puente

Con el agente de la vía A abierto en la misma carpeta, un pedido así alcanza:

Escribí un servidor MCP (TypeScript o Python, SDK oficial de MCP) que exponga como
herramientas los endpoints de /api/v1 que están en la referencia: listar/leer/crear/editar
productos, precios por lista, categorías, listas de precios, clientes y pedidos (leer, anular,
notas internas). Base URL y token salen de VXM_URL y VXM_TOKEN. Transporte stdio para uso
local y Streamable HTTP para uso remoto. Cada herramienta de escritura debe describir
claramente qué cambia. Probalo contra la API real con una llamada de solo lectura.

Alternativa sin escribir código: un puente genérico OpenAPI → MCP (hay varios de código abierto) que toma un esquema OpenAPI de la API y expone cada operación como herramienta. El esquema lo genera la IA a partir de la referencia, igual que en la vía C.

B2. Enchufá el puente en tu app

Hay dos modos. Local: el puente corre en tu computadora y lo usan las apps de escritorio. Remoto: el puente corre en un servidor con HTTPS y URL pública, y lo usan las apps web y móviles, que se conectan desde la nube del proveedor.

Vía C: un GPT personalizado o un agente con acciones (OpenAPI)

Si querés un asistente armado para tu equipo («Operador de la tienda») que cualquiera use desde ChatGPT o desde Microsoft 365 Copilot, la pieza es un esquema OpenAPI de la API con autenticación Bearer. Hoy la plataforma no publica ese esquema, pero la IA lo escribe a partir de la referencia:

Generá un esquema OpenAPI 3.1 en YAML de los endpoints /api/v1 de la referencia, con
securitySchemes bearerAuth (http, bearer), el servidor $VXM_URL, y descripciones claras
de cada operación y parámetro (offset, limit, category, customer). Marcá como
x-openai-isConsequential: true las operaciones POST, PUT y DELETE.

1. GPT personalizado (ChatGPT). Explorar GPTs → Crear → Configurar → Acciones → Crear nueva acción → pegar el esquema → Autenticación: Clave de API, tipo Bearer, pegar el token → Probar con una operación de lectura. Las operaciones marcadas como consecuentes piden confirmación antes de ejecutarse.
2. Copilot Studio / Microsoft 365 Copilot. Herramientas → Agregar → Conector personalizado → Importar desde OpenAPI → autenticación por clave en el header Authorization → publicar el agente para tu equipo.
3. Gems de Gemini y Proyectos de Claude. No ejecutan acciones por sí mismos: usá el conector MCP de la vía B y guardá las reglas de la plantilla como instrucciones del Gem o del Proyecto.

Vía D: automatizaciones (n8n, Make, Zapier) y desarrolladores con SDK

Para las tareas que tienen que correr solas, sin que nadie las pida, la IA se combina con una plataforma de automatización:

• n8n, Make, Zapier, Power Automate. Un disparador (cada mañana a las 8, o cuando llega un mail), un nodo HTTP Request a $VXM_URL/api/v1/orders con el header Authorization: Bearer, y un nodo de IA (OpenAI, Anthropic, Google, Mistral) que resume, clasifica o decide. El resultado va a WhatsApp, Slack, un mail o una planilla.
• SDKs de los proveedores. Si tu equipo programa, cualquier SDK con tool use o function calling (Anthropic, OpenAI, Google, Mistral) define las herramientas sobre los endpoints y deja el agente corriendo en tu infraestructura. Los modelos abiertos (Llama, DeepSeek, Qwen con Ollama) funcionan igual: la API es la misma.
• Sin webhooks salientes, por ahora. La API no avisa cuando pasa algo: la automatización pregunta cada tanto (por ejemplo, pedidos de los últimos 15 minutos) y actúa sobre lo nuevo.

Cómo manejarlo día a día: las reglas que conviene darle

Una IA conectada a la API tiene el mismo poder que un administrador. La diferencia entre una herramienta excelente y un susto está en seis reglas:

1. Lectura primero. La primera semana, solo consultas y reportes. Cuando confíes en cómo interpreta la tienda, habilitá escrituras.
2. Confirmación antes de escribir. Todo POST, PUT o DELETE se anuncia y espera tu OK. En cambios masivos, tabla previa con el antes y el después.
3. El código de producto es la clave. Los productos se direccionan por code, lo demás por id. Antes de crear, buscar: así no se duplican productos por una tilde o un espacio.
4. Respetar los límites. 120 llamadas por minuto por método, páginas de hasta 100, cuerpos de hasta 5 MB. Ante 429 esperar; ante 409 releer el recurso y volver a intentar.
5. El token no viaja por el chat. Vive en una variable de entorno, en el puente MCP o en la configuración de autenticación del GPT. Si alguna vez aparece en una conversación, pedí uno nuevo por soporte.
6. Cierre con resumen. Cada sesión termina con qué cambió, cuántos registros y qué quedó pendiente. En los pedidos, las notas internas dejan rastro de lo que hizo la IA y para quién.

Prompts para arrancar

Copiá y pegá. Están ordenados de menor a mayor riesgo, y cada uno usa una parte distinta de la API:

• «Listame los pedidos de hoy con cliente, total y estado. Marcá cuáles no tienen pago registrado.»
• «¿Qué productos de la categoría Limpieza tienen stock cero? Armame la tabla con código, nombre y última vez que se vendió.»
• «Compará los precios de la lista Mayorista A y la Mayorista B para los 50 productos más vendidos y mostrame la diferencia porcentual.»
• «Subí un 8% todos los precios de la lista Mayorista B en la categoría Limpieza. Antes mostrame la tabla y esperá mi OK.»
• «Cargá los productos de esta planilla: código, nombre, categoría, variantes y precio por lista. Los que ya existen, actualizalos; los nuevos, crealos. Decime cuántos de cada uno antes de ejecutar.»
• «Estos 12 clientes tienen deuda vencida (te paso los correos). Bloquealos y anotá en sus fichas el motivo y la fecha.»
• «Todos los lunes a las 8 armá el resumen semanal: pedidos por cliente, ticket promedio, productos sin stock, y dejalo listo como script programado.»

Errores frecuentes y qué significan

La API responde con códigos HTTP estándar y un cuerpo {"error": {"code": "…", "message": "…"}}. Los que vas a ver más seguido:

Lo que la API no hace hoy

• No crea pedidos. Los pedidos nacen en el carrito de la tienda o en el panel, donde el motor de precios, listas y descuentos los calcula. La IA los lee, los anula y les deja notas.
• No borra clientes. Los bloquea con blocked: true, y el historial queda.
• No avisa sola. No hay webhooks salientes: las automatizaciones consultan periódicamente.
• Sin conector MCP ni esquema OpenAPI oficiales, por ahora. Ambos se arman en minutos con la IA a partir de la referencia, como se explica en las vías B y C.