Введение
Первое сентября предоставляет доступ к функциям 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 |
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
, который нельзя отклонить).
profile
— Базовая информация (фамилия, имя, отчество, пол). Обязательный scopeaddress
— Почтовый адрес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 авторизации.