> ## Documentation Index
> Fetch the complete documentation index at: https://docs.hypesquad.store/llms.txt
> Use this file to discover all available pages before exploring further.

# API: visão geral

> Conheça a Hyper Developer API v1: autenticação, limites, escopos, endpoints e exemplos de resposta reais.

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** | <Badge color="green">v1</Badge> |
| **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

<Steps>
  <Step title="Teste se a API está no ar">
    Faça uma requisição para `GET https://hypesquad.store/api/health`. Ela não exige chave.
  </Step>

  <Step title="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.
  </Step>

  <Step title="Use sua chave nas rotas protegidas">
    Envie o cabeçalho `X-Hyper-API-Key` com a sua chave em todas as rotas de dados.
  </Step>
</Steps>

## Respostas reais da API

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

### Verificação de saúde

<CodeGroup>
  ```bash Requisição theme={null}
  curl https://hypesquad.store/api/health
  ```

  ```json 200 OK theme={null}
  {
    "status": "ok",
    "time": "2026-10-18T16:11:56.165Z"
  }
  ```
</CodeGroup>

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

<CodeGroup>
  ```bash Requisição theme={null}
  curl https://hypesquad.store/api/v1
  ```

  ```json 200 OK highlight={2-4,8-10} theme={null}
  {
    "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" },
      "..."
    ]
  }
  ```
</CodeGroup>

<ResponseField name="name" type="string">
  Nome da API.
</ResponseField>

<ResponseField name="version" type="string">
  Versão atual. Hoje é `v1`.
</ResponseField>

<ResponseField name="header" type="string">
  Nome do cabeçalho em que você envia a chave.
</ResponseField>

<ResponseField name="basePath" type="string">
  Prefixo de todas as rotas de dados.
</ResponseField>

<ResponseField name="authentication" type="object">
  Diz quais rotas são públicas (`discovery: public`) e quais exigem chave e escopo.
</ResponseField>

<ResponseField name="rateLimit" type="object">
  Limites de requisição. Veja a tabela em [Limites de requisição](#limites-de-requisição).
</ResponseField>

<ResponseField name="scopes" type="string[]">
  Lista de escopos que uma chave pode ter.
</ResponseField>

<ResponseField name="endpoints" type="object[]">
  Lista de rotas com `method`, `path` e o `scope` exigido.
</ResponseField>

### 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 <Badge color="red">401</Badge>.

```bash Requisição sem chave theme={null}
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.

<CodeGroup>
  ```bash cURL theme={null}
  curl https://hypesquad.store/api/v1/account \
    -H "X-Hyper-API-Key: SUA_CHAVE_AQUI"
  ```

  ```javascript JavaScript theme={null}
  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();
  ```

  ```python Python theme={null}
  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()
  ```
</CodeGroup>

<Warning>
  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.
</Warning>

<Note>
  O local exato no painel para gerar ou revogar uma chave não foi confirmado. Consulte a [documentação técnica da Hyper](https://hypesquad.store/documentacao#api) ou o suporte.
</Note>

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

<Tip>
  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.
</Tip>

## Escopos

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

| Escopo | Tipo | Permite |
| - | - | - |
| `account:read` | <Badge color="blue">leitura</Badge> | Ler os dados da conta |
| `sales:read` | <Badge color="blue">leitura</Badge> | Ler o resumo de vendas |
| `orders:read` | <Badge color="blue">leitura</Badge> | Ler pedidos |
| `transactions:read` | <Badge color="blue">leitura</Badge> | Ler transações |
| `withdrawals:read` | <Badge color="blue">leitura</Badge> | Ler saques |
| `products:read` | <Badge color="blue">leitura</Badge> | Ler produtos |
| `customers:read` | <Badge color="blue">leitura</Badge> | Ler clientes |
| `events:read` | <Badge color="blue">leitura</Badge> | Ler eventos |
| `events:ack` | <Badge color="orange">ação</Badge> | Confirmar o recebimento de eventos |
| `audit:write` | <Badge color="orange">ação</Badge> | Registrar ações de auditoria |

## Endpoints

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

| Método | Rota | Escopo exigido |
| - | - | - |
| <Badge color="green">GET</Badge> | `/api/v1/account` | `account:read` |
| <Badge color="green">GET</Badge> | `/api/v1/sales/summary` | `sales:read` |
| <Badge color="green">GET</Badge> | `/api/v1/orders` | `orders:read` |
| <Badge color="green">GET</Badge> | `/api/v1/orders/:id` | `orders:read` |
| <Badge color="green">GET</Badge> | `/api/v1/transactions` | `transactions:read` |
| <Badge color="green">GET</Badge> | `/api/v1/transactions/:id` | `transactions:read` |
| <Badge color="green">GET</Badge> | `/api/v1/withdrawals` | `withdrawals:read` |
| <Badge color="green">GET</Badge> | `/api/v1/withdrawals/:id` | `withdrawals:read` |
| <Badge color="green">GET</Badge> | `/api/v1/products` | `products:read` |
| <Badge color="green">GET</Badge> | `/api/v1/customers` | `customers:read` |
| <Badge color="green">GET</Badge> | `/api/v1/events` | `events:read` |
| <Badge color="purple">POST</Badge> | `/api/v1/events/ack` | `events:ack` |
| <Badge color="purple">POST</Badge> | `/api/v1/actions` | `audit:write` |

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

<Info>
  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.
</Info>

<Accordion title="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.
</Accordion>

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

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

<Note>
  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](https://hypesquad.store/documentacao#api).
</Note>

## Códigos de resposta

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

## Problemas comuns

<AccordionGroup>
  <Accordion title="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.
  </Accordion>

  <Accordion title="Recebo erro 403">
    A chave é válida, mas não tem o escopo da rota. Veja na tabela de [Endpoints](#endpoints) qual escopo a rota exige.
  </Accordion>

  <Accordion title="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.
  </Accordion>

  <Accordion title="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](https://hypesquad.store/status).
  </Accordion>
</AccordionGroup>

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

<CardGroup cols={2}>
  <Card title="Canais de atendimento" icon="life-ring" href="/suporte/canais-de-atendimento">
    Fale com o suporte para dúvidas técnicas.
  </Card>

  <Card title="Documentação técnica da Hyper" icon="file-code" href="https://hypesquad.store/documentacao#api">
    Consulte a referência publicada no site da Hyper.
  </Card>
</CardGroup>


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.