Что умеет 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. Сообщите этот код владельцу магазина вместе со временем запроса. По нему владелец найдёт запрос в журнале и увидит, что вы прислали и что ответил магазин. Как устроен журнал, описано на странице «Журнал запросов».