API - Підключення й авторизація

Автентифікація та базова URL-адреса

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

Створіть облікові дані API на панелі налаштувань електронної комерції. Access Token показується лише раз, тому одразу збережіть його в серверному сховищі секретів.

Зберігайте Access Key і Access Token на сервері. Кінцеві точки з автентифікацією відхиляють браузерні виклики із заголовками Origin або Referer.

Права облікових даних можна обмежувати. Використовуйте GET /auth/check, щоб перевірити активний магазин, можливості тарифу та права, повернені для цих облікових даних.

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

Перевірка підключення

Використайте кінцеву точку перевірки автентифікації, перш ніж увімкнути синхронізацію чи вбудовування в робочій інтеграції.

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

Приклад запиту (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);

Приклад відповіді

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

Наведена нижче допоміжна функція використовується в інших прикладах. Це звичайний fetch, який може працювати в Node.js 18+ або будь-якому серверному середовищі з підтримкою 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;
}

Помилки й обмеження частоти запитів

Більшість помилок контролерів нормалізуються у відповідь із code. Проміжні обробники автентифікації та обмеження частоти можуть натомість повертати відповідь із error.

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

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

{
  "error": "Too Many Requests"
}