Download OpenAPI specification:Download
Документация выполнена в соответствии со спецификацией OpenAPI. На ее основе можно сгенерировать исходный код для многих языков программирования. Спецификация построенна таким образом что использовать ее удобно и человеку и автоматизированной системе.
Все запросы должны отправляться по защищенному протоколу HTTPS на адрес https://api.esia.cloud/api/v1.
Параметры запроса передаются в теле сообщения. данные как в формате application/json, так и в формате x-www-form-urlencoded. Схема авторизации пользователей идентична протоколу OAuth 2.0
1) Пользователь нажимает ссылку "Войти через госуслуги"
2) Приложение отправляет запрос Authorization Request на сервер ЕСИА-облака
3) ЕСИА-облако отправляет пользователя на страницу авторизации ЕСИА
4) Пользователь вводит свой логин пароль, при необходимости проходит двухфакторную авторизацию. А также выдает разрешения запрашиваемые ИС.
5) ЕСИА-облако с помощью HTTP Redirect возвращает временный токен доступа
6) Приложение отправляет запрос с временный токеном и получает токен авторизации
7) Ответ содержит токен авторизации
#необходимо перенаправить браузер пользователя по адресу
https://api.esia.cloud/api/v1/ac?client_id=123ABC45&state=82bdcf89-1166-4bfe-905b-aaa2132537ec&code=code&redirect_uri=https%3A%2F%2Fyour-site.ru%2Fauth&scope=openid%20fullname
< ?php #необходимо выполнить post запрос с нужными параметрами с передачей code полученного на предыдущем шаге $ch = curl_init('https://api.esia.cloud/api/v1/te'); curl_setopt($ch, CURLOPT_RETURNTRANSFER, true); curl_setopt($ch, CURLOPT_POST, true); curl_setopt($ch, CURLOPT_POSTFIELDS, "client_id=123ABC45&client_secret=123456&state=124cfbba-4902-48c5-a4ca-ad339cc9b9f6&code=cf9e71891ffda3b23d259ee04733b08f8ed03cfd8757087be4b719ae33930f91a0e451117685f40e10f77255e5ec00b7f31c6472ad6a31411d45fcc17e377bcb&scope=openid%20fullname&redirect_uri=https%3A%2F%2Fyour-site.ru%2Fauth"); $json = curl_exec($ch); curl_close($ch); echo $json; ?>
< ?php $ch = curl_init('https://esia-cloud/api/v1/data/3456789'); curl_setopt($ch, CURLOPT_RETURNTRANSFER, 1); $headers = array("Authorization: Bearer d8c05c0d3fdac10ec86ce6fdf4eec7bca5d771510e5fbacca0d001e957f15c47f0eeeca864369d6b056d80689e8e7f4788670712755a4a29f8dde936024626a0"); curl_setopt($ch, CURLOPT_HTTPHEADER, $headers); $json = curl_exec($ch); curl_close($ch); echo $json; ?>
#необходимо перенаправить браузер пользователя по адресу
https://api.esia.cloud/api/v1/logout?client_id=123ABC45&redirect_uri=https%3A%2F%2Fyour-site.ru%2Fauth
Ошибки и их описание возвращаемые системой
Коды ошибок
| error | error_description | | ------------- | ------------- | | invalid authorization | отсутсвует HTTP заголовок Authorization Bearer | | invalid token or oid | неверный token или oid | | bad redirect_uri | некорректный redirect_uri | | invalid request | отсутсвует нужные параметры запроса | | invalid client_secret | неверный client_id или client_secret | | invalid code | отсутсвует, просрочен или неверный код авторизации | | invalid token | отсутсвует, просрочен или неверный токен | | invalid client | не удалось найти ИС | | bad redirect_uri | некорректный redirect_uri | | redirect_uri not exist | указанный в запросе redirect_uri отсутствует среди разрешенных для ИС | | collection not exist | запрошен несуществующий набор данных | | invalid esia token | Отсутсвует ЕСИА access-token. Сначала нужно запростить авторизационный код (code). |
Необходимо перенаправить браузер пользователя передав следующие параметры
client_id required | string Идентификатор ИС в ЕСИА-облаке |
code required | string Тип ответа, который ожидается от ЕСИА-облака, всегда имеет значение |
redirect_uri required | string Cсылка, по которой должен быть направлен пользователь после того, как даст разрешение на доступ |
scope required | string Область доступа, запрашиваемые права. Полностью соответсвуют scope из методичиских рекомендаций ЕСИА |
state required | string Набор случайных символов, необходимо для защиты от перехвата |
{- "code": "db144da9dbebe1a9755be8c8f65ed3521892901526d195ff561c17e23c93226c3e7faaa1c4faebd0137d786cb4949a48ee8799a395e1ba863cffb87d290b8219",
- "state": "98779bc6-a803-472c-a6a2-fac467d1abb1"
}
Для получения кода доступа access_token отправьте следующие параметры
client_id required | string Идентификатор ИС в ЕСИА-облаке |
client_secret required | string API-ключ из Настроек личного кабинета |
code required | string Значение авторизационного кода, который был ранее получен от ЕСИА и который необходимо обменять на access_token |
grant_type required | string Всегда принимает значение |
redirect_uri required | string Cсылка, по которой должен быть направлен пользователь после аутентификации (то же самое значение, которое было указано в запросе на получение авторизационного кода) |
scope required | string Область доступа, запрашиваемые права (то же самое значение, которое было указано в запросе на получение авторизационного кода). Полностью соответсвуют scope из методичиских рекомендаций ЕСИА. |
state required | string Набор случайных символов, необходимо для защиты от перехвата |
timestamp required | string Время запроса маркера в формате yyyy.MM.dd HH:mm:ss Z (например, 2011.10.25 12:27:21 +0900) |
token_type required | string Всегда принимает значение |
{- "access_token": "d4551b5a1d8073d69c3b02aaf0ea5454bd4421276c4c8daf802c35f60d507ac0abcb60698c41039a47d312050030486025a321c0da3173fe51d306f9a4e337c7",
- "refresh_token": "9d85c52a-5680-454d-969f-ce7b9fc646ca",
- "id_token": "eyJ2ZXIiOjACBnR5cCI6IkpXVCIsInNidCI6ImlkIiwiYWxnIjoiR09TVDM0MTBfMjAxMl8yNTYifQ.eyJhdWQiOiIyMzUzMDQ4NjEiLCJzdWIiOjI0Mjg0ODU5MiwibmJmIjoxNjM1MzkyMDg5LCJhbXIiOiJQV0QiLCJ1cm46ZXNpYTphbWQiOiJQV0QiLCJhdXRoX3RpbWUiOjE2MzUzOTE0NL2-IlzcyI6Imh0dHA6XC9cL2VzaWEuZ29zdXNsdWdpLnJ1XC8iLCJ1cm46ZXNpYTpzaWQiOiI1ZTk0MTEzMC1kNWExLTQ3OTAtODE2YS05Yjg4NTY4ZGNlYzMiLCJ1cm46ZXNpYTpzYmoiOnsidXJuOmVzaWE6c2JqOnR5cCI6IlAiLCJ1cm46ZXPorTpzYmo6aXNfdHJ1Ijp0cnVlLCJ1cm46ZXNpYTpzYmo6b2lkIjoyNDI4NDg1OTIsInVybjplc2lhOnNiajpuYW0iOiIwNzYtMzQyLTI1MCA1OSJ9LCJleHAiOjE2MzU0MDI4ODksImlhdCI6MTYzNTM5MjA4OX0.BCLMauut1A8QpnFoQMIUwXvowFf-zRKil6fgQrDHhu50xoV0uS8lo4PoqgZpsCgTF6HWw6TaWgAlTpgPX7aeZA",
- "oid": "12345678",
- "token_type": "Bearer"
}
Получение ФИО, даты рождения, СНИЛС, ФИО и прочих обобщенных данных по запрошенным скоупам. Для получения персональных данных о пользователях система-клиент должна направить соответствующий запрос. Для авторизации HTTP-запрос должeн содержать следующий заголовок: Authorization: Bearer <access_token>
, где access_token — токен авторизации права на исполнение запрашиваемого метода с заданным набором параметров.
oid required | string Внутренний идентификатор объекта, в том числе пользователя, в ЕСИА |
{- "info": {
- "stateFacts": [
- "EntityRoot"
], - "firstName": "Алексей",
- "lastName": "Иванович",
- "middleName": "Степанов",
- "trusted": true,
- "updatedOn": 1597660053,
- "status": "REGISTERED",
- "verifying": false,
- "rIdDoc": 2255365,
- "containsUpCfmCode": false,
- "eTag": "8E14015E333F978AEE32024BBE5513C20F158D4A"
}
}
Для получения персональных данных о пользователях система-клиент должна направить соответствующий запрос. Для авторизации HTTP-запрос должeн содержать следующий заголовок: Authorization: Bearer <access_token>
, где access_token — токен авторизации права на исполнение запрашиваемого метода с заданным набором параметров.
oid required | string Внутренний идентификатор объекта, в том числе пользователя, в ЕСИА |
{- "ctts": [
- {
- "stateFacts": [
- "Identifiable"
], - "id": 30341168,
- "type": "EML",
- "vrfStu": "VERIFIED",
- "value": "usermail@example.com",
- "eTag": "0E402592529081AAA8F008986475DF642E980F57"
}, - {
- "stateFacts": [
- "Identifiable"
], - "id": 30342267,
- "type": "MBT",
- "vrfStu": "VERIFIED",
- "value": "+7(999)1234567",
- "eTag": "08F441711C9C5B511F41EB126A89E73285E71C40"
}, - {
- "stateFacts": [
- "Identifiable"
], - "id": 56133382,
- "type": "PHN",
- "vrfStu": "NOT_VERIFIED",
- "value": "+7(999)1234567",
- "eTag": "E1640B7FF5BD45EF629167F50BF535535DA5CF65"
}
]
}
Для получения персональных данных о пользователях система-клиент должна направить соответствующий запрос. Для авторизации HTTP-запрос должeн содержать следующий заголовок: Authorization: Bearer <access_token>
, где access_token — токен авторизации права на исполнение запрашиваемого метода с заданным набором параметров.
oid required | string Внутренний идентификатор объекта, в том числе пользователя, в ЕСИА |
{- "addrs": [
- {
- "stateFacts": [
- "Identifiable"
], - "id": 7801249,
- "type": "PLV",
- "addressStr": "Амурская обл, Благовещенск г, Ленина ул",
- "fiasCode": "76884535-32a6-5533-a3d5-6f27b6cb5201",
- "flat": "1",
- "countryId": "RUS",
- "street": "Ленина",
- "house": "1",
- "zipCode": "675000",
- "city": "Благовещенск",
- "region": "Амурская",
- "vrfDdt": "0,0,0",
- "eTag": "AED61E5CB6BDA7F89149CB70A0E2049B39D41461"
}, - {
- "stateFacts": [
- "Identifiable"
], - "id": 7804555,
- "type": "PRG",
- "city": "Благовещенск",
- "addressStr": "обл Амурская, г Благовещенск, ул Ленина",
- "fiasCode": "76884535-32a6-4b4e-a3d5-6f27b6cb5201",
- "flat": "1",
- "countryId": "RUS",
- "house": "1",
- "zipCode": "675004",
- "street": "Ленина",
- "region": "Амурская",
- "vrfDdt": "0,0,0",
- "eTag": "AED61E5CB6BDA7F891F1CB70A0E2049B39D41461"
}
]
}
Для получения персональных данных о пользователях система-клиент должна направить соответствующий запрос. Для авторизации HTTP-запрос должeн содержать следующий заголовок: Authorization: Bearer <access_token>
, где access_token — токен авторизации права на исполнение запрашиваемого метода с заданным набором параметров.
oid required | string Внутренний идентификатор объекта, в том числе пользователя, в ЕСИА |
{- "docs": [
- {
- "stateFacts": [
- "EntityRoot"
], - "id": 2211365,
- "type": "RF_PASSPORT",
- "vrfStu": "VERIFIED",
- "series": "1000",
- "number": "111111",
- "issueDate": "01.01.2000",
- "issueId": "111001",
- "issuedBy": "УВД ГОР. БЛАГОВЕЩЕНСКА",
- "eTag": "BE265B5DFB7AB557CA3AE0435104D442E41108D7F"
}
]
}
Для получения персональных данных о пользователях система-клиент должна направить соответствующий запрос. Для авторизации HTTP-запрос должeн содержать следующий заголовок: Authorization: Bearer <access_token>
, где access_token — токен авторизации права на исполнение запрашиваемого метода с заданным набором параметров.
oid required | string Внутренний идентификатор объекта, в том числе пользователя, в ЕСИА |
{- "kids": [ ]
}
Для получения персональных данных о пользователях система-клиент должна направить соответствующий запрос. Для авторизации HTTP-запрос должeн содержать следующий заголовок: Authorization: Bearer <access_token>
, где access_token — токен авторизации права на исполнение запрашиваемого метода с заданным набором параметров.
oid required | string Внутренний идентификатор объекта, в том числе пользователя, в ЕСИА |
{- "vhls": [
- {
- "stateFacts": [
- "Identifiable"
], - "id": 2331354,
- "name": "Toyota Will VS",
- "numberPlate": "И123СА28",
- "regCertificate": {
- "series": "282С",
- "number": "130346"
}, - "vrfStu": "NOT_VERIFIED",
- "duplicate": false,
- "eTag": "66133797373B90C030F3FF51B1128B7C6F246194"
}, - {
- "stateFacts": [
- "Identifiable"
], - "id": 10366210,
- "name": "Mazda CX-5",
- "numberPlate": "В987УМ28",
- "regCertificate": {
- "series": "2810",
- "number": "811512"
}, - "vrfStu": "NOT_VERIFIED",
- "duplicate": false,
- "eTag": "644A7911FA457F2D567C928E3AFCD57317F92F80"
}
]
}
Для получения персональных данных о пользователях система-клиент должна направить соответствующий запрос. Для авторизации HTTP-запрос должeн содержать следующий заголовок: Authorization: Bearer <access_token>
, где access_token — токен авторизации права на исполнение запрашиваемого метода с заданным набором параметров.
oid required | string Внутренний идентификатор объекта, в том числе пользователя, в ЕСИА |
{- "orgs": [ ]
}