Авторизация в Sailplay API

В данном разделе описываются правила и процедуры получения и безопасного использования первичных идентификаторов и токена для работы c REST API платформы Sailplay.

Процесс авторизации в API состоит из 2 простых шагов:

1. Получите первичные идентификаторы в личном кабинете Sailplay
2. Выполните API запрос для получения токена

---

Основные параметры API авторизации

Параметр	Описание
store_department_id	Уникальный числовой идентификатор Отдела. Используется как в запросе получения токена, так и во всех последующих запросах к API.
store_department_key	Числовой секретный ключ Отдела. Используется только для получения токена в запросе /api/v2/login/.
pin_code	Числовой код, закрепленный за конкретным Сотрудником. Для получения токена в запросе /api/v2/login/ рекомендуется использовать значение сервисной учетной записи сотрудника.
token	40‑символьный hex‑идентификатор возвращаемый методом /api/v2/login/. Подписывает все дальнейшие запросы к API.

---

Получение первичных идентификаторов

1. Получите идентификаторы в личном кабинете Sailplay. Идентификаторы store_department_id и store_department_key расположены в карточке отдела. pin_code можно получить в карточке сотрудника.
2. Получите идентификаторы через менеджера Sailplay. При отсутствии доступа к кабинету запросите идентификаторы у персонального менеджера Sailplay.

❗️ Важно

Не пересылайте идентификаторы, токены или другие чувствительные данные в открытых каналах (чаты, мессенджеры, системы управления задачами). Любая утечка может привести к несанкционированному доступу и финансовым потерям.

---

Пример cURL запроса для получения токена

curl --request POST \
     --url https://sailplay.ru/api/v2/login \
     --header 'Accept: application/json' \
     --header 'Content-Type: application/x-www-form-urlencoded' \
     --data store_department_id=3354 \
     --data store_department_key=450013 \
     --data pin_code=230945

---

Политика обновления токена

• Стандартный TTL. Стандартный настройка жизненного цикла токена работает без ограничения по времени. Однако Sailplay рекомендует автоматизировать обновление токена каждые 24 часа при помощи фоновой задачи.
• Изменение TTL. TTL может быть увеличен или уменьшен по запросу через техническую поддержку Sailplay.
• Принудительное обновление. При получении ответа c ошибкой "status_code": -7 на любой рядовой запрос немедленно инициируйте повторный вызов api/v2/login/ и обновите токен во всех последующих запросах к системе.

Пример ответа на рядовой запрос в случае если token не валидный:

{
	"status": "error",
	"status_code": -7,
	"message": "Authentication token is invalid"
}

Пример ответа на запрос получения token в случае если ключевые параметры переданы корректно:

{
  "status": "ok",
  "token": "db24834db10ed8a58ab8d2ce02be41ab03a86b21"
}

🚧 Рекомендации по безопасному хранению ключей

Ключи и токены ни при каких условиях нельзя фиксировать в исходном коде. Храните их только в переменных окружения либо в специализированных секрет‑хранилищах, следуя общепринятым принципам, изложенным в NIST SP 800‑57 и OWASP ASVS. Если токен оказался скомпрометирован, его можно оперативно заглушить и пересоздать вместе с новыми store_department_key и pin_code. Для этого обратитесь в техническую поддержку Sailplay. Запросите инструкцию по корректной деактивации текущего токена и обновлению ключевых идентификаторов.