API - Conexión y autorización

Autenticación y URL base

https://alterproduct.com/public-api/v1

Crea las credenciales API en el panel de ajustes de comercio electrónico. Access Token se muestra una sola vez, así que guárdalo inmediatamente en el almacén de secretos de tu backend.

Guarda Access Key y Access Token en tu servidor. Los endpoints autenticados rechazan llamadas desde el navegador que incluyan cabeceras Origin o Referer.

Las credenciales pueden tener ámbitos limitados. Usa GET /auth/check para verificar la tienda activa, las funciones del plan y los ámbitos devueltos para la credencial.

x-alter-access-key: YOUR_API_KEY
x-alter-access-token: YOUR_API_TOKEN

Prueba de conexión

Usa el endpoint de comprobación de autenticación antes de activar la sincronización o las funciones de integración en producción.

GET https://alterproduct.com/public-api/v1/auth/check

Ejemplo de solicitud (fetch)

const response = await fetch('https://alterproduct.com/public-api/v1/auth/check', {
  method: 'GET',
  headers: {
    'x-alter-access-key': process.env.ALTER_ACCESS_KEY,
    'x-alter-access-token': process.env.ALTER_ACCESS_TOKEN
  }
});

const payload = await response.json();

if (!response.ok) {
  throw new Error(payload?.code || payload?.error || `Alter API ${response.status}`);
}

console.log(payload);

Ejemplo de respuesta

{
  "ok": true,
  "message": "success",
  "storefrontId": 12,
  "userOwnerId": 34,
  "credentialId": 56,
  "scopes": ["orders:read", "orders:write", "products:read"],
  "plan": {
    "requiredPlan": "Business",
    "currentPlanName": "Business",
    "eligible": true,
    "runtimeFlags": {
      "viewer": true,
      "configurator": true,
      "customizer": true
    },
    "limits": {
      "activeRuntimeBindingsLimit": 100,
      "monthlyReassignmentLimit": 1000,
      "monthlyEmbedTokenLimit": 50000
    }
  }
}

Los demás ejemplos utilizan la función auxiliar siguiente. Usa fetch estándar y puede ejecutarse en Node.js 18+ o en cualquier entorno de servidor que proporcione fetch.

const ALTER_API_BASE = 'https://alterproduct.com/public-api/v1';

const authHeaders = {
  'x-alter-access-key': process.env.ALTER_ACCESS_KEY,
  'x-alter-access-token': process.env.ALTER_ACCESS_TOKEN
};

async function alterFetch(path, options = {}) {
  const response = await fetch(`${ALTER_API_BASE}${path}`, {
    ...options,
    headers: {
      ...authHeaders,
      ...(options.body ? { 'Content-Type': 'application/json' } : {}),
      ...options.headers
    }
  });

  const payload = await response.json().catch(() => null);

  if (!response.ok) {
    throw new Error(payload?.code || payload?.error || `Alter API ${response.status}`);
  }

  return payload;
}

Errores y límites de solicitudes

La mayoría de los errores de controladores se normalizan como una respuesta code. El middleware de autenticación y los limitadores de solicitudes pueden devolver una respuesta error en su lugar.

// Controller error
{
  "code": "assetCatalog.invalidType"
}

// Auth middleware or rate limit
{
  "error": "Unauthorized"
}

{
  "error": "Too Many Requests"
}