API: visão geral

Esta página é para lojistas e desenvolvedores que querem ligar um sistema externo à Hyper. Se você só usa o painel para vender, não precisa dela.

Resumo rápido

Item	Valor
Nome	Hyper Developer API
Versão	v1
Raiz	`https://hypesquad.store/api`
Prefixo das rotas	`/api/v1`
Cabeçalho de autenticação	`X-Hyper-API-Key`
Verificação de saúde	`GET /api/health`
Descoberta (pública)	`GET /api/v1`
Formato das respostas	JSON

O que dá para fazer com a API

Objetivo	Exemplo prático
Consultar pedidos	Listar os pedidos do dia em uma planilha ou sistema interno
Acompanhar vendas	Montar um painel próprio com o resumo de vendas
Ver transações e saques	Conferir movimentações financeiras no seu sistema de contabilidade
Listar produtos e clientes	Sincronizar o catálogo ou a base de clientes com outra ferramenta
Receber eventos	Reagir quando uma venda é aprovada, por exemplo

Comece em 3 passos

Teste se a API está no ar

Faça uma requisição para GET https://hypesquad.store/api/health. Ela não exige chave.

Consulte a descoberta

Faça uma requisição para GET https://hypesquad.store/api/v1. A resposta mostra os escopos, os limites e as rotas disponíveis no momento.

Use sua chave nas rotas protegidas

Envie o cabeçalho X-Hyper-API-Key com a sua chave em todas as rotas de dados.

Respostas reais da API

Os exemplos abaixo foram obtidos diretamente da API pública da Hyper.

Verificação de saúde

curl https://hypesquad.store/api/health

{
  "status": "ok",
  "time": "2026-10-18T16:11:56.165Z"
}

Campo	Tipo	O que significa
`status`	texto	`ok` quando a API está funcionando
`time`	data e hora (ISO 8601, UTC)	Horário do servidor no momento da resposta

Descoberta da API

Esta rota é pública e serve para o seu sistema descobrir sozinho o que está disponível.

curl https://hypesquad.store/api/v1

{
  "name": "Hyper Developer API",
  "version": "v1",
  "header": "X-Hyper-API-Key",
  "docs": "/documentacao#api",
  "health": "/api/health",
  "root": "/api",
  "basePath": "/api/v1",
  "authentication": {
    "discovery": "public",
    "data": "Leituras e ações documentadas requerem X-Hyper-API-Key e o escopo indicado para cada rota."
  },
  "rateLimit": {
    "scopedRequests": { "requests": 120, "windowSeconds": 60, "per": "API key", "default": true },
    "discoveryRequests": { "requests": 300, "windowSeconds": 900, "per": "client IP", "default": true }
  },
  "scopes": ["account:read", "sales:read", "orders:read", "..."],
  "endpoints": [
    { "method": "GET", "path": "/api/v1/account", "scope": "account:read" },
    "..."
  ]
}

string

Nome da API.

string

Versão atual. Hoje é v1.

string

Nome do cabeçalho em que você envia a chave.

string

Prefixo de todas as rotas de dados.

object

Diz quais rotas são públicas (discovery: public) e quais exigem chave e escopo.

object

Limites de requisição. Veja a tabela em Limites de requisição.

string[]

Lista de escopos que uma chave pode ter.

object[]

Lista de rotas com method, path e o scope exigido.

Rota protegida sem chave

Se você chamar uma rota de dados sem a chave, ou com uma chave inválida, a API responde com o status 401.

Requisição sem chave

curl https://hypesquad.store/api/v1/account
# HTTP 401

Autenticação

Envie a chave no cabeçalho X-Hyper-API-Key em todas as rotas de dados.

curl https://hypesquad.store/api/v1/account \
  -H "X-Hyper-API-Key: SUA_CHAVE_AQUI"

const resposta = await fetch("https://hypesquad.store/api/v1/account", {
  headers: { "X-Hyper-API-Key": process.env.HYPER_API_KEY },
});
const dados = await resposta.json();

import os
import requests

resposta = requests.get(
    "https://hypesquad.store/api/v1/account",
    headers={"X-Hyper-API-Key": os.environ["HYPER_API_KEY"]},
)
dados = resposta.json()

Trate a chave como uma senha. Nunca coloque a chave no código do site (frontend), em repositórios públicos ou em prints. Se ela vazar, revogue a chave e gere outra.

O local exato no painel para gerar ou revogar uma chave não foi confirmado. Consulte a documentação técnica da Hyper ou o suporte.

Limites de requisição

Tipo de rota	Limite	Janela	Contado por
Rotas de dados (com escopo)	120 requisições	60 segundos	Chave de API
Rotas de descoberta	300 requisições	900 segundos (15 minutos)	IP de quem chama

Se você passar do limite, espere um pouco antes de tentar de novo e aumente o tempo de espera a cada nova falha. Guarde em cache os dados que mudam pouco, como a lista de produtos.

Escopos

Cada chave tem um ou mais escopos. Uma chamada para uma rota fora dos escopos da chave é recusada.

Escopo	Tipo	Permite
`account:read`	leitura	Ler os dados da conta
`sales:read`	leitura	Ler o resumo de vendas
`orders:read`	leitura	Ler pedidos
`transactions:read`	leitura	Ler transações
`withdrawals:read`	leitura	Ler saques
`products:read`	leitura	Ler produtos
`customers:read`	leitura	Ler clientes
`events:read`	leitura	Ler eventos
`events:ack`	ação	Confirmar o recebimento de eventos
`audit:write`	ação	Registrar ações de auditoria

Endpoints

Lista retornada pela rota de descoberta (GET /api/v1).

Método	Rota	Escopo exigido
GET	`/api/v1/account`	`account:read`
GET	`/api/v1/sales/summary`	`sales:read`
GET	`/api/v1/orders`	`orders:read`
GET	`/api/v1/orders/:id`	`orders:read`
GET	`/api/v1/transactions`	`transactions:read`
GET	`/api/v1/transactions/:id`	`transactions:read`
GET	`/api/v1/withdrawals`	`withdrawals:read`
GET	`/api/v1/withdrawals/:id`	`withdrawals:read`
GET	`/api/v1/products`	`products:read`
GET	`/api/v1/customers`	`customers:read`
GET	`/api/v1/events`	`events:read`
POST	`/api/v1/events/ack`	`events:ack`
POST	`/api/v1/actions`	`audit:write`

Em :id, coloque o identificador do item. Exemplo: /api/v1/orders/12345.

Os campos que cada rota de dados devolve dependem da sua conta e não foram publicados aqui. Para ver o formato real, faça uma chamada com a sua chave e confira a resposta.

Rotas de pagamentos, carteira, taxas e Minecraft

Versões anteriores da documentação da Hyper citavam rotas de pagamentos Pix, carteira, taxas e entregas de Minecraft (por exemplo, POST /api/v1/payments/pix e GET /api/v1/wallet). Elas não aparecem na rota de descoberta atual. Antes de usar alguma delas, confirme com o suporte se ainda estão disponíveis para a sua conta.

Eventos

A Hyper registra eventos que o seu sistema pode ler e confirmar.

Evento	Quando acontece
`sale.approved`	Pagamento de uma venda aprovado
`subscription.renewed`	Assinatura renovada
`ticket.created`	Ticket criado

Como funciona:

Leia os eventos com GET /api/v1/events (escopo events:read).
Processe cada evento no seu sistema.
Confirme o recebimento com POST /api/v1/events/ack (escopo events:ack).

O formato do corpo de POST /api/v1/events/ack e a configuração de webhooks no painel não foram confirmados. Consulte a documentação técnica da Hyper.

Códigos de resposta

Status	Significado	O que fazer
200	Deu certo	Use os dados da resposta
401	Chave ausente ou inválida	Confira o cabeçalho `X-Hyper-API-Key`
403	Chave sem o escopo da rota	Use uma chave com o escopo exigido
429	Limite de requisições atingido	Espere e tente de novo mais devagar

Problemas comuns

Recebo erro 401

A chave não foi enviada ou está errada. Confira se o cabeçalho se chama exatamente X-Hyper-API-Key e se não há espaços sobrando antes ou depois da chave.

Recebo erro 403

A chave é válida, mas não tem o escopo da rota. Veja na tabela de Endpoints qual escopo a rota exige.

Recebo erro 429

Você passou do limite. Espere alguns segundos, tente de novo e aumente a espera a cada nova falha. Use cache para dados que mudam pouco.

Não sei se o problema é meu ou da API

Chame GET /api/health. Se a resposta tiver "status": "ok", a API está funcionando. Consulte também a página de status.

Quando pedir ajuda

Fale com o suporte se:

não conseguir gerar ou revogar uma chave;
receber erros que não estão nesta página;
precisar de uma rota que não aparece na descoberta.

Canais de atendimento

Fale com o suporte para dúvidas técnicas.

Documentação técnica da Hyper

Consulte a referência publicada no site da Hyper.

Introdução

Conta e acesso

Lojas e personalização

Produtos e catálogo

Compras e checkout

Pedidos e entregas

Domínios e endereços

Planos, saldo e cobranças

Segurança e privacidade

Problemas comuns

Suporte e contato

Para desenvolvedores

API: visão geral

Resumo rápido

O que dá para fazer com a API

Comece em 3 passos

Respostas reais da API

Verificação de saúde

Descoberta da API

Rota protegida sem chave

Autenticação

Limites de requisição

Escopos

Endpoints

Eventos

Códigos de resposta

Problemas comuns

Quando pedir ajuda

Canais de atendimento

Documentação técnica da Hyper

​Resumo rápido

​O que dá para fazer com a API

​Comece em 3 passos

​Respostas reais da API

​Verificação de saúde

​Descoberta da API

​Rota protegida sem chave

​Autenticação

​Limites de requisição

​Escopos

​Endpoints

​Eventos

​Códigos de resposta

​Problemas comuns

​Quando pedir ajuda

Canais de atendimento

Documentação técnica da Hyper

Resumo rápido

O que dá para fazer com a API

Comece em 3 passos

Respostas reais da API

Verificação de saúde

Descoberta da API

Rota protegida sem chave

Autenticação

Limites de requisição

Escopos

Endpoints

Eventos

Códigos de resposta

Problemas comuns

Quando pedir ajuda