Що вміє API магазину

API магазину потрібен тим, хто підключається до магазину ззовні. Дропшипер забирає через нього каталог до себе на сайт і передає замовлення своїх покупців. Партнер звіряє в себе статуси та способи доставки. Розробник створює для магазину окремий сайт чи застосунок і бере дані звідси.

Через API дані можна отримувати, а змінювати в магазині нічого не можна: ні товари, ні ціни, ні залишки, ні замовлення. Єдине, що API приймає, — нові замовлення, наприклад замовлення, яке дропшипер оформив у себе на сайті й передає магазину.

Що доступно зараз#

Зараз API віддає відомості про ключ, налаштування й довідники магазину, каталог, ціни, залишки й замовлення. Нові замовлення він теж приймає:

Довідники магазину описано в довіднику адрес. Каталогу присвячено окремі сторінки: видимість і синхронізація, довідники каталогу, товари та артикули, ціни і залишки. Як магазин приймає замовлення, описано на сторінках «Замовлення партнера» і «Замовлення: адреси й поля».

Магазин може й сам повідомляти партнера, що змінився статус його замовлення, менеджер змінив замовлення або змінилися ціни й залишки. Тоді партнерові не потрібно постійно питати про це. Вмикає такі повідомлення власник у формі ключа, а як їх приймати, описано на сторінці «Повідомлення партнерові (вебхуки)».

Ключ завжди видається конкретному контакту магазину, дропшиперу чи партнеру. За цим контактом магазин рахує ціни для ключа з урахуванням категорії покупця та персональних цін і на нього ж записує замовлення, що надійшли через API.

Що буде далі#

У формі ключа вже можна позначити право «Бачити покупців». Адрес під нього поки немає, вони з’являться в наступних випусках магазину. Запит до розділу, якого ще немає, отримує відповідь 404.

Як влаштовано API#

• Адреса: https://<домен магазину>/api/v1. Версія входить в адресу, зараз вона одна, v1.
• Відповіді — JSON у кодуванні UTF-8. Кирилиця та скісна риска в адресах приходять як є, без екранування.
• Вхід — за ключем у заголовку Authorization: Bearer <ключ>. Сеанс співробітника в панелі API не відкриває. Навіть із того самого браузера без ключа відповідь буде 401.
• Права ключа обирає власник магазину. Ключ бачить лише ті розділи, які йому позначили.
• У кожного ключа свій ліміт запитів за хвилину, типово 120.
• Помилки приходять в одному форматі application/problem+json із чесним HTTP-статусом і кодом помилки. Подробиці на сторінці «Помилки та їхні коди».
• Кожен запит записується в журнал, який власник бачить у панелі. Кожна відповідь має заголовок X-Request-Id: за цим кодом запит знаходиться в журналі.

Опис для Postman і Swagger#

Кожен магазин віддає опис свого API у форматі OpenAPI 3.1 за адресою https://<домен магазину>/api/v1/openapi.json. Ключ для цього не потрібен. В описі перелічено всі адреси з параметрами, поля відповідей, коди помилок і повідомлення, які магазин надсилає партнерові. Адресу для запитів у ньому вже вказано, і це адреса того магазину, звідки ви його взяли.

Щоб отримати готові запити в Postman, натисніть Import і вставте адресу опису. Postman збере колекцію із запитом на кожну адресу API. Тип Bearer Token на вкладці Authorization у колекції він обере сам, вам залишиться вставити туди ключ. Цю саму адресу відкривають Swagger Editor, Insomnia та інші програми, які розуміють OpenAPI. За описом можна й згенерувати готовий клієнт для своєї мови програмування.

Пояснення в описі написано англійською, а подробиці з прикладами українською та російською є на сторінках цього довідника. Посилання на опис власник магазину знайде у формі ключа, у блоці «Як підключити».

Швидкий старт#

1. Отримайте ключ#

Ключ видає власник магазину або співробітник із правом «Видавати ключі API». У панелі він відкриває «Налаштування платформи», у групі «Платформа» обирає «API магазину» й натискає плюс біля «Ключі доступу». Як заповнити форму, описано на сторінці «Ключі доступу та права».

Після натискання «Видати ключ» магазин один раз показує ключ повністю. Він має такий вигляд:

12|ctx_Hq4bR7mPz0LwX3sYt8VnK2cJd5aEf9gUiO1hBqWe6a1c94f7

Ключем вважається весь цей рядок разом із числом і вертикальною рискою на початку. Зберігайте його як пароль. Магазин зберігає лише відбиток ключа й удруге його не покаже.

2. Перевірте ключ#

Першим запитом варто викликати /me. Цій адресі не потрібні права, вона відповідає будь-якому чинному ключу й показує, що ключ уміє.

curl https://shop.example.ua/api/v1/me \
  -H "Authorization: Bearer 12|ctx_Hq4bR7mPz0LwX3sYt8VnK2cJd5aEf9gUiO1hBqWe6a1c94f7" \
  -H "Accept: application/json"

Відповідь:

{
    "data": {
        "id": 3,
        "name": "Сайт партнера",
        "kind": "integration",
        "contact": { "id": 418, "name": "ФОП Коваленко" },
        "scopes": ["shop:read", "orders:create"],
        "rate_limit_per_minute": 120,
        "expires_at": null,
        "settings_changed_at": null,
        "api_version": "1"
    }
}

Якщо прийшла відповідь 401, ключ не передано, скопійовано не повністю, відкликано, термін його дії минув, ключ замінено новим або видалено. Ключ видаляється й тоді, коли в магазині видаляють контакт, якому його видали. Поле code у відповіді підкаже, що саме сталося.

3. Отримайте дані магазину#

curl https://shop.example.ua/api/v1/shop \
  -H "Authorization: Bearer <ключ>"

Для цієї адреси ключ повинен мати право «Бачити налаштування й довідники магазину» (shop:read). Новий ключ отримує його позначеним одразу.

Якщо щось не працює#

У кожній відповіді про помилку є поле request_id, такий самий код приходить у заголовку X-Request-Id. Повідомте цей код власникові магазину разом із часом запиту. За ним власник знайде запит у журналі й побачить, що ви надіслали і що відповів магазин. Як влаштовано журнал, описано на сторінці «Журнал запитів».