Доступ к API

Перед первым защищённым вызовом определите стенд, учётную запись и организацию, от имени которой нужно выполнить задачу.

Выбрать стендВыбрать стенд

Проверяйте токен, права и идентификаторы объектов на выбранном стенде. Перед операцией записи на рабочем стенде согласуйте с пользователем действие и объект.

Получить токенПолучить токен

Пользователь открывает ссылку Яндекс OAuth для выбранного стенда и входит под нужным Яндекс ID. После входа откроется страница с токеном.

• Получить токен тестового стенда
• Получить токен рабочего стенда

Эти ссылки приведены в инструкции по получению токена для разработчиков. Для ручной проверки вызовов в браузере используйте авторизацию через OpenAPI.

Настроить авторизациюНастроить авторизацию

1. Проверьте, есть ли у клиента настроенный источник токена для выбранного стенда. Если токена ещё нет, направьте пользователя к получению токена.
2. Если способ передачи токена клиенту ещё не настроен, согласуйте его с пользователем. Достаточно узнать имя секрета и способ его подключения. Значение токена пользователь вводит через интерфейс хранилища или среды запуска.
3. Клиент добавляет заголовок Authorization: Bearer <токен> к защищённым запросам на выбранный стенд. Для общедоступного метода используйте вызов без токена, если это указано в карточке.

Проверить учётную запись и рольПроверить учётную запись и роль

С одной учётной записью можно работать от имени нескольких организаций. У пользователя могут быть профили заказчика в одних организациях и профили исполнителя в других. Один профиль может иметь оба признака роли.

Методы в первых двух шагах возвращают JSON. Если клиент передал байты, разберите ответ перед чтением data.

1. Вызовите метод получения идентификаторов текущего пользователя без тела и параметров. Ответ 200 OK подтверждает аутентификацию. Если клиенту известны ожидаемые идентификаторы учётной записи, сравните их с ответом в клиенте. При несовпадении остановитесь.
2. Вызовите метод получения профилей сотрудников на том же стенде и с той же учётной записью. В data.empls найдите профили, у которых isOn: true и установлен признак нужной роли. Заказчику (forwarder) соответствует isForwarder: true, исполнителю (executor) — isExecutor: true.
3. Если пользователь указал название организации, сопоставьте его с orgName подходящих профилей в клиенте. Если указан идентификатор, сверьте его с organizationID. Если выбор неоднозначен, уточните организацию у пользователя. Для дальнейших вызовов используйте organizationID выбранного профиля. Порядок профилей в ответе не задаёт организацию по умолчанию.
4. Сообщите, прошла ли аутентификация и найден ли активный профиль нужной роли с учётом выбранной организации. Если подходящего профиля нет, остановитесь и предложите проверить в интерфейсе сервиса Яндекс Магистрали доступ учётной записи к нужной организации и её роль. Права на бизнес-операцию проверяйте отдельно по условиям доступа в её карточке.

Если доступ отклонёнЕсли доступ отклонён

• При 401 остановите сценарий. Проверьте настройку заголовка авторизации, срок действия токена и соответствие стенду.
• При 403 остановите сценарий. Проверьте доступ учётной записи к выбранному стенду, организации и операции.

Сообщите пользователю стенд, метод и HTTP-статус. Для диагностики достаточно этих сведений и подтверждённых условий доступа. Токен, заголовки и полные ответы держите в клиенте. При проверке профилей соблюдайте правила работы с персональными и чувствительными данными.