Введение

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

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

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

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

Регистрация

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

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

Client ID = testclient — ID сервиса,
Client Secret = secret_123 — Ключ для авторизованных запросов к API,
Redirect URL = https://example.ru/redirect — Белый список адресов возврата (один или несколько).

Авторизация на сайте (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» или "").

* Если пользователь зарегистрировал несколько Личных кабинетов Первое сентября, то они могут быть объединены. В таком случае остаётся один основной ID пользователя, а все остальные попадают в список старых ID. Если сервис получает ответ userinfo с новым ID, то перед тем как создавать новую учётную запись рекомендуется проверить список старых ID: если какой-либо ID найдётся, то следует только заменить этот ID на основной.

Справочник

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

Ресурс	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, который нельзя отклонить).

profile — Базовая информация (фамилия, имя, отчество, пол). Обязательный scope
address — Почтовый адрес
avatar — Картинка (картинка пользователя)
birthday — Дата рождения (дата рождения, возраст)
email — Электронный адрес (email)
location — Регион пользователя (страна, регион)
passport — Документы (СНИЛС)
phone — Телефон(ы)
regalia — Регалии

Коды ошибок

В процессе авторизации могут произойти ошибки, тогда браузер перенаправляется на страницу возврата (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}

где:

size — размер (ширина = высота),
max — максимально доступный размер,
@2x|@3x — признак HiRes,
version — необязательный параметр (avatar_version), ускоряющий загрузку и обновление аватарок при их замене.

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

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

API (Application Programming Interface) — Публичный сервис для работы с ресурсами Первого сентября.
Сервис — сайт или приложение, использующая API.
Токен доступа — многоразовый ключ для доступа к защищённым ресурсам API с ограниченным сроком действия.
Токен восстановления — одноразовый токен с неограниченным временем действия, с помощью которого можно восстановить рабочий токен.
Права доступа (scope) — перечень ресурсов пользователя, к которым он разрешает доступ сервису.
Проверочная строка (state) — строка (обычно случайный набор символов) используемая для защиты от CSRF атак при OAuth авторизации.