Перейти к содержанию

Приложения

В этой статье описаны OAuth-приложения для входа покупателей на витрину, каналы продаж и действия приложения в бэк-офисе.

Задачи по заказам описаны в заказах и клиентах. Выгрузки товаров — в выгрузках. Токен канала «Диалогов» — в диалогах.

Ключ доступа из раздела «Разработчикам» действует в одном магазине. Приложение, установленное из каталога, обращается к тем же адресам с паролем, выданным для этого магазина.

OAuth-записи принадлежат паролю приложения, с которым созданы. Другой ключ того же магазина не видит эти записи и получает пустой список. При этом имя OAuth-провайдера должно быть уникальным для всего магазина.

Права

При обращении по ключу доступа API проверяет, разрешён ли ему соответствующий раздел настроек:

Ресурс Раздел ключа
/admin/o_auth_apps настройки магазина
/admin/application_actions настройки магазина

Ключ без нужного раздела отвечает 403.

GET/admin/o_auth_apps.json
GET /admin/o_auth_apps.json
Authorization: Basic API_KEY:API_PASSWORD
Accept: application/json

Ответ · 403

{
  "status": "error",
  "message": "Недостаточно прав для операции"
}

Для опубликованного приложения право на каждое действие выдаётся отдельно. Если право не выдано, API возвращает 403.

Для приложения в режиме разработки первый вызов действия разрешается и сохраняется как выданное право. Последующие вызовы выполняются с этим правом.

OAuth-приложения

Ресурс хранит client_id и client_secret, которые используются для входа покупателя на витрину через OAuth-провайдера. Установка самого приложения и токены автологина описаны в статье «Как интегрироваться с InSales».

GET /admin/o_auth_apps.json возвращает массив записей этого пароля. Пустой список — []. Поля записи: id, client_id, client_secret, provider, issuer, enabled.

Для встроенных провайдеров используйте provider: yandex, vkontakte, google, mailru или wbid. Поле issuer для них пустое. Любое другое имя задаёт собственного провайдера, для которого issuer обязателен. Переданное значение enabled не меняет запись: в ответе поле остаётся true.

Покупатель открывает /auth/yandex, /auth/vkontakte, /auth/google или /auth/mailru — магазин переходит на страницу провайдера.

Создание

Передайте данные в объекте o_auth_app или на верхнем уровне JSON. Если объект o_auth_app пуст, API вернёт 422 и {"message":"param is missing or the value is empty or invalid: o_auth_app"}.

POST/admin/o_auth_apps.json
Параметр Описание
provider_handle обязательный
строка		 Имя провайдера. Для готовых имён issuer не нужен.
client_id обязательный
строка		 Идентификатор приложения у провайдера.
client_secret обязательный
строка		 Секрет приложения у провайдера.
issuer необязательный
строка		 Адрес своего провайдера. Для готового имени остаётся null. 
POST /admin/o_auth_apps.json
Authorization: Basic API_KEY:API_PASSWORD
Accept: application/json
Content-Type: application/json

{
  "o_auth_app": {
    "provider_handle": "yandex",
    "client_id": "docs-ya-id",
    "client_secret": "docs-ya-secret"
  }
}

Ответ · 201

{
  "client_id": "docs-ya-id",
  "client_secret": "docs-ya-secret",
  "provider": "yandex",
  "issuer": null,
  "id": 1,
  "enabled": true
}

Повтор того же provider в магазине, в том числе другим ключом, отвечает 422. Первый ключ при этом не видит чужую запись: GET по её id отвечает 404, тело — HTML-страница.

POST/admin/o_auth_apps.json
Параметр Описание
provider_handle обязательный
строка		 Имя, которое уже сохранено в магазине.
client_id обязательный
строка		 Идентификатор приложения у провайдера.
client_secret обязательный
строка		 Секрет приложения у провайдера. 
POST /admin/o_auth_apps.json
Authorization: Basic API_KEY:API_PASSWORD
Accept: application/json
Content-Type: application/json

{
  "o_auth_app": {
    "provider_handle": "yandex",
    "client_id": "docs-ya-id",
    "client_secret": "docs-ya-secret"
  }
}

Ответ · 422

{
  "provider": [
    "уже существует"
  ]
}

Свой провайдер без issuer отвечает 422.

POST/admin/o_auth_apps.json
Параметр Описание
provider_handle обязательный
строка		 Имя своего провайдера.
client_id обязательный
строка		 Идентификатор приложения у провайдера.
client_secret обязательный
строка		 Секрет приложения у провайдера. 
POST /admin/o_auth_apps.json
Authorization: Basic API_KEY:API_PASSWORD
Accept: application/json
Content-Type: application/json

{
  "o_auth_app": {
    "provider_handle": "my_oidc",
    "client_id": "oidc-id",
    "client_secret": "oidc-secret"
  }
}

Ответ · 422

{
  "issuer": [
    "Не заполнены обязательные поля"
  ]
}

С issuer свой провайдер создаётся. Ответ 201, provider равен переданному имени.

POST/admin/o_auth_apps.json
Параметр Описание
provider_handle обязательный
строка		 Имя своего провайдера.
client_id обязательный
строка		 Идентификатор приложения у провайдера.
client_secret обязательный
строка		 Секрет приложения у провайдера.
issuer обязательный
строка		 Адрес своего провайдера. 
POST /admin/o_auth_apps.json
Authorization: Basic API_KEY:API_PASSWORD
Accept: application/json
Content-Type: application/json

{
  "o_auth_app": {
    "provider_handle": "my_oidc",
    "client_id": "oidc-id",
    "client_secret": "oidc-secret",
    "issuer": "https://issuer.example/"
  }
}

Ответ · 201

{
  "client_id": "oidc-id",
  "client_secret": "oidc-secret",
  "provider": "my_oidc",
  "issuer": "https://issuer.example/",
  "id": 4,
  "enabled": true
}

PUT и PATCH /admin/o_auth_apps/ID.json меняют client_id, client_secret и issuer и отвечают 200 тем же набором полей. issuer можно записать и у готового провайдера. DELETE отвечает 200, тело {"status":"ok"}. Удаление пароля приложения удаляет его OAuth-записи.

Каналы продаж

GET /admin/sales_channels.json возвращает каналы этого приложения. Каналы других приложений и каналы маркетплейсов магазина в список не входят. До первого создания список приложения пустой: [].

POST /admin/sales_channels.json создаёт канал по title и отвечает 201. В ответе application_id — приложение ключа, goods_setting_type и goods_setting_id пустые, auto_export_products равен disabled. Изменения канала методом PUT нет: такой запрос отвечает 404.

POST/admin/sales_channels.json
Параметр Описание
sales_channel[title] обязательный
строка		 Название канала этого приложения. 
POST /admin/sales_channels.json
Authorization: Basic API_KEY:API_PASSWORD
Accept: application/json
Content-Type: application/json

{
  "sales_channel": {
    "title": "docs-api Канал"
  }
}

Ответ · 201

{
  "id": 1,
  "title": "docs-api Канал",
  "state": null,
  "messages": [],
  "account_id": 233686,
  "goods_setting_type": null,
  "goods_setting_id": null,
  "application_id": 12,
  "additional_fields": {},
  "auto_export_products": "disabled"
}

DELETE /admin/sales_channels/:id.json отвечает {"status":"ok"}. Следующий список — [].

Действия приложения

Действие приложения добавляет кнопку в раздел бэк-офиса, заданный полем entity. При вызове действия магазин отправляет POST-запрос на url приложения. Тело запроса — JSON-массив выбранных объектов.

Читать и менять действия можно, если у приложения есть право на настройки магазина.

Список GET /admin/application_actions.json содержит действия текущего приложения. Действия других приложений в него не входят. Пустой список — [].

Поле entity принимает order, product, client, discount_code, file, page, article или collection_filter. Приложению нужно право на чтение выбранного типа объектов. Поле handle должно быть уникальным в пределах приложения.

POST/admin/application_actions.json
Параметр Описание
application_action[title] обязательный
строка		 Подпись кнопки.
application_action[handle] обязательный
строка		 Код действия. Уникален у этого приложения.
application_action[url] обязательный
строка		 Адрес POST. Схема http или https.
application_action[entity] обязательный
строка		 Раздел кнопки: order, product, client, discount_code, file, page, article, collection_filter. 
POST /admin/application_actions.json
Authorization: Basic API_KEY:API_PASSWORD
Accept: application/json
Content-Type: application/json

{
  "application_action": {
    "title": "docs-api печать",
    "handle": "docs_api_print",
    "url": "https://example.com/actions",
    "entity": "order"
  }
}

Ответ · 201

{
  "id": 1,
  "title": "docs-api печать",
  "url": "https://example.com/actions",
  "handle": "docs_api_print",
  "entity": "order"
}

GET /admin/application_actions/1.json возвращает тот же объект.

Повтор того же handle отвечает 422, тело {"handle":["уже существует"]}. entity вне списка — 422, тело {"entity":["имеет непредусмотренное значение"]}. Адрес без схемы http или https — 422, тело {"url":["укажите валидный url"]}.

PUT и PATCH меняют переданные поля и возвращают объект. entity можно сменить.

PUT/admin/application_actions/1.json
Параметр Описание
id обязательный
число		 id действия в пути.
application_action[title] необязательный
строка		 Новая подпись кнопки.
application_action[entity] необязательный
строка		 Новый раздел кнопки. 
PUT /admin/application_actions/1.json
Authorization: Basic API_KEY:API_PASSWORD
Accept: application/json
Content-Type: application/json

{
  "application_action": {
    "title": "docs-api печать заказа",
    "entity": "client"
  }
}

Ответ · 200

{
  "id": 1,
  "title": "docs-api печать заказа",
  "url": "https://example.com/actions",
  "handle": "docs_api_print",
  "entity": "client"
}

DELETE /admin/application_actions/1.json отвечает 200. Тело пустое.