Introdução

Visão Geral

A API HelpyGo é uma API REST que utiliza formato JSON para requisições e respostas. Todas as comunicações devem ser realizadas exclusivamente via HTTPS.

• Protocolo: REST
• Formato: JSON
• Transporte: HTTPS obrigatório

URL Base

Todas as requisições devem ser feitas para a seguinte URL base:

https://www.helpygo.com.br/api/v1/

Autenticação

A API utiliza autenticação via Bearer Token. O token deve ser enviado no header Authorization de todas as requisições.

Authorization: Bearer {seu_token}

Como obter o token

Para obter o token de autenticação, faça uma requisição GET para o endpoint de autenticação informando o código da sua conta:

GET https://www.helpygo.com.br/api/v1/autenticacao/{codigo}

Limites de Requisição

Cada endpoint possui um limite de requisições por minuto que varia conforme a operação. O limite específico é informado na documentação de cada endpoint.

Códigos de Status HTTP

A API utiliza os seguintes códigos de status HTTP para indicar o resultado das requisições:

Padrões de Dados

• Datas: formato ISO 8601 (ex: 2024-01-15T10:30:00Z)
• Strings: codificação UTF-8

MCP — Integração com IA (Documentação)

✅ O HelpyGo possui um servidor MCP oficial.

O Model Context Protocol (MCP) permite que IAs como Claude, ChatGPT, Cursor e Kiro consultem a documentação da API HelpyGo diretamente durante o desenvolvimento. O servidor MCP roda localmente na máquina do desenvolvedor via stdio (stdin/stdout), seguindo a especificação JSON-RPC 2.0.

Compatível com Kiro, Cursor, VS Code, Claude Desktop, Windsurf e qualquer IDE/agente com suporte ao protocolo MCP.

Download e Instalação

O servidor MCP está disponível na pasta api/doc/mcp/ do repositório.

1. Certifique-se de ter o Node.js (v18+) instalado na sua máquina.
2. Baixe ou clone a pasta api/doc/mcp/ e instale as dependências:

cd api/doc/mcp
npm install

3. Adicione a configuração no arquivo MCP da sua IDE:

{
  "mcpServers": {
    "helpygo-api": {
      "command": "node",
      "args": ["caminho/para/api/doc/mcp/index.js"]
    }
  }
}

Ferramentas disponíveis

Onde configurar por IDE

Especificação Técnica

MCP Operacional (Chamadas Reais)

🔧 Servidor MCP para operações reais na API

Além do MCP de documentação, o HelpyGo oferece um MCP operacional que executa chamadas HTTP reais na API — criar pedidos, consultar fila, conversar com agentes — diretamente via protocolo MCP. Requer autenticação com token Bearer.

O MCP operacional está disponível na pasta api/doc/mcp-operacional/.

Configuração

Adicione a variável de ambiente com o token da loja:

• HELPYGO_TOKEN — Token API da loja (obtido via GET api/v1/autenticacao/{codigoLoja})

{
  "mcpServers": {
    "helpygo-operacional": {
      "command": "node",
      "args": ["caminho/para/api/doc/mcp-operacional/index.js"],
      "env": {
        "HELPYGO_TOKEN": "SEU_TOKEN_API_AQUI"
      }
    }
  }
}

Tools Operacionais (8 tools)

Diferença entre os dois MCPs