Entrar
.md

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