TunoCommerce

Autenticación

Los tres métodos de autenticación de la API de TunoCommerce

La API de TunoCommerce usa tres métodos de autenticación distintos según el tipo de consumidor:

MétodoHeaderPara quién
API Token (pk_*)Authorization: Bearer pk_...Integraciones servidor-a-servidor, ERPs, dashboards propios
JWT de compradorX-Buyer-Token: eyJ...Portal de comprador, apps móviles, frontends B2B
Token de storefront (sf_*)Authorization: Bearer sf_... + X-Storefront-SlugFrontends de tienda pública, catálogos headless

Método 1: API Token (pk_*)

Los API tokens son credenciales de larga duración para integraciones server-side. Son la opción más simple cuando tu consumidor es un sistema backend, no un usuario final.

Crear un token

Desde el dashboard administrativo:

  1. Ve a Mi Empresa → API Tokens
  2. Haz clic en Crear token
  3. Copia el token — solo se muestra una vez

Usar el token

Incluye el token en el header Authorization en cada solicitud:

curl https://tu-instancia.com/api/v1/products \
  -H "Authorization: Bearer pk_a1b2c3d4..."

Permisos

Los tokens tienen acceso completo al API v1 de su empresa y sus subsidiarias.

Rotación de tokens

Crea el nuevo token antes de eliminar el anterior para evitar interrupciones:

# 1. Crear token nuevo
curl -X POST https://tu-instancia.com/api/v1/api-tokens \
  -H "Authorization: Bearer pk_token_viejo..." \
  -H "Content-Type: application/json" \
  -d '{"name": "Integración ERP v2"}'

# 2. Actualizar tu sistema con el nuevo token
# 3. Eliminar el token anterior
curl -X DELETE https://tu-instancia.com/api/v1/api-tokens/{tokenId} \
  -H "Authorization: Bearer pk_token_nuevo..."

Método 2: JWT de comprador

Los compradores (customers) se autentican con un flujo que usa cifrado asimétrico para proteger las credenciales en tránsito. El resultado es un access token JWT (15 minutos) y un refresh token (30 días).

Paso 1: Obtener el challenge

El challenge genera un par de claves RSA-2048 temporal para cifrar la contraseña:

curl -X POST https://tu-instancia.com/api/v1/customers/auth/challenge \
  -H "X-Storefront-Slug: acme-b2c" \
  -H "Authorization: Bearer sf_dev_seed_acme_b2c_token" \
  -H "Content-Type: application/json" \
  -d '{"email": "cmendoza@textilesnorte.mx"}'

Respuesta:

{
  "data": {
    "challengeId": "uuid-...",
    "publicKey": "-----BEGIN PUBLIC KEY-----\nMIIBI...\n-----END PUBLIC KEY-----",
    "expiresAt": "2024-01-15T10:32:00Z"
  }
}

El challenge es válido por 2 minutos.

Paso 2: Cifrar la contraseña

Cifra la contraseña con la clave pública usando RSA-OAEP con SHA-256:

// Node.js
import { publicEncrypt, constants } from 'crypto';

const encrypted = publicEncrypt(
  {
    key: publicKey,
    padding: constants.RSA_PKCS1_OAEP_PADDING,
    oaepHash: 'sha256',
  },
  Buffer.from(password)
).toString('base64');

Paso 3: Autenticarse

curl -X POST https://tu-instancia.com/api/v1/customers/auth/signin \
  -H "X-Storefront-Slug: acme-b2c" \
  -H "Authorization: Bearer sf_dev_seed_acme_b2c_token" \
  -H "Content-Type: application/json" \
  -d '{
    "email": "cmendoza@textilesnorte.mx",
    "encryptedPassword": "base64...",
    "challengeId": "uuid-..."
  }'

Respuesta exitosa:

{
  "data": {
    "accessToken": "eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9...",
    "refreshToken": "64_hex_chars...",
    "expiresIn": 900,
    "customer": {
      "id": "clx...",
      "email": "cmendoza@textilesnorte.mx",
      "firstName": "Carlos",
      "lastName": "Mendoza"
    }
  }
}

Usar el JWT en solicitudes de comprador

Los endpoints del portal de comprador (/api/v1/buyer/*) requieren tres headers:

curl https://tu-instancia.com/api/v1/buyer/quotes \
  -H "X-Storefront-Slug: acme-b2c" \
  -H "Authorization: Bearer sf_dev_seed_acme_b2c_token" \
  -H "X-Buyer-Token: eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9..."

Paso 4: Renovar el access token

El access token expira a los 15 minutos. Usa el refresh token para obtener uno nuevo:

curl -X POST https://tu-instancia.com/api/v1/customers/auth/refresh \
  -H "X-Storefront-Slug: acme-b2c" \
  -H "Authorization: Bearer sf_dev_seed_acme_b2c_token" \
  -H "Content-Type: application/json" \
  -d '{"refreshToken": "64_hex_chars..."}'

El refresh token anterior se invalida automáticamente (rotación). La respuesta incluye un nuevo par accessToken + refreshToken.

Paso 5: Cerrar sesión

curl -X POST https://tu-instancia.com/api/v1/customers/auth/logout \
  -H "X-Storefront-Slug: acme-b2c" \
  -H "Authorization: Bearer sf_dev_seed_acme_b2c_token" \
  -H "X-Buyer-Token: eyJ..."

Perfil del comprador autenticado

curl https://tu-instancia.com/api/v1/customers/me \
  -H "X-Storefront-Slug: acme-b2c" \
  -H "Authorization: Bearer sf_dev_seed_acme_b2c_token" \
  -H "X-Buyer-Token: eyJ..."

Método 3: Token de storefront (sf_*)

Los tokens de storefront autorizan acceso a la API pública de catálogo. Son de solo lectura y están limitados a los datos visibles para la empresa del storefront.

Crear un token de storefront

Desde el dashboard administrativo:

  1. Ve a Tiendas → selecciona la tienda
  2. Ve a la pestaña Tokens
  3. Crea un nuevo token con un nombre descriptivo

Usar el token

Todos los endpoints del storefront requieren dos headers:

curl https://tu-instancia.com/api/v1/storefront/catalog/products \
  -H "X-Storefront-Slug: acme-b2c" \
  -H "Authorization: Bearer sf_dev_seed_acme_b2c_token"

El slug debe corresponder exactamente a la tienda del token. Si no coinciden, recibirás 401 STOREFRONT_UNAUTHORIZED.

Credenciales para desarrollo local

Con pnpm db:seed ejecutado, estos tokens están disponibles de inmediato:

TipoTokenUso
API Tokenpk_dev_seed_catalog_tokenAdmin API v1 completa
Storefrontsf_dev_seed_acme_b2c_tokenTienda acme-b2c
Storefrontsf_dev_seed_acme_wholesale_tokenTienda acme-wholesale

Compradores disponibles (contraseña: Customer123$):

EmailNombre
cmendoza@textilesnorte.mxCarlos Mendoza
lgonzalez@unicorp.mxLaura González
dmorales@safetek.com.mxDiana Morales

Inicio Rápido

Primeros pasos para integrar con la API de TunoCommerce en minutos

Catálogo

Cómo listar productos, navegar categorías, filtrar por marca y gestionar inventario

On this page

Método 1: API Token (pk_*)Crear un tokenUsar el tokenPermisosRotación de tokensMétodo 2: JWT de compradorPaso 1: Obtener el challengePaso 2: Cifrar la contraseñaPaso 3: AutenticarseUsar el JWT en solicitudes de compradorPaso 4: Renovar el access tokenPaso 5: Cerrar sesiónPerfil del comprador autenticadoMétodo 3: Token de storefront (sf_*)Crear un token de storefrontUsar el tokenCredenciales para desarrollo local