API - Conectare și autorizare

Autentificare și URL de bază

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

Creează credențiale API în panoul Setări e-commerce. Access Token este afișat o singură dată, deci salvează-l imediat în stocarea secretelor din backend.

Păstrează Access Key și Access Token pe server. Endpointurile autentificate resping apelurile provenite din browser care includ antetele Origin sau Referer.

Credențialele pot avea domenii de acces limitate. Folosește GET /auth/check pentru a verifica magazinul activ, funcționalitățile planului și domeniile de acces returnate pentru setul de credențiale.

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

Test de conexiune

Folosește endpointul de verificare a autentificării înainte de a activa sincronizarea sau încorporarea într-o integrare în producție.

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

Exemplu de solicitare (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);

Exemplu de răspuns

{
  "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
    }
  }
}

Funcția auxiliară de mai jos este folosită de celelalte exemple. Folosește fetch simplu și poate rula în Node.js 18+ sau în orice mediu de execuție de server care oferă 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;
}

Erori și limite de solicitări

Majoritatea erorilor de controler sunt normalizate într-un răspuns code. Middleware-ul de autentificare și limitatoarele de solicitări pot returna în schimb un răspuns error.

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

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

{
  "error": "Too Many Requests"
}