Conecte o ChatGPT, Claude, Gemini ou Copilot à sua loja

Antes de começar: o que você vai conectar

A loja tem uma API REST que expõe o mesmo que você vê no painel: produtos, preços por lista, categorias, listas de preços, clientes e pedidos. Um agente de IA é, no fundo, um programa que sabe ler uma referência de API e fazer chamadas HTTP. Ao conectá-lo, você lhe dá mãos para operar a loja e fica com a voz: você pede em português, ele chama a API.

Há três coisas para ter à mão antes do primeiro passo:

• A API ativa na sua conta. É um serviço adicional. Se em Configuração → ERP não aparecer a opção API Token, ou se todas as chamadas devolverem 403, peça a ativação ao suporte.
• Um usuário administrador. Só os administradores (ou um usuário com permissão ERP) veem e geram o token.
• A referência da API. Fica no painel, no mesmo cartão do token (link para a documentação técnica), e resumida na central de ajuda. É o que você vai passar à IA para ela aprender os endpoints.

Passo 1: gere o token da API

1. No painel de administração, entre em Configuração → ERP.
2. Escolha a opção API Token entre as integrações disponíveis.
3. Clique em Gerar Token. Ele aparece uma única vez: copie ou baixe (botão Baixar) nesse momento.
4. Anote também a URL base: é o domínio do seu painel, e todos os endpoints ficam sob /api/v1/.

Teste se funciona antes de continuar. Em um terminal, com o token em uma variável:

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"

Se voltar um JSON com data, total, offset e limit, a porta está aberta. Se voltar 401 o token não está viajando bem; se voltar 403 a API não está ativa na sua conta.

Passo 2: escolha a via conforme a IA que você usa

Todas as IAs chegam à mesma API; o que muda é a tomada. Há quatro vias, da mais rápida à mais sob medida:

Via A: um agente com terminal (Claude Code, Codex, Gemini CLI, Copilot)

Esses agentes rodam no seu computador e podem executar comandos, então chamam a API diretamente, sem nenhum conector no meio. Só é preciso deixar o token à mão e explicar a loja em um arquivo de contexto.

1. Crie uma pasta de trabalho (por exemplo minha-loja-ia) e abra o agente ali: claude, codex, gemini ou copilot.
2. Deixe o token em uma variável de ambiente, nunca dentro de um arquivo do projeto: no terminal, antes de abrir o agente, export VXM_TOKEN="…" e export VXM_URL="https://seu-painel…".
3. Escreva o arquivo de contexto que cada agente lê ao iniciar: CLAUDE.md para o Claude Code, AGENTS.md para o Codex, GEMINI.md para o Gemini CLI, .github/copilot-instructions.md para o Copilot. Mesmo conteúdo para todos (modelo abaixo).
4. Peça algo só de leitura para começar: «Liste os últimos 10 pedidos com cliente e total». O agente lê a referência, monta o curl e mostra a tabela.

Modelo do arquivo de contexto

Cole como está e ajuste a URL. É o que faz a IA se comportar como um funcionário cuidadoso e não como um script solto:

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

Via B: um conector MCP para os apps de chat (Claude, ChatGPT, Gemini, Copilot)

Os apps de chat não executam comandos no seu computador: eles usam MCP (Model Context Protocol), o padrão com que um assistente descobre e usa ferramentas externas. Como a VendasxAtacado ainda não publica um conector MCP oficial, levanta-se uma ponte: um pequeno servidor MCP que traduz cada ferramenta («listar pedidos», «mudar preço») na chamada REST correspondente, com o token guardado dentro da ponte e não no chat.

B1. Peça à IA que escreva a ponte

Com o agente da via A aberto na mesma pasta, um pedido assim basta:

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 sem escrever código: uma ponte genérica OpenAPI → MCP (há várias de código aberto) que pega um esquema OpenAPI da API e expõe cada operação como ferramenta. O esquema a IA gera a partir da referência, igual à via C.

B2. Conecte a ponte no seu app

Há dois modos. Local: a ponte roda no seu computador e os apps de desktop a usam. Remoto: a ponte roda em um servidor com HTTPS e URL pública, e os apps web e móveis a usam, conectando-se a partir da nuvem do provedor.

Via C: um GPT personalizado ou um agente com ações (OpenAPI)

Se você quer um assistente montado para a sua equipe («Operador da loja») que qualquer um use pelo ChatGPT ou pelo Microsoft 365 Copilot, a peça é um esquema OpenAPI da API com autenticação Bearer. Hoje a plataforma não publica esse esquema, mas a IA o escreve a partir da referência:

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 → Criar → Configurar → Ações → Criar nova ação → colar o esquema → Autenticação: Chave de API, tipo Bearer, colar o token → Testar com uma operação de leitura. As operações marcadas como consequentes pedem confirmação antes de executar.
2. Copilot Studio / Microsoft 365 Copilot. Ferramentas → Adicionar → Conector personalizado → Importar de OpenAPI → autenticação por chave no header Authorization → publicar o agente para a equipe.
3. Gems do Gemini e Projetos do Claude. Não executam ações por conta própria: use o conector MCP da via B e salve as regras do modelo como instruções do Gem ou do Projeto.

Via D: automações (n8n, Make, Zapier) e desenvolvedores com SDK

Para as tarefas que precisam rodar sozinhas, sem que ninguém peça, a IA se combina com uma plataforma de automação:

• n8n, Make, Zapier, Power Automate. Um gatilho (toda manhã às 8, ou quando chega um e-mail), um nó HTTP Request para $VXM_URL/api/v1/orders com o header Authorization: Bearer, e um nó de IA (OpenAI, Anthropic, Google, Mistral) que resume, classifica ou decide. O resultado vai para o WhatsApp, Slack, um e-mail ou uma planilha.
• SDKs dos provedores. Se a sua equipe programa, qualquer SDK com tool use ou function calling (Anthropic, OpenAI, Google, Mistral) define as ferramentas sobre os endpoints e deixa o agente rodando na sua infraestrutura. Modelos abertos (Llama, DeepSeek, Qwen com Ollama) funcionam igual: a API é a mesma.
• Sem webhooks de saída, por enquanto. A API não avisa quando algo acontece: a automação pergunta de tempos em tempos (por exemplo, pedidos dos últimos 15 minutos) e age sobre o que é novo.

Como gerenciar no dia a dia: as regras que vale dar

Uma IA conectada à API tem o mesmo poder que um administrador. A diferença entre uma ferramenta excelente e um susto está em seis regras:

1. Leitura primeiro. Na primeira semana, só consultas e relatórios. Quando confiar em como ela interpreta a loja, habilite escritas.
2. Confirmação antes de escrever. Todo POST, PUT ou DELETE é anunciado e espera o seu OK. Em mudanças em massa, tabela prévia com o antes e o depois.
3. O código do produto é a chave. Produtos são endereçados por code, o resto por id. Antes de criar, buscar: assim não se duplicam produtos por um acento ou um espaço.
4. Respeitar os limites. 120 chamadas por minuto por método, páginas de até 100, corpos de até 5 MB. Diante de 429 esperar; diante de 409 reler o recurso e tentar de novo.
5. O token não viaja pelo chat. Ele vive em uma variável de ambiente, na ponte MCP ou na configuração de autenticação do GPT. Se algum dia aparecer em uma conversa, peça um novo ao suporte.
6. Encerrar com resumo. Cada sessão termina com o que mudou, quantos registros e o que ficou pendente. Nos pedidos, as notas internas deixam rastro do que a IA fez e para quem.

Prompts para começar

Copie e cole. Estão ordenados do menor ao maior risco, e cada um usa uma parte diferente da API:

• «Liste os pedidos de hoje com cliente, total e status. Marque quais não têm pagamento registrado.»
• «Quais produtos da categoria Limpeza estão com estoque zero? Monte a tabela com código, nome e última vez que foi vendido.»
• «Compare os preços da lista Atacado A e da Atacado B para os 50 produtos mais vendidos e mostre a diferença percentual.»
• «Aumente em 8% todos os preços da lista Atacado B na categoria Limpeza. Antes me mostre a tabela e espere meu OK.»
• «Cadastre os produtos desta planilha: código, nome, categoria, variantes e preço por lista. Os que já existem, atualize; os novos, crie. Diga quantos de cada antes de executar.»
• «Estes 12 clientes têm dívida vencida (passo os e-mails). Bloqueie-os e anote em suas fichas o motivo e a data.»
• «Toda segunda às 8 monte o resumo semanal: pedidos por cliente, ticket médio, produtos sem estoque, e deixe pronto como script agendado.»

Erros frequentes e o que significam

A API responde com códigos HTTP padrão e um corpo {"error": {"code": "…", "message": "…"}}. Os que você vai ver com mais frequência:

O que a API não faz hoje

• Não cria pedidos. Os pedidos nascem no carrinho da loja ou no painel, onde o motor de preços, listas e descontos os calcula. A IA os lê, anula e deixa notas.
• Não exclui clientes. Bloqueia com blocked: true, e o histórico fica.
• Não avisa sozinha. Não há webhooks de saída: as automações consultam periodicamente.
• Sem conector MCP nem esquema OpenAPI oficiais, por enquanto. Ambos se montam em minutos com a IA a partir da referência, como explicado nas vias B e C.