Как да свържете персонализиран магазин с easySales през API

Кога Ви е нужно това

easySales разполага с готови конектори за най-разпространените магазин платформи. Ако работите с нещо персонализирано — собствен магазин, разработен вътрешно, или платформа, за която нямаме интеграция — можете да го свържете сами през API.

Това е задача за разработчик. Ще напишете код, който изпраща каталога Ви към easySales и предава поръчките, а easySales ще извиква обратно Вашия магазин, когато нещо се промени. Нищо от описаното тук не изисква инсталиран плъгин.

Как работи връзката

Участват две удостоверения и тяхното объркване е най-честата причина първата интеграция да връща 403.

И двете са необходими при всяко записване. Токенът за достъп доказва кой извиква; токенът на уебсайта казва на кой магазин принадлежат данните.

Стъпка 1 — Добавете уебсайта

Отидете в Интеграции → Уебсайтове, натиснете Свържете уебсайт, попълнете формата, след което изберете плочката API и версията API V2 под нея.

Стъпка 2 — Копирайте токена на уебсайта

Стъпката Настройки в съветника показва токен от 60 знака. Именно него старата статия изобщо не споменава и именно от него се нуждае всяко извикване за запис.

Копирайте го с бутона, вместо да го преписвате, и го съхранявайте като тайна в приложението си. Натиснете Запази, за да създадете уебсайта.

Магазинът вече се показва в Интеграции → Уебсайтове със същия токен върху картата си — оттам ще го намерите отново по-късно.

Стъпка 3 — Създайте OAuth клиент

Отидете в Настройки → API Настройки. Там се намират OAuth удостоверенията.

Натиснете Създаване на нов клиент, наименувайте го според системата, която ще извиква, и задайте Grant тип на Website Grant.

Website Grant е създаден точно за тази задача: разменя токена на уебсайта Ви за токен за достъп, без пренасочване в браузъра и без намеса на потребител. Запазете и копирайте появилите се Идентификационен номер на клиента и Таен ключ.

Стъпка 4 — Получете токен за достъп

POST https://easy-sales.com/oauth/token
Content-Type: application/json

{
  "grant_type":    "website",
  "client_id":     "your-client-id",
  "client_secret": "your-client-secret",
  "website_token": "your-60-character-website-token",
  "scope":         "add-products update-products update-stock add-orders update-orders read-orders"
}

Отговорът е стандартно OAuth тяло:

{
  "token_type":    "Bearer",
  "expires_in":    31536000,
  "access_token":  "eyJ0eXAiOiJKV1Qi...",
  "refresh_token": "def50200a1b2c3..."
}

Изпращайте го като Authorization: Bearer <access_token> при всяко следващо извикване.

Стъпка 5 — Изпратете каталога си

Базовият адрес за всичко по-долу е https://easy-sales.com/api/v2.

Редът има значение. Категориите и характеристиките трябва да съществуват, преди продукт да може да ги посочи, иначе извикването за продукта се отхвърля.

1. POST /categories/save — Вашите категории
2. POST /characteristics/save — Вашите атрибути
3. POST /products/save — Вашите продукти

POST https://easy-sales.com/api/v2/products/save
Authorization: Bearer <access_token>
Content-Type: application/json

{
  "website_token": "your-60-character-website-token",
  "product": {
    "product_website_id": "10231",
    "sku": "TS-BLK-M",
    "name": "Black T-shirt, size M",
    "sale_price": 79.99,
    "full_price": 99.99,
    "stock": 24,
    "type": "simple",
    "tax_rate": 21,
    "url": "https://my-shop.example.com/p/ts-blk-m",
    "images": ["https://my-shop.example.com/img/ts-blk-m.jpg"],
    "categories": ["cat-778"],
    "characteristics": [{ "id": "char-12", "value": "Black" }]
  }
}

Стъпка 6 — Поддържайте наличностите синхронизирани

Наличността е това, което трябва да остане актуално, и е най-евтиното извикване, което може да се прави често. Изпращайте до 100 реда наведнъж:

PATCH https://easy-sales.com/api/v2/stocks/bulk
Authorization: Bearer <access_token>

{
  "website_token": "your-60-character-website-token",
  "data": [
    { "sku": "TS-BLK-M", "stock": 24 },
    { "sku": "TS-BLK-L", "stock": 0 }
  ]
}

Всеки SKU трябва вече да съществува в този уебсайт; непознатите се отхвърлят, а не се създават.

Стъпка 7 — Изпратете поръчките си

POST https://easy-sales.com/api/v2/orders/save
Authorization: Bearer <access_token>

{
  "website_token": "your-60-character-website-token",
  "order": {
    "order_id": "SO-100244",
    "order_date": "2026-09-09 14:31:00",
    "order_total": 179.98,
    "status": "new",
    "payment_mode": "card",
    "shipment_tax": 21,
    "billing_address":  { "country": "RO", "city": "Cluj-Napoca", "street": "Str. Memorandumului 4" },
    "shipping_address": { "country": "RO", "city": "Cluj-Napoca", "street": "Str. Memorandumului 4" },
    "order_products": [
      { "product_website_id": "10231", "sku": "TS-BLK-M", "name": "Black T-shirt, size M",
        "quantity": 2, "price": 79.99, "total": 159.98 }
    ]
  }
}

Изпратете същия order_id отново и поръчката се актуализира, вместо да се дублира, което прави повторните опити безопасни.

Стъпка 8 — Получавайте промените обратно

Магазинът Ви трябва да знае кога една поръчка е фактурирана, има товарителница или сменя статуса си. Вместо да правите периодични заявки, абонирайте webhook:

GET https://easy-sales.com/api/v2/webhooks
Authorization: Bearer <access_token>

POST https://easy-sales.com/api/v2/webhooks/order-updated
Authorization: Bearer <access_token>

{
  "url":    "https://my-shop.example.com/hooks/easysales",
  "secret": "a-shared-secret-of-at-least-24-characters"
}

Абонирате се за едно събитие наведнъж, затова повторете заявката за всяко от order-created, order-updated, awb-created, invoice-created и delivery-status-updated.

Всяко доставяне е подписано, затова проверявайте подписа, преди да се доверите на съдържанието. Отговаряйте бързо — заявката изтича след няколко секунди и се повтаря ограничен брой пъти, затова първо потвърдете и обработвайте след това.

Ограничения

Когато нещо се провали

Всичко, което се проваля от наша страна, попада и в Продукти → Онлайн магазини → Грешки в уебсайта, заедно със заявката и действие за повторен опит, което обикновено е по-бързо от възпроизвеждането на извикването.

Справочник

Пълният справочник на крайните точки, с всяко поле и всеки отговор, е публикуван на https://api.easy-sales.com.