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

Приложения и диалоги

Четыре ресурса: OAuth-приложения покупателя, каналы продаж приложения, действия приложения и токен канала «Диалогов».

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

Ключ доступа из раздела «Разработчикам» работает в одном магазине. Установленное приложение из каталога вызывает те же адреса своим паролем магазина. Список OAuth и токены диалогов принадлежат этому паролю: второй ключ того же магазина получает пустой список OAuth. Имя провайдера OAuth при этом одно на весь магазин.

Права

Ключ доступа проверяет раздел настроек.

Ресурс Раздел ключа
/admin/o_auth_apps настройки магазина
/admin/application_actions настройки магазина
POST /admin/dialogs/provider_tokens диалоги, полный доступ

Ключ без нужного раздела отвечает 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": "Недостаточно прав для операции"
}

У опубликованного приложения каждое действие выдаётся отдельно. Пока действие не выдано, ответ тот же 403. Выпуск токена диалогов в кабинете партнёра не выдаётся: опубликованное приложение на POST /admin/dialogs/provider_tokens.json получает 403.

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

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

Ресурс хранит client_id и client_secret входа покупателя на витрине. Установка приложения и три токена автологина описаны в общем описании.

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 или полями на верхнем уровне. Пустой объект {"o_auth_app":{}} отвечает 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"}. Следующий список — [].

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

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

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

Список 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. Тело пустое.

Токен провайдера диалогов

Один метод: POST /admin/dialogs/provider_tokens.json. GET этого адреса отвечает 404. Тело — верхний уровень, поле messenger_type. Обёртка provider_token игнорируется и отвечает тем же телом, что и пустой запрос.

Рабочие значения: sms, telegram, viber, email, vk. sms — канал «Диалогов». Код входа на витрину этим методом не выпускается.

Ответ успеха — 200 и два значения по 128 шестнадцатеричных символов. Повтор для того же messenger_type выпускает новую пару, старая перестаёт подходить к Provider API. Ошибки этого метода тоже приходят с 200 и полем error.

Удаление пароля приложения удаляет его токены. Прежний api_token после этого отвечает 401.

POST/admin/dialogs/provider_tokens.json
Параметр Описание
messenger_type обязательный
строка		 sms, telegram, viber, email или vk. 
POST /admin/dialogs/provider_tokens.json
Authorization: Basic API_KEY:API_PASSWORD
Accept: application/json
Content-Type: application/json

{
  "messenger_type": "telegram"
}

Ответ · 200

{
  "api_token": "…128 шестнадцатеричных символов…",
  "webhook_token": "…128 шестнадцатеричных символов…"
}

Пустой messenger_type и тело без этого поля отвечают 200:

{
  "error": "Please, specify messenger_type to issue a token"
}

Provider API

Хост — https://messengers.insales.ru. Заголовок Authorization равен api_token, без Basic и без Bearer. Чужой токен отвечает 401, тело {"error":"Not authorized"}.

Пока магазин не переключил канал на этого провайдера, active равен false. Вызов, который переключает канал, в Provider API нет.

GET/api/messengers/provider/v1/settings
GET /api/messengers/provider/v1/settings
Host: messengers.insales.ru
Authorization: API_TOKEN
Accept: application/json

Ответ · 200

{
  "send_message_url": null,
  "settings_url": null,
  "active": false
}

POST тех же настроек отвечает 201.

POST/api/messengers/provider/v1/settings
Параметр Описание
send_message_url необязательный
строка		 Адрес, на который магазин шлёт исходящее сообщение.
settings_url необязательный
строка		 Адрес, на который магазин шлёт gateway_token. 
POST /api/messengers/provider/v1/settings
Host: messengers.insales.ru
Authorization: API_TOKEN
Accept: application/json
Content-Type: application/json

{
  "send_message_url": "https://example.com/insales-dialogs",
  "settings_url": "https://example.com/insales-dialogs-settings"
}

Ответ · 201

{
  "send_message_url": "https://example.com/insales-dialogs",
  "settings_url": "https://example.com/insales-dialogs-settings",
  "active": false
}

На send_message_url магазин шлёт POST с Authorization: webhook_token и Content-Type: application/json. Текстовое сообщение:

{
  "to": "chat-id",
  "internal_id": 100,
  "account_id": 233686,
  "body": "текст",
  "type": "text"
}

Файл вместо body и type: text приходит как type: file и files: [{url, name}]. Ответ сервиса — 200 и JSON со status и external_id. Статусы: scheduled, wait_for_capture, complete, error. Другой HTTP-статус и неизвестный status считаются ошибкой. Повторной отправки вебхука нет.

На settings_url тем же заголовком уходит {"gateway_token":"…","account_id":233686}, когда у магазина меняется токен шлюза.

Входящее сообщение клиента провайдер передаёт своим POST /api/messengers/provider/v1/messages. Пока active равен false, ответ 422.

POST/api/messengers/provider/v1/messages
Параметр Описание
from обязательный
строка		 Идентификатор отправителя в канале: телефон, email или другой id.
external_id обязательный
строка		 Идентификатор сообщения у провайдера.
time обязательный
строка		 Время сообщения.
body необязательный
строка		 Текст. Нужен body, files или meta_type. 
POST /api/messengers/provider/v1/messages
Host: messengers.insales.ru
Authorization: API_TOKEN
Accept: application/json
Content-Type: application/json

{
  "from": "+79990000000",
  "external_id": "docs-1",
  "time": "2026-10-21T22:22:00+03:00",
  "body": "Здравствуйте"
}

Ответ · 422

{
  "errors": [
    "Provider was deactivated by user. You can't send messages to user while it's deactivated"
  ]
}

POST /api/messengers/provider/v1/message_status принимает external_id и status: scheduled, complete, wait_for_capture, error. Неизвестное сообщение отвечает 404, тело {}.