Autenticação e primeira chamada

Toda requisição é autenticada por uma chave de API. Chaves são criadas na sua conta, escopadas por loja, e podem ser revogadas a qualquer momento.

1 · Crie sua chave

Em /account, clique em Nova chave, dê um nome (ex.: "Agente de IA") e escolha as lojas que ela pode acessar. A chave começa com mpk_ e é exibida uma única vez; o link MCP dela fica sempre disponível na lista de chaves.

2 · Autentique

Envie a chave no header X-API-Key. A base de todas as rotas é https://platform.mercadophone.tech.

curl https://platform.mercadophone.tech/api/v1/stores \
  -H "X-API-Key: mpk_sua_chave"

3 · Leia a resposta

Respostas são JSON. GET /api/v1/stores devolve as lojas que a sua chave cobre:

{
  "cross_unit": false,
  "stores": [
    { "system_unit_id": 1252, "name": "Loja Teste Centro" },
    { "system_unit_id": 1300, "name": "Loja Teste Shopping" }
  ]
}

As listas aceitam page e limit (até 300) como query string e respondem com total, items, page e limit.

Erros comuns

Erros usam status HTTP padrão e um corpo JSON com o campo detail explicando o que aconteceu.

Conectar uma IA (MCP)

Cada chave de API tem um link MCP próprio. Colado num assistente, como o Claude, o Cursor ou qualquer cliente MCP, ele dá à IA o conjunto completo de ferramentas de leitura e escrita da sua loja. O link usa um token separado (mpl_), então a sua chave não aparece na URL.

No Claude

1. Copie o link MCP da chave na lista de chaves em /account.
2. Em Configurações, Connectors, clique em Add custom connector e cole o link.
3. Pronto. Pergunte "quanto vendi hoje?" e a IA consulta a loja.

No Cursor ou outro cliente MCP

Clientes que aceitam header podem usar a URL sem a chave embutida:

{
  "mcpServers": {
    "mercadophone": {
      "url": "https://platform.mercadophone.tech/mcp/platform",
      "headers": { "X-API-Key": "mpk_sua_chave" }
    }
  }
}

Ferramentas disponíveis

Construa seu ERP com IA

A plataforma é o backend; a interface é você quem decide. Este guia mostra os dois caminhos: conversar com a loja por MCP, e gerar um app próprio que usa a API REST.

Caminho 1 · Converse com a loja

Conecte o link MCP no seu assistente e peça em português. A IA lê e escreve na loja usando as mesmas operações da API.

Caminho 2 · Gere seu próprio painel

Peça a uma ferramenta de vibecoding (Claude, Cursor, v0 e afins) o app que você quer: um painel de estoque baixo, um caixa simplificado, um kanban de ordens de serviço. Dê a ela o documento OpenAPI e guarde a chave num backend ou variável de ambiente.

# Prompt de exemplo para a sua ferramenta de vibecoding
Crie um painel web que mostre as vendas de hoje e os produtos
com estoque abaixo de 5 unidades. Use a API do Mercado Phone
(schema em https://platform.mercadophone.tech/openapi.json),
autenticando com o header X-API-Key lido de process.env.MP_KEY.

A referência completa de endpoints está em Referência da API; o documento OpenAPI (/openapi.json) pode ser baixado e anexado direto ao contexto da IA. Para um resumo compacto que cabe inteiro no contexto, aponte a IA para /llms.txt (índice) ou /llms-full.txt (guia + todos os endpoints em texto).

Boas práticas

• Crie uma chave por projeto: revogar uma não derruba as outras.
• Nunca exponha a chave no frontend; ela pertence a um backend ou a um assistente.
• Escope a chave só às lojas que o projeto precisa.
• Comece lendo (vendas, estoque) antes de dar permissão de escrita a agentes.

Várias lojas

Se a sua conta tem mais de uma loja, a mesma chave pode cobrir todas. Você escolhe a loja por requisição, ou consulta todas de uma vez.

Descubra as lojas da chave

curl https://platform.mercadophone.tech/api/v1/stores \
  -H "X-API-Key: mpk_sua_chave"

Escolha a loja com o header X-Unit-Id

Nos endpoints de loja única, informe a loja pelo header X-Unit-Id. Uma chave de loja única resolve sozinha, sem header. Uma chave de várias lojas sem o header recebe um erro que lista as lojas e explica o que enviar.

curl https://platform.mercadophone.tech/api/v1/inventory \
  -H "X-API-Key: mpk_sua_chave" \
  -H "X-Unit-Id: 1252"

Ou consulte todas de uma vez

Os endpoints /all consultam todas as lojas da chave e agregam o resultado. Uma loja indisponível aparece em errors, e as demais retornam normalmente.

curl https://platform.mercadophone.tech/api/v1/inventory/all \
  -H "X-API-Key: mpk_sua_chave"

{
  "stores": [
    { "system_unit_id": 1252, "total": 148, "items": [ ... ] }
  ],
  "errors": [
    { "system_unit_id": 1300, "error": "loja indisponível" }
  ],
  "total_items": 148,
  "stores_ok": 1,
  "stores_failed": 1
}

Existem versões /all para estoque, vendas, clientes, pessoas, ordens de serviço, financeiro, notas, arquivos, metas e catálogo (/api/v1/catalog/{recurso}/all).

No MCP

As ferramentas aceitam system_unit_id para escolher a loja, e as versões *_all_stores consultam todas de uma vez. A ferramenta list_my_stores lista as lojas da chave.