Entrar
.md

Autenticación

La mayoría de las APIs de Guper requieren un token de autorización enviado en cada solicitud mediante el header x-guper-authorization. Esta página cubre cómo obtener ese token y cómo usarlo.

Credenciales

Cada cuenta de acceso a la API recibe dos credenciales:

  • API Key (x-guper-apikey) — identificador público de tu cuenta.
  • API Secret (x-guper-apisecret) — valor secreto, trátalo como una contraseña.

El par inicial lo genera el equipo de integración de Guper. Mantén el secret seguro — nunca debe exponerse en el navegador ni subirse a un repositorio.

Generando un token

Intercambia las credenciales por un token de corta duración en el endpoint Get token:

curl -X GET "https://{organization}.myguper.com/api/connect/token" \
  -H "x-guper-apikey: <tu apikey>" \
  -H "x-guper-apisecret: <tu apisecret>"

La respuesta contiene el token y su vencimiento:

{
  "accessToken": "c074cb9bd30d7b431230877facb45e0a06790e93dea6a728cef9fdaf656bf349",
  "expiresIn":   "2023-08-11T15:13:00-03:00",
  "dateTime":    "2023-08-11T09:13:00-03:00"
}

Los tokens son de corta duración. Guárdalos en caché en tu backend hasta que venzan y renuévalos con anticipación — nunca llames al endpoint de auth en cada solicitud.

Autenticando a un usuario

Si tu integración necesita actuar en nombre de un usuario específico (login + contraseña), usa Auth en su lugar. La respuesta trae el personId y type correspondientes, que puedes combinar con Get access token para emitir un token de sesión de 30 días para ese usuario.

Usando el token

Envía el token en el header x-guper-authorization en cada solicitud protegida:

curl -X POST "https://{organization}.myguper.com/api/loyalty/rewardByOrder" \
  -H "x-guper-authorization: <tu token>" \
  -H "Content-Type: application/json" \
  -d '{ ... }'

Puedes verificar a quién pertenece un token con Get user by token.

Inicio de sesión por persona (OAuth 2.1)

Además del camino apiKey/apiSecret de arriba — que identifica una integración — existe un segundo camino, que identifica a una persona: OAuth 2.1 con PKCE, usado por los asistentes de IA.

La diferencia que importa:

apiKey / apiSecret OAuth 2.1
identifica una integración (sistema) una persona
quién la registra el equipo de integración nadie — registro dinámico
permisos de la cuenta de acceso los del perfil de la persona en el panel
revocar cambiar la credencial de todos desactivar a ese usuario

Ambos conviven, y nada cambia para quien ya integra. Usa OAuth cuando el acceso sea de una persona y deba respetar su perfil; sigue con apiKey/apiSecret para integración servidor a servidor.

El flujo completo, los endpoints y lo que tu cliente debe respetar están en Guper por IA (MCP).

Proof of Work (PoW)

Los endpoints de login que aceptan login + password soportan una capa opcional de Proof of Work que mitiga ataques de fuerza bruta y credential stuffing.

Como funciona

Antes de enviar las credenciales, el cliente solicita un desafio al endpoint Generar desafio. El servidor retorna una cadena challenge aleatoria y un target — un umbral hexadecimal de 64 caracteres. El cliente debe encontrar un nonce tal que:

SHA-256(challenge + nonce) <= target

El challenge y nonce resueltos se incluyen entonces en la solicitud Auth junto con login y password.

Anti-paralelismo

Cada nuevo challenge para el mismo login invalida el anterior. Un atacante creando miles de navegadores contra el mismo email descubre que solo el ultimo challenge es valido — los demas intentos fallan en la autenticacion.

Escalada de dificultad

El servidor rastrea cuantos challenges fueron solicitados para un login dado dentro de una ventana deslizante de 15 minutos. Cuantas mas solicitudes, mas dificil se vuelve el desafio (escala exponencial). Despues de que la ventana pasa sin nuevas solicitudes, la dificultad vuelve al nivel base.

Solicitudes en ventana Tiempo aproximado de resolucion
1 menos de 1 segundo
5 ~4 segundos
10 ~78 segundos
13+ excede el TTL del challenge (bloqueo efectivo)

Expiracion del challenge

Cada challenge es valido por 5 minutos. Si el cliente no envia la solucion dentro de esa ventana, el challenge expira y debe solicitarse uno nuevo.

Ejemplo (JavaScript)

async function loginWithPoW(baseUrl, login, password) {
    // 1. Solicitar un 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 donde 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 con la prueba resuelta
    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 aplicaciones en el navegador, ejecute el paso 2 dentro de un Web Worker para no bloquear el hilo principal de la interfaz.

Integracion

Los campos de PoW (challenge, nonce) son actualmente opcionales en el endpoint Auth. Los clientes que no los envian omiten la verificacion PoW. El panel admin de Guper y la pagina de autorizacion OAuth ya incluyen PoW en sus flujos de inicio de sesion.

Estos campos se volveran obligatorios en una version futura. Todos los clientes que llaman al endpoint Auth deben integrar el flujo de Proof of Work lo antes posible.

Modo público

Un pequeño conjunto de endpoints soporta el Modo público — aceptan la misma solicitud sin el header x-guper-authorization. En modo público la respuesta no incluye datos del cliente ni tokens de confirmación; solo se devuelven los valores que se aplicarían.

Por ejemplo, la variante pública de Reward by Order te permite simular el cashback que un pedido generaría, sin registrar nada.

Segundo factor por PIN

Los endpoints que involucran canjes de alto valor (como el checkout de loyalty) pueden requerir un paso adicional con PIN:

  • Generate PIN — envía un PIN numérico al cliente (SMS / email).
  • Validate PIN — confirma el código que el cliente capturó en el POS.

Errores

Status Significado
401 Token inválido o expirado. Renuévalo y reintenta.
403 El token es válido, pero no tiene permiso para el recurso.
5xx Problema del lado del servidor. Si persiste, contacta a soporte.

Sandbox

Para pruebas en un entorno fuera de producción, usa las credenciales documentadas en la guía Sandbox.

Ver también