NAV
http

Введение

Первое сентября предоставляет доступ к функциям API для интеграции с сайтами (внешними сервисами) и приложениями (далее по тексту сервисы). Через API сервисы могут получить доступ как к общим данным API, так и к ресурсам пользователя.

Запросы к API направляются по протоколу HTTPS с применением REST архитектуры. API возвращает ответы в формате JSON. Для PHP авторизация оформлена в готовую библиотеку.

Авторизация (OAuth)

Для большинства функций доступ к API предоставляется по токену, который выдаётся после прохождения OAuth 2.0 авторизации. Токен имеет срок действия. После истечении срока действия токена можно получить новый при наличии токена восстановления или после прохождения повторной авторизации.

Регистрация

Для работы с API сервису необходимо отправить запрос на подключение на адрес support@1sept.ru на получение Client ID и Client Secret, указав информацию о подключенном клиенте и список разрешённых адресов возврата Redirect URL (список нужен только для сайтов).

В примерах будут приведены тестовые параметры сервиса (необходимо заменить на рабочие):

Авторизация на сайте (Authorization code grant)

Этот тип авторизации предусмотрен для сайтов и производится для каждого пользователя отдельно. Сервис направляет браузер пользователя к серверу авторизации (Authorization URL), где у пользователя запрашивается согласие на авторизацию сервиса и согласуется перечень предоставляемых пользователем сервису прав доступа.

GET /oauth/authorize?response_type=code&client_id=testclient&redirect_uri=https:%2F%2Fexample.ru%2Fredirect&scope=profile%20email&state=l4xipq7…XwT0hR HTTP/1.1
Host: my.1sept.ru

HTTP запрос

GET https://my.1sept.ru/oauth/authorize

URL параметры

GET Параметр Значение Описание
response_type code Тип запроса
client_id testclient ID сервиса (Client ID)
redirect_uri https://example.ru/redirect Пусть возврата (Redirect URL)
scope profile email Права доступа (разделённые пробелом)
state l4xipq7…XwT0hR Проверочная строка (необязательно)

Параметр state необязателен, но настоятельно рекомендуется использовать в целях безопасности. Это должна быть случайная строка, которая сохраняется в сессии пользователя для последующей сверки.

После решения пользователя происходит перенаправление к сервису (Redirect URL) с одноразовым code. Далее сервис, используя code, запрашивает токен у API (Access Token URL).

HTTP/1.1 302 Found
Location: https://example.ru/redirect?code=def50200…5Ydp2&state=l4xipq7…XwT0hR

HTTP запрос

GET https://example.ru/redirect

URL параметры

GET Параметр Значение Описание
code def50200…5Ydp2 Код для получения токена
state l4xipq7…XwT0hR Проверочная строка (если передана)

Далее сайту необходимо запросить токен у API (Access Token URL).

POST /oauth/access_token HTTP/1.1
Content-Type: multipart/form-data; charset=utf-8; boundary=__X_PAW_BOUNDARY__
Host: api.1sept.ru

--__X_PAW_BOUNDARY__
Content-Disposition: form-data; name="grant_type"

authorization_code
--__X_PAW_BOUNDARY__
Content-Disposition: form-data; name="redirect_uri"

https://example.ru/redirect
--__X_PAW_BOUNDARY__
Content-Disposition: form-data; name="client_id"

testclient
--__X_PAW_BOUNDARY__
Content-Disposition: form-data; name="client_secret"

secret_123
--__X_PAW_BOUNDARY__
Content-Disposition: form-data; name="code"

def50200…5Ydp2
--__X_PAW_BOUNDARY__--

HTTP запрос

POST https://api.1sept.ru/oauth/access_token

URL параметры

POST Параметр Значение Описание
grant_type authorization_code Тип авторизации
redirect_uri https://example.ru/redirect Пусть возврата (Redirect URL)
client_id testclient ID сервиса
client_secret secret_123 Ключ для авторизованных запросов к API
code def50200…5Ydp2 Код для получения токена

Если все данные верны и актуальны, то API вернёт JSON:

{
  "token_type": "Bearer",
  "expires_in": 3600,
  "access_token": "eyJ0eXAiOiJ…O3sQ",
  "refresh_token": "def502009791659…cf1d"
}
Параметр JSON Значение Описание
token_type Bearer Тип токена
expires_in 3600 Срок действия токена доступа
access_token eyJ0eXAiOiJ…O3sQ Токен доступа
refresh_token def502009791659…cf1d Токен восстановления

Авторизация сервиса (Client credentials grant)

Этот тип авторизации предназначен авторизации самого сервиса (без привязки к пользователю).

HTTP запрос

POST https://api.1sept.ru/oauth/access_token

URL параметры

GET Параметр Значение Описание
grant_type client_credentials Тип токена
client_id testclient ID сервиса
client_secret secret_123 Ключ для авторизованных запросов к API

Если все данные верны и актуальны, то API вернёт JSON:

{
  "token_type": "Bearer",
  "expires_in": 3600,
  "access_token": "eyJ0eXAiOi…VTJs0g"
}
Параметр JSON Значение Описание
token_type Bearer Тип токена
expires_in 3600 Срок действия токена доступа
access_token eyJ0eXAiOi…VTJs0g Токен доступа

Обновление токена

Если при авторизации сервиса был выдан токен восстановления, то вместо токена доступа с истёкшим сроком действия через API можно получить новый.

POST /oauth/access_token HTTP/1.1
Content-Type: multipart/form-data; charset=utf-8; boundary=__X_PAW_BOUNDARY__
Host: api.1sept.ru

--__X_PAW_BOUNDARY__
Content-Disposition: form-data; name="grant_type"

refresh_token
--__X_PAW_BOUNDARY__
Content-Disposition: form-data; name="refresh_token"

def502009791659…cf1d
--__X_PAW_BOUNDARY__
Content-Disposition: form-data; name="client_id"

testclient
--__X_PAW_BOUNDARY__
Content-Disposition: form-data; name="client_secret"

secret_123
--__X_PAW_BOUNDARY__--

HTTP запрос

POST https://api.1sept.ru/oauth/access_token

URL параметры

POST параметр Значение Описание
grant_type refresh_token Тип запроса
refresh_token def502009791659…cf1d Проверочная строка (если передан)
client_id testclient ID сервиса
client_secret secret_123 Ключ для авторизованных запросов к API
scope profile Права доступа (необязательный параметр)

Работа с API

После того как, токен доступа получен, приложение должно включать его в каждый запрос к API, в качестве заголовка HTTP Authorization: Bearer {токен}.

Получение данных пользователя

Для получения данных пользователя необходимо выполнить GET запрос используя выданный токен. В ответ API пришлёт JSON с данными, к которым пользователь разрешил доступ (scope).

HTTP запрос

GET /2.0/userinfo HTTP/1.1
Authorization: Bearer eyJ0eXAiOiJ…173h1hQ
Host: api.1sept.ru

GET https://api.1sept.ru/2.0/userinfo

Заголовки HTTP запроса

Заголовок Значение Описание
Authorization Bearer eyJ0eXAiOiJ…173h1hQ Токен доступа

Поля ответа

{
  "id": "57453134-486c-11e8-9081-456056b34322",
  "id_alt": [
    "945c7c22-4d32-11e8-9081-456056b34322"
  ],
  "type": "person",
  "personal_name": {
    "surname": "Иванов",
    "name": "Иван",
    "patronymic": "Иванович"
  },
  "display_name": "Иван Иванов",
  "sex": "male",
  "locale": "ru_RU",
  "timezone": "Europe/Moscow",
  "passport": {
    "snils": "123-456-789 55"
  },
  "email": "ivanov@example.ru",
  "birthday": "1976-01-01",
  "age": 43,
  "avatar": "https://avatar.1sept.ru/57453134-486c-11e8-9081-456056b34322.jpeg",
  "avatar_max": "https://avatar.1sept.ru/57453134-486c-11e8-9081-456056b34322.max.jpeg",
  "avatar_version": 32958,
  "avatar_default": false,
  "phones": [
    {
      "canonical": "+79011234567",
      "type": "mobile",
      "number": "+7 (901) 123-45-67",
      "comment": ""
    }
  ],
  "location": {
    "country_id": "RU",
    "country_name": "Россия",
    "country_name_eng": "Russia",
    "region_id": "ALT",
    "region_name": "Алтайский край",
    "region_name_eng": "Altai Krai"
  },
  "address": {
    "id": 12345,
    "country_id": "RU",
    "country_name": "Россия",
    "country_name_eng": "Russia",
    "postal_code": "123456",
    "region_id": "ROS",
    "region_name": "Ростовская область",
    "region_name_eng": "Rostov Oblast",
    "area": "",
    "city": "Ростов",
    "street": "ул. 1 Мая",
    "house": "7",
    "building": "1",
    "flat": "121",
    "general_delivery": false,
    "postal_box": "",
    "inline": "ул. 1 Мая, д. 7, стр. 1, офис 121, Ростов, Ростовская обл.",
    "organization": "Школа «Ромашка»"
  }
}
Заголовок Право доступа Тип Описание
id UUID, CHAR36 ID пользователя.
id_alt* array(UUID, CHAR36) Массив старых ID пользователя.
type "person" или "organization" Тип учётной записи.
personal_name.surname profile string Фамилия.
personal_name.name profile string Имя.
personal_name.patronymic profile string Отчество.
display_name profile string Отображаемое имя.
sex profile "male", "female" или null Пол.
locale profile string Локаль пользователя.
timezone profile string Часовой пояс (см. список часовых поясов).
email email string Эл. адрес (если подтверждён).
birthday birthday "YYYY-MM-DD" Дата рождения.
is_died profile bool Пользователь умер.
age birthday int Возраст (полных лет).
avatar avatar string Картинка пользователя (URL) размером 150x150. Для формирования ссылкой на другие масштабы обратитесь к разделу Адрес аватарки.
avatar_max avatar string Картинка пользователя (URL) максимального размера.
avatar_version avatar int Версия картинки (null — при отсутствии картинки). Используется в URL картинки для кэширования.
avatar_default avatar bool Является ли картинка пользователя заглушкой.
passport.snils passport string СНИЛС
phones.* phone array Телефон(ы)
phones.canonical phone string Каноническая запись номера телефона (E164)
phones.type phone string Тип телефона (если указано):
phones.number phone string Номер телефона (как его ввёл пользователь)
phones.comment phone string Комментарий к телефону
location.* location array Регион пользователя
location.country_id location string Код страны (ISO 3166-1 alpha-2)
location.country_name location string Название страны
location.country_name_eng location string Название страны (на английском)
location.region_id location string Код региона (ISO 3166-1* alpha-2)
location.region_name location string Название региона
location.region_name_eng location string Название региона (на английском)
address.* address array Почтовый адрес
address.id address int ID адреса
address.country_id address string Код страны (ISO 3166-1 alpha-2)
address.country_name address string Название страны
address.country_name_eng address string Название страны (на английском)
address.postal_code address string Индекс
address.region_id address string Код региона (ISO 3166-1* alpha-2)
address.region_name address string Название региона
address.region_name_eng address string Название региона (на английском)
address.area address string Район
address.city address string Город (населённый пункт)
address.street address string Улица
address.house address string Дом
address.building address string Строение
address.flat address string Квартира
address.general_delivery address bool До востребования
address.postal_box address string Абонентский ящик
address.inline address string Полный адрес в строку в формате Почты (без индекса)
address.organization address string Название организации

API возвращает значения запрошенных полей только после получения разрешения от пользователя и при их заполненности (при отсутствии данных будет возвращён «null» или "").

Справочник

Основные пути

Ресурс URL
Авторизация пользователя (Authorization URL) https://my.1sept.ru/oauth/authorize
API (URL) https://api.1sept.ru/2.0
Получение и обновление токена (Access Token URL) https://api.1sept.ru/oauth/access_token

Права доступа (scope)

При авторизации пользователь видит запрошенные сервисом права доступа к ресурсам и может отклонить часть из них (кроме profile, который нельзя отклонить).

Коды ошибок

В процессе авторизации могут произойти ошибки, тогда браузер перенаправляется на страницу возврата (Return URL) c кодом ошибки (GET параметр error). Дополнительно в параметрах могут присутствуют message и hint с текстовым описанием ошибки.

Код Описание
access_denied Пользователь или сервер авторизации отклонил запрос.
unsupported_grant_type Запрошенный тип авторизации не поддерживается сервером авторизации.
invalid_request Запрос на авторизацию составлен некорректно.
invalid_client Запрашивающий авторизацию сервис не предоставил корректных подтверждающих полномочия данных.
invalid_scope Запрошен некорректный или неизвестный тип данных.
invalid_credentials Предоставлены некорректные данные для входа пользователя.
server_error На сервере авторизации произошла неожиданная ошибка.

Адрес аватарки

При наличии аватарки (картинки пользователя) API отдаёт URL в формате:

https://avatar.1sept.ru/{UUID}.jpeg (разрешение 150x150)

Пример: https://avatar.1sept.ru/57453134-486c-11e8-9081-456056b34322.jpeg

https://avatar.1sept.ru/57453134-486c-11e8-9081-456056b34322.300.jpeg
https://avatar.1sept.ru/57453134-486c-11e8-9081-456056b34322.450.jpeg?v=215
https://avatar.1sept.ru/57453134-486c-11e8-9081-456056b34322.600@2x.jpeg
https://avatar.1sept.ru/57453134-486c-11e8-9081-456056b34322.max.jpeg

При необходимости размер можно настроить используя формат: https://avatar.1sept.ru/{UUID}.{size|max}[@2x|@3x].jpeg?v={version}

где:

При запросе отсутствующей картинки происходит отдача заглушки (инициалы пользователя на цветном фоне).

Словарь терминов