Autenticação
A maioria das APIs Guper exige um token de autorização enviado em cada requisição através do header x-guper-authorization. Esta página cobre como obter esse token e como usá-lo.
Credenciais
Cada conta de acesso à API recebe duas credenciais:
- API Key (
x-guper-apikey) — identificador público da sua conta. - API Secret (
x-guper-apisecret) — valor secreto, trate como uma senha.
O par inicial é gerado pela equipe de integração da Guper. Mantenha o secret seguro — ele nunca deve ser exposto no browser ou commitado num repositório.
Gerando um token
Troque as credenciais por um token de curta duração no endpoint Get token:
curl -X GET "https://{organization}.myguper.com/api/connect/token" \
-H "x-guper-apikey: <sua apikey>" \
-H "x-guper-apisecret: <seu apisecret>"
A resposta contém o token e seu vencimento:
{
"accessToken": "c074cb9bd30d7b431230877facb45e0a06790e93dea6a728cef9fdaf656bf349",
"expiresIn": "2023-08-11T15:13:00-03:00",
"dateTime": "2023-08-11T09:13:00-03:00"
}
Os tokens têm vida curta. Faça cache no seu backend até o vencimento e renove com antecedência — não chame o endpoint de auth a cada requisição.
Autenticando um usuário
Se sua integração precisa agir em nome de um usuário específico (login + senha), use o Auth. A resposta traz o personId e type correspondentes, que podem ser combinados com Gerar token de acesso para emitir um token de sessão de 30 dias para esse usuário.
Usando o token
Envie o token no header x-guper-authorization em cada requisição protegida:
curl -X POST "https://{organization}.myguper.com/api/loyalty/rewardByOrder" \
-H "x-guper-authorization: <seu token>" \
-H "Content-Type: application/json" \
-d '{ ... }'
Você pode verificar a quem um token pertence em Buscar usuário pelo token.
Login por pessoa (OAuth 2.1)
Além do caminho apiKey/apiSecret acima — que identifica uma integração — existe um segundo caminho, que identifica uma pessoa: OAuth 2.1 com PKCE, usado pelos assistentes de IA.
A diferença que importa:
apiKey / apiSecret |
OAuth 2.1 | |
|---|---|---|
| identifica | uma integração (sistema) | uma pessoa |
| quem cadastra | a equipe de integração | ninguém — registro dinâmico |
| permissões | da conta de acesso | as do perfil da pessoa no painel |
| revogar | trocar a credencial de todos | inativar aquele usuário |
Os dois convivem, e nada muda para quem já integra. Use OAuth quando o acesso for de uma pessoa e precisar respeitar o perfil dela; continue com apiKey/apiSecret para integração servidor-a-servidor.
O fluxo completo, os endpoints e o que o seu cliente precisa respeitar estão em Guper por IA (MCP).
Proof of Work (PoW)
Os endpoints de login que aceitam login + password suportam uma camada opcional de Proof of Work que mitiga ataques de forca bruta e credential stuffing.
Como funciona
Antes de enviar as credenciais, o cliente solicita um desafio ao endpoint Gerar desafio. O servidor retorna uma string challenge aleatoria e um target — um limiar hexadecimal de 64 caracteres. O cliente deve encontrar um nonce tal que:
SHA-256(challenge + nonce) <= target
O challenge e nonce resolvidos sao entao incluidos na requisicao Auth junto com login e password.
Anti-paralelismo
Cada novo challenge para o mesmo login invalida o anterior. Um atacante criando milhares de browsers contra o mesmo email descobre que apenas o ultimo challenge e valido — as outras tentativas falham na autenticacao.
Escalada de dificuldade
O servidor rastreia quantos challenges foram solicitados para um dado login dentro de uma janela deslizante de 15 minutos. Quanto mais pedidos, mais dificil o desafio se torna (escala exponencial). Apos a janela passar sem novos pedidos, a dificuldade retorna ao nivel base.
| Pedidos na janela | Tempo aproximado de resolucao |
|---|---|
| 1 | menos de 1 segundo |
| 5 | ~4 segundos |
| 10 | ~78 segundos |
| 13+ | excede o TTL do challenge (bloqueio efetivo) |
Expiracao do challenge
Cada challenge e valido por 5 minutos. Se o cliente nao enviar a solucao dentro dessa janela, o challenge expira e um novo deve ser solicitado.
Exemplo (JavaScript)
async function loginWithPoW(baseUrl, login, password) {
// 1. Solicitar um desafio
const challengeRes = await fetch(`${baseUrl}/api/connect/pow/challenge`, {
method: 'POST',
headers: { 'Content-Type': 'application/json' },
body: JSON.stringify({ login })
});
const { challenge, target } = await challengeRes.json();
// 2. Resolver: encontrar nonce onde SHA-256(challenge + nonce) <= target
let nonce = 0;
const encoder = new TextEncoder();
while (true) {
const data = encoder.encode(challenge + nonce.toString());
const buf = await crypto.subtle.digest('SHA-256', data);
const hex = [...new Uint8Array(buf)]
.map(b => b.toString(16).padStart(2, '0')).join('');
if (hex <= target) break;
nonce++;
}
// 3. Autenticar com a prova resolvida
const authRes = await fetch(`${baseUrl}/api/connect/auth`, {
method: 'POST',
headers: { 'Content-Type': 'application/json' },
body: JSON.stringify({ login, password, challenge, nonce: nonce.toString() })
});
return authRes.json(); // { personId, type, dateTime }
}
Para aplicacoes no browser, execute o passo 2 dentro de um Web Worker para nao bloquear a thread principal da interface.
Integracao
Os campos de PoW (challenge, nonce) sao atualmente opcionais no endpoint Auth. Clientes que nao os enviam ignoram a verificacao PoW. O painel admin Guper e a pagina de autorizacao OAuth ja incluem PoW em seus fluxos de login.
Esses campos se tornarao obrigatorios em uma versao futura. Todos os clientes que chamam o endpoint Auth devem integrar o fluxo de Proof of Work o mais breve possivel.
Modo Público
Um pequeno conjunto de endpoints suporta o Modo Público — eles aceitam a mesma requisição sem o header x-guper-authorization. No modo Público a resposta não inclui dados do cliente nem token de confirmação; apenas os valores que seriam aplicados são retornados.
Por exemplo, a variante Pública de Acúmulo por pedido permite simular o cashback que um pedido geraria, sem registrar nada.
Segundo fator por PIN
Endpoints envolvendo resgates de alto valor (como o checkout do loyalty) podem exigir uma etapa extra de PIN:
- Gerar PIN — envia um PIN numérico ao cliente (SMS / email).
- Validar PIN — confirma o código que o cliente digitou no POS.
Erros
| Status | Significado |
|---|---|
401 |
Token inválido ou expirado. Renove e tente de novo. |
403 |
Token é válido, mas não tem permissão para o recurso. |
5xx |
Erro no servidor. Se persistir, contate o suporte. |
Sandbox
Para testes em ambiente não-produção, use as credenciais documentadas no guia Sandbox.
Veja também
- Get token — apikey + apisecret → access token
- Auth — login + senha → personId
- Gerar desafio — desafio Proof of Work para login
- Gerar token de acesso — emite um token de sessão de 30 dias para um usuário
- Guper por IA (MCP) — login por pessoa, para assistentes de IA
- Buscar usuário pelo token — resolve um token de sessão para o usuário dono