Conectá cualquier sistema con Espina Comercial.

1. 1 Creá la aplicación

   Registrá el sistema externo y sus URLs de retorno desde tu cuenta.

2. 2 Iniciá OAuth

   Redirigí al usuario al login de Espina usando Authorization Code + PKCE.

3. 3 Obtené el token

   Canjeá el código temporal por un access token y un refresh token.

4. 4 Elegí el negocio

   Consultá /me o /accounts para obtener el accountId.

5. 5 Consumí recursos

   Usá el token Bearer para consultar productos, ventas, reportes o webhooks.

1. Generá PKCE

Creá un code_verifier aleatorio por intento y enviá su hash SHA-256 como code_challenge.

const bytes = crypto.getRandomValues(new Uint8Array(32));
const verifier = base64url(bytes);
const digest = await crypto.subtle.digest(
  "SHA-256",
  new TextEncoder().encode(verifier)
);
const challenge = base64url(new Uint8Array(digest));

function base64url(value) {
  return btoa(String.fromCharCode(...value))
    .replaceAll("+", "-")
    .replaceAll("/", "_")
    .replaceAll("=", "");
}

2. Redirigí al usuario

https://www.espinacomercial.com/oauth2/authorize?
  response_type=code&
  client_id=TU_CLIENT_ID&
  redirect_uri=https%3A%2F%2Ftu-app.com%2Foauth%2Fcallback&
  scope=openid%20profile%20email%20accounts%3Aread%20products%3Aread&
  state=VALOR_ALEATORIO_UNICO&
  code_challenge=TU_CODE_CHALLENGE&
  code_challenge_method=S256&
  prompt=login

3. Canjeá el código

curl --request POST 'https://www.espinacomercial.com/oauth2/token' \
  --user 'TU_CLIENT_ID:TU_CLIENT_SECRET' \
  --header 'Content-Type: application/x-www-form-urlencoded' \
  --data-urlencode 'grant_type=authorization_code' \
  --data-urlencode 'code=CODIGO_RECIBIDO' \
  --data-urlencode 'redirect_uri=https://tu-app.com/oauth/callback' \
  --data-urlencode 'code_verifier=TU_CODE_VERIFIER'

curl --request POST 'https://www.espinacomercial.com/oauth2/token' \
  --header 'Content-Type: application/x-www-form-urlencoded' \
  --data-urlencode 'grant_type=authorization_code' \
  --data-urlencode 'client_id=TU_CLIENT_ID' \
  --data-urlencode 'code=CODIGO_RECIBIDO' \
  --data-urlencode 'redirect_uri=https://tu-app.com/oauth/callback' \
  --data-urlencode 'code_verifier=TU_CODE_VERIFIER'

Respuesta 200 OK

{
  "access_token": "eyJraWQiOiI...",
  "refresh_token": "pX7w2c...",
  "scope": "openid profile email accounts:read products:read",
  "id_token": "eyJraWQiOiI...",
  "token_type": "Bearer",
  "expires_in": 899
}

4. Renovación y revocación

El access token dura 15 minutos. El refresh token dura hasta 30 días y rota en cada uso: guardá el nuevo y descartá el anterior.

curl --request POST 'https://www.espinacomercial.com/oauth2/token' \
  --user 'TU_CLIENT_ID:TU_CLIENT_SECRET' \
  --header 'Content-Type: application/x-www-form-urlencoded' \
  --data-urlencode 'grant_type=refresh_token' \
  --data-urlencode 'refresh_token=TU_REFRESH_TOKEN'

Para revocar un token, enviá el mismo formato a POST /oauth2/revoke con el parámetro token.

curl 'https://www.espinacomercial.com/api/v1/me' \
  --header 'Accept: application/json' \
  --header 'Authorization: Bearer TU_ACCESS_TOKEN'

const response = await fetch('https://www.espinacomercial.com/api/v1/me', {
  headers: {
    Accept: 'application/json',
    Authorization: 'Bearer ' + accessToken
  }
});

if (!response.ok) throw await response.json();
const user = await response.json();

import requests

response = requests.get(
    'https://www.espinacomercial.com/api/v1/me',
    headers={
        'Accept': 'application/json',
        'Authorization': f'Bearer {access_token}',
    },
    timeout=15,
)
response.raise_for_status()
user = response.json()

Respuesta 200 OK

{
  "id": 42,
  "name": "Gabriel Espina",
  "email": "gabriel@example.com",
  "pictureUrl": "https://...",
  "accounts": [
    {
      "id": 17,
      "name": "Kiosco Jardín 2",
      "role": "OWNER",
      "plan": "PRO",
      "subscriptionStatus": "ACTIVE",
      "trialEndsAt": null,
      "paidUntil": "2026-08-31",
      "active": true,
      "setupCompleted": true
    }
  ]
}

Un usuario puede administrar uno o varios negocios. Primero consultá GET /api/v1/accounts, elegí uno y colocá su id en las rutas que contienen {accountId}.

Para OpenID Connect también podés solicitar openid profile email.

Formato paginado

{
  "items": [],
  "page": 0,
  "size": 50,
  "totalItems": 134,
  "totalPages": 3,
  "first": true,
  "last": false
}

Headers de entrega

{
  "id": "01J4M6R7...",
  "type": "stock.low",
  "createdAt": "2026-07-29T21:42:00Z",
  "accountId": 17,
  "data": {
    "productId": 982,
    "code": "7790036974286",
    "description": "Agua saborizada naranja 500 ml",
    "currentStock": 4,
    "minimumStock": 6
  }
}

La cadena firmada es timestamp + "." + rawBody. Usá el cuerpo sin parsear y una comparación de tiempo constante.

import crypto from "node:crypto";

export function verifyEspinaWebhook(rawBody, headers, secret) {
  const timestamp = headers["x-espina-timestamp"];
  const received = headers["x-espina-signature"];
  const age = Math.abs(Date.now() / 1000 - Number(timestamp));

  if (!timestamp || !received || age > 300) return false;

  const expected = "v1=" + crypto
    .createHmac("sha256", secret)
    .update(`${timestamp}.${rawBody}`)
    .digest("hex");

  return expected.length === received.length &&
    crypto.timingSafeEqual(
      Buffer.from(expected),
      Buffer.from(received)
    );
}

• Respondé cualquier estado 2xx después de guardar el evento.
• Procesá tareas lentas en segundo plano.
• Deduplicá por X-Espina-Event-Id; un evento puede entregarse más de una vez.
• Los fallos se reintentan a 1 minuto, 5 minutos, 30 minutos, 2 horas y 12 horas.
• Después quedan en DEAD y pueden reencolarse con el endpoint de replay.