Приложение Б. Сервисы ЕСИА на базе подхода REST

Приложение Б

Сервисы ЕСИА на базе подхода REST

Б.1 Общие сведения о программном интерфейсе ЕСИА

В рамках развития ЕСИА реализован прикладной программный интерфейс на базе архитектурного стиля "Representational State Transfer" (REST). Он позволяет интегрированным с ЕСИА информационным системам получать доступ к хранящимся в ЕСИА ресурсам, т.е. данным (например, о пользователях или других информационных системах), а также выполнять ряд операций.

Вызов прикладного программного интерфейса возможен только теми интегрированными с ЕСИА системами, которые имеют на это соответствующие полномочия. Контроль доступа к ресурсам ЕСИА осуществляет сервис авторизации ЕСИА, реализующий модель контроля доступа, основанную на спецификациях OAuth 2.0 (см. Приложение В).

Для обозначения ресурсов используются специальные идентификаторы. Сами ресурсы организованы иерархически, уровни разделены косой чертой - "/". Ресурсы более "низкого" уровня являются составными частями "родительского уровня":

В ЕСИА используется два типа ресурсов:

- документ содержит информацию об отдельном объекте в базе данных, который характеризуется некоторыми полями и значениями. Например, при доступе к документу об организации сервис возвращает наименование организации, ее тип, ОГРН и др. Кроме того, в документе могут содержаться ссылки на связанные ресурсы: так, в документе об организации размещаются указатели на ресурсы (документы) по ее сотрудникам;

- коллекция представляет собой список некоторых ресурсов, например, документов. Перечень организаций, сотрудников отдельной организации - примеры коллекций. Ресурсы, который включены в коллекцию, снабжены собственными идентификаторами (uri). Обычно для обозначения коллекции используются множественные существительные (orgs, sbjs и др.).

Для вызова сервиса ЕСИА, позволяющего получить доступ к защищенному ресурсу, система-клиент должна направить в https-адрес программного интерфейса ЕСИА запрос. Для этого (в зависимости от типа запроса) используются методы GET или POST. В каждом запросе должен быть указан идентификатор ресурса, к которому запрашивается доступ. Кроме того, в запрос на вызов REST-API должен быть добавлен следующий header:

Authorization: Bearer <access token>

<access token> - маркер доступа, предварительно полученный у сервиса авторизации ЕСИА. Срок действия маркера доступа не должен истечь на момент вызова. Маркер доступа должен быть выдан системе-клиенту на <scope>, позволяющий получить запрашиваемый защищенный ресурс. Пример запроса на получение сведений об организации с идентификатором 1000000000:

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

При вызове сервиса могут быть заданы параметры запроса (query), которые оформляются стандартным способом. Следующий запрос позволит получить первые 15 организаций из соответствующей коллекции orgs:

При вызове сервиса может быть указана конкретная схема предоставления данных об объекте. Для этого необходимо дать ссылку на соответствующую схему в заголовке запросе (с помощью ACCEPT. Например:

Данный запрос позволяет получить сведения о пользователе с идентификатором 402, сформированные согласно схеме Person-1. Это означает, что по мере развития ЕСИА может быть изменен передаваемый атрибутный состав данных о пользователе, в результате чего появляется новые схемы - Person-2, Person-3 и т.д. В связи с этим для получения неизменного состава атрибутов рекомендуется в запросе указывать конкретную схему. Если в качестве схемы указана схема /model/prn/Person без явного указания версии, то возвращается последняя версия. Если схема не указана вообще, то также возвращается последняя версия схемы.

В ответе на корректный запрос выдается JSON-документ, который представляет собой набор пар ключ/значение или массив значений. В заголовке (headers) ответа содержатся следующие данные:

1. Ссылки (links) на связанные ресурсы. Например, если в запросе указан ресурс с данными конкретного пользователя (prns/402), то ссылки будут содержать ресурсы с его контактными данными, документами, адресам, транспортными средствами, а также на "родительский" ресурс с перечнем всех пользователей в системе.

2. Указатель запрошенного ресурса (location), т.е. uri запрошенного ресурса.

3. Тип предоставляемых данных (Content-Type) с указанием схемы предоставляемых данных. Например, если запрашиваются данные о пользователе в схеме Person-1, то будет указано следующее значение: Content-Type: [application/json; q=.2; schema="https://esia-portal1.test.gosuslugi.ru/rs/model/prn/Person-1"]

Пример раздела headers (разрывы строк даны для удобства чтения):

Содержательная часть ответа на запрос содержится в разделе body. Пример возвращаемых данных (разрывы строк даны для удобства чтения) о физическом лице:

Каждое описание объекта или коллекции содержит параметр stateFacts, указывающий на некоторые факты о предоставляемых сведениях. Возможны следующие значения stateFacts:

- Identifiable - имеет идентификатор (например, это конкретный контакт или документ);

- hasSize - имеет размер (например, для коллекции указывает на число элементов коллекции);

- FirstPage - первая страница списка;

- LastPage - последняя страница списка;

- Paginated - постраничный список;

- EntityRoot- корневой объект;

- ReadOnly - объект только для чтения.

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

Из данного ответа видно, что на каждой странице отображается по 2 элемента.

Для ряда операций поддерживается возможность встраивания (embedding) связанных данных. Для этого в запросе соответствующего ресурса необходимо указывать параметр "embed", а в качестве его значения - сущность, которую требуется включить в ответ запроса. Например, при запросе следующего ресурса будут отображаться ссылки на контакты пользователя 100000:

Однако указание параметра "embed" позволяет получить данные о контактах непосредственно в ответе на следующий запрос:

В этом случае запрос данного ресурса будет возвращать ответ (фрагмент, разрывы строки даны для удобства чтения):

В данном случае на месте ссылок на связанные элементы встраиваются данные контактов.

При встраивании сохраняется возможность получать схемы возвращаемых ресурсов, например:

В этом случае данные об элементах будут возвращаться согласно первой схеме.

Также возможно встраивание нескольких ресурсов в запросе, например:

В этом случае в ответе вместо ссылок на сотрудников организации будут передаваться персональные данные сотрудников организации: ФИО, отчество, дата и место рождения, пол и т.д. Набор данных зависит от информации, указанной в профиле сотрудника.

При встраивании нескольких ресурсов также возможно указание на версии, например:

Перечень ссылок, которые могут быть встроены:

- данные о физических лицах:

- контактные данные (contacts);

- адреса (addresses);

- документы (documents);

- транспортные средства (vehicles);

- организации, к которым принадлежит физическое лицо (organizations);

- данные об организациях:

- контактные данные (contacts);

- адреса (addresses);

- транспортные средства (vehicles);

- данные о сотрудниках организации:

- данные о сотруднике как физическом лице (person).

- данные по ссылкам, отображаемым в содержании ответа в разделе "elements" (возможность встраивания elements есть везде, где параметр stateFacts имеет значение "hasSize").

Далее приведены описания следующих операций программного интерфейса ЕСИА:

- предоставление персональных данных пользователей;

- проверка факта удаления учётной записи пользователя ЕСИА;

- предоставление сведений о вхождении пользователя в группы и организации;

- предоставление данных из профиля организации;

- предоставление списка участников группы или организации;

- предоставление сведений о вхождении пользователей в группы;

- управление данными организации;

- предоставление сведений о субъекте.

Б.2 Предоставление персональных данных пользователей

Для получения персональных данных о пользователях система-клиент должна направить в https-адрес REST-API системы ЕСИА*(29) запрос методом GET. В запросе должен быть указан ресурс, содержащий необходимые данные. Иерархия идентификаторов этих ресурсов в ЕСИА имеет следующий вид:

/prns/{oid}/{collection_name}/{collection_entity_id}, где:

- prns - перечень (коллекция) пользователей, зарегистрированных в ЕСИА;

- {oid} - внутренний идентификатор объекта, в том числе пользователя, в ЕСИА;

- {collection_name} - ссылка на перечень (коллекцию) типов данных, указанных пользователем с данным oid, возможные значения:

- ctts - контактные данные;

- addrs - адреса;

- docs - документы пользователя;

- orgs - организации, сотрудником которых является данный пользователь;

- kids - дети пользователя;

- vhls - транспортные средства пользователя.

- {collection_entity_id} - внутренний идентификатор элемента (например, контакта или документа) пользователя в ЕСИА.

В запрос должен быть добавлен header с маркером доступа, позволяющим получить доступ к данному ресурсу (либо scope id_doc с параметрами, либо один или несколько scope, обеспечивающих доступ к персональным данным пользователя, с параметрами*(30)).

Пример запроса (вызов сервиса в среде разработки):

Данные, которые ЕСИА возвращает в ответ на запрос, представлены в таблице 6.

Таблица 6 - Параметры ответа на запрос о персональных данных пользователя

N	URI запрашиваемого ресурса	Описание ресурса	Предоставляемые данные
1.	/prns/{oid}	Данные о пользователе с идентификатором prn-id	Данные о физическом лице: <rIdDoc> - идентификатор текущего документа пользователя; <firstName> - имя; <lastName> - фамилия; <middleName> - отчество; <birthDate> - дата рождения (задается как количество секунд, прошедших с 00:00:00 UTC 1 января 1970 года); <birthPlace> - место рождения пользователя; <gender> - пол; <trusted> - тип учетной записи (подтверждена ("true") / не подтверждена ("false")); <citizenship> - гражданство (идентификатор страны гражданства); <snils> - СНИЛС; <inn> - ИНН; <updatedOn> - дата последнего изменения учетной записи пользователя (задается как количество секунд, прошедших с 00:00:00 UTC 1 января 1970 года); <verifying> - процесс проверки данных (true/false); <status> - статус УЗ (Registered - зарегистрирована/Deleted - удалена).
2.	/prns/{oid}/ctts	Перечень контактов физического лица	Перечень контактов физического лица (в виде ссылок на ресурс c указанием {ctt_id}, содержащий данные о каждом контакте)
3.	/prns/{oid}/ctts/{ctt_id}	Сведения об отдельной записи в перечне контактов физического лица	Контактные данные: <type> - тип записи, может иметь значения: - "MBT" - мобильный телефон; - "PHN" - домашний телефон; - "EML" - электронная почта; - "CEM" - служебная электронная почта. <vrfStu> - сведения о "подтвержденности" контактов, может иметь значения: - "NOT_VERIFIED" - не подтвержден; - "VERIFIED" - подтвержден. В настоящее время статус "VERIFIED" может быть только у мобильного телефона ("MBT") и адреса электронной почты ("EML"). <value> - значение контакта; <vrfValStu> - необязательный параметр, указывается в случае, если контакт находится в процессе подтверждения. Может принимать следующее значение: - "VERIFYING" - в процессе подтверждения. В настоящее время статус "VERIFYING" может быть только у мобильного телефона ("MBT") и адреса электронной почты ("EML"). <verifyingValue> - значение контакта, находящегося в процессе подтверждения.
4.	/prns/{oid}/addrs	Перечень адресов физического лица	Перечень адресов физического лица (в виде ссылок на ресурс c указанием {addr_id}, содержащий данные о каждом адресе)
5.	/prns/{oid}/addrs/{addr_id}	Сведения об отдельной записи в перечне адресов физического лица	Адреса: <type> - тип записи, может иметь значения: - "PLV" - адрес места проживания; - "PRG" - адрес места регистрации. <zipCode> - индекс; <countryId> - идентификатор страны; <addressStr> - адрес в виде строки (не включая дом, строение, корпус, номер квартиры); <building> - строение; <frame> - корпус; <house> - дом; <flat> - квартира; <fiasCode> - код КЛАДР; <region> - регион; <city> - город; <district> - внутригородской район; <area> - район; <settlement> - поселение; <additionArea> - доп. территория; <additionAreaStreet> - улица на доп. территории; <street> - улица.
6.	/prns/{oid}/docs	Перечень документов физического лица	Перечень документов физического лица (в виде ссылок на ресурс c указанием {doc_id}, содержащий данные о каждом документе)
7.	/prns/{oid}/docs/{doc_id}	Сведения об отдельной записи в перечне документов физического лица	Документы: <type> - тип записи, может иметь значения: - "RF_PASSPORT" - паспорт гражданина РФ; - "FID_DOC" - документ иностранного гражданина; - "DRIVING_LICENSE" - водительское удостоверение. - "MLTR_ID" - военный билет; - "FRGN_PASS" - заграничный паспорт; - "MDCL_PLCY" - полис ОМС; - "BRTH CERT" - свидетельство о рождении. <vrfStu> - сведения о "подтвержденности" документов, может иметь значения: - "NOT_VERIFIED" - не подтвержден; - "VERIFIED" - подтвержден. <series> - серия документа; <number> - номер документа; <issueDate> - дата выдачи документа; <issueId> - код подразделения; <issuedBy> - кем выдан; <expiryDate> - срок действия документа; <lastName> - фамилия (для заграничного паспорта); <firstName> - имя (для заграничного паспорта).
8.	/prns/{oid}/orgs	Перечень организаций, сотрудником которых является данное физическое лицо	Перечень организаций, сотрудником которых является физическое лицо с данным {oid} (в виде ссылок на ресурс с указанием {oid}, содержащий данные о каждой организации)
9.	/prns/{oid}/kids	Перечень записей о детях физического лица	Перечень детей физического лица (в виде ссылок на ресурс с указанием {kid_id}, содержащий данные о каждом ребенке)
10.	/prns/{oid}/kids/{kid_id}	Сведения об отдельной записи в перечне детей физического лица	Дети: <firstName> - имя ребенка; <lastName> - фамилия ребенка; <middleName> - отчество ребенка; <birthDate> - дата рождения; <gender> - пол; <snils> - СНИЛС; <inn> - ИНН; <trusted> - признак подтвержденности данных о ребенке (подтверждены ("true") / не подтверждены ("false")); <updatedOn> - дата последнего изменения данных о ребенке (задается как количество секунд, прошедших с 00:00:00 UTC 1 января 1970 года)
11.	/prns/{oid}/kids/{kid_id}/docs	Перечень документов ребенка физического лица	Перечень документов ребенка данного физического лица (в виде ссылок на ресурс с указанием {doc_id}, содержащий данные о каждом документе)
12.	/prns/{oid}/kids/{kid_id}/docs/{doc_id}	Сведения об отдельной записи в перечне документов ребенка физического лица	Документы ребенка описываются по аналогии с документами физического лица. Для детей предусмотрены следующие типы (<type>) документов: - "MDCL_PLCY" - полис ОМС; - "BRTH CERT" - свидетельство о рождении*(31).
13.	/prns/{oid}/vhls	Перечень транспортных средств	Перечень транспортных средств, которыми владеет данный пользователь
14.	/prns/{oid}/vhls/{vhl-id}	Транспортное средство пользователя	<name> - имя автомобиля (например, марка или другое пользовательское описание); <numberPlate> - государственный регистрационный знак; <regCertificate> - данные свидетельства о государственной регистрации, включает в себя атрибуты: - <series> - серия свидетельства; - <number> - номер свидетельства.

При отображении всех коллекций используется механизм paging.

Пример ответа на запрос контактных данных физического лица (фрагмент, разрывы строк даны для удобства чтения):

Пример ответа на запрос конкретного адреса физического лица (фрагмент, разрывы строк даны для удобства чтения):

Пример ответа на запрос конкретного документа физического лица (фрагмент, разрывы строк даны для удобства чтения):

Пример ответа на запрос конкретного транспортного средства физического лица (фрагмент, разрывы строк даны для удобства чтения):

Пример ответа на запрос всех транспортных средств физического лица, полученный с использованием возможностей встраивания*(32) (фрагмент, разрывы строк даны для удобства чтения):

Б.3 Проверка факта удаления учётной записи и связанных с ней персональных данных пользователя из ЕСИА

Вызов данной операции предоставляет интегрированным с ЕСИА информационным системам данные об удаленных пользователях в ЕСИА (идентификатор пользователя). Для получения перечня удаленных пользователей система-клиент должна направить в https-адрес REST-API системы ЕСИА запрос методом GET. В запросе должен быть указан ресурс, содержащий необходимые данные. В качестве этого ресурса используется стандартный идентификатор ресурса с персональными данными пользователей (/prns), возвращающий перечень зарегистрированных в системе пользователей (см. раздел Б.2). Специфика вызова данной операции состоит в том, что запрос должен содержать следующие параметры:

- <status> - статус пользователя, должен иметь значение "DELETED";

- <updatedSince> - дата, начиная с которой необходимо отобразить удаленных пользователей. Задается как количество секунд, прошедших с 00:00:00 UTC 1 января 1970 года.

В запрос должен быть добавлен header с маркером доступа, позволяющим получить доступ к данному ресурсу (scope http://esia.gosuslugi.ru/tech_inf с параметрами).

Пример запроса (вызов сервиса в среде разработки):

В качестве ответа передается перечень физических лиц, удаленных с указанной даты. Этот перечень представляет собой список ссылок на ресурс с указанием {oid}, содержащий идентификаторы всех удаленных физических лиц с указанной в запросе даты.

Б.4 Предоставление данных из профиля организации

Для получения данных об организациях система-клиент должна направить в https-адрес REST-API системы ЕСИА*(33) запрос методом GET. В запросе должен быть указан ресурс, содержащий необходимые данные. Идентификатор этого ресурса в ЕСИА имеет следующий вид:

/orgs/{orgOid}/{collection_name}/{collection_entity_id}, где:

- orgs - коллекция организаций, имеющихся в ЕСИА;

- orgOid - внутренний идентификатор организации в ЕСИА; для определения orgOid соответствующей организации необходимо использовать атрибут orgOid, передающийся в утверждениях SAML;

- {collection_name} - ссылка на перечень (коллекцию) типов данных организации с указанным oid, возможные значения:

- ctts - контактные данные;

- addrs - адреса;

- vhls - транспортные средства;

- brhs - филиалы организации.

- {collection_entity_id} - внутренний идентификатор контакта, адреса, транспортного средства или филиала.

В запрос должен быть добавлен header с маркером доступа, позволяющим получить доступ к данному ресурсу (scope в зависимости от полномочий системы).

Пример запроса (вызов сервиса в среде разработки):

Данные, которые ЕСИА возвращает в ответ на запрос, представлены в таблице 7.

Таблица 7 - Параметры ответа на запросы о данных организации

N	URI запрашиваемого ресурса	Описание ресурса	Предоставляемые данные
1.	/orgs/{orgOid}	Данные об организации с идентификатором {orgOid}	Данные об организации: <shortName> - сокращенное наименование организации; <fullName> - полное наименование организации; <type> - тип организации. Для государственных организаций - "AGENCY", для юридических лиц - "LEGAL"; <ogrn> - ОГРН организации; <inn> - ИНН организации; <leg> - код организационно-правовой формы по общероссийскому классификатору организационно-правовых форм; <kpp> - КПП организации; <agencyTerRange> - территориальная принадлежность ОГВ (только для государственных организаций, код по справочнику "Субъекты Российской федерации" (ССРФ), для Российской Федерации используется код 00; <agencyType> - тип ОГВ (только для государственных организаций)*(34).
2.	/orgs/{orgOid}/brhs	Перечень филиалов организации	Перечень филиалов организации (в виде ссылок на ресурс c указанием {branch_id}, содержащий данные о каждом филиале)
3.	/orgs/{orgOid}/brhs/{branch_id}	Сведения о филиале организации	Данные о филиале: <name> - имя филиала; <kpp> - КПП филиала; <leg> - код организационно-правовой формы по общероссийскому классификатору организационно-правовых форм. Для просмотра контактных данных и адресов филиала следует воспользоваться ресурсами /orgs/{orgOid}/brhs/{branch_id}/ctts и /orgs/{orgOid}/brhs/{branch_id}/addrs соответственно. Структура этих ресурсов аналогична ресурсам головной организации
4.	/orgs/{orgOid}/ctts	Перечень контактов организации	Перечень контактов организации (в виде ссылок на ресурс c указанием {ctt_id}, содержащий данные о каждом контакте)
5.	/orgs/{orgOid}/ctts/{ctt_id}	Сведения об отдельной записи в перечне контактов организации	Контактные данные: <type> - тип записи, может иметь значения: - "PHN" - телефон; - "OFX" - факс; - "OEM" - электронная почта. <vrfStu> - сведения о "подтвержденности" контактов, может иметь значения: - "NOT VERIFIED" - не подтвержден; - "VERIFIED" - подтвержден. <value> - значение контакта
6.	/orgs/ {orgOid}/adders	Перечень адресов организации	Перечень адресов организации (в виде ссылок на ресурс c указанием {addr_id}, содержащий данные о каждом адресе)
7.	/otg/{orgOid}/addres/{addr_id}	Сведения об отдельной записи в перечне адресов организации	Контактные данные: <type> - тип записи, может иметь значения: - "OLG" - юридический адрес; - "OPS" - фактический адрес; <zipCode> - индекс; <countryId> - идентификатор страны; <addressStr> - адрес в виде строки (не включая дом, строение, корпус, номер квартиры); <building> - строение; <frame> - корпус; <house> - дом; <flat> - квартира; <fiasCode> - код ФИАС; <region> - регион; <city> - город; <district> - внутригородской район; <area> - район; <settlement> - поселение; <additionArea> - доп. территория; <additionAreaStreet> - улица на доп. территории; <street> - улица.
8.	/orgs/{orgOid}/vhls	Перечень транспортных средств	Перечень транспортных средств, которыми владеет данная организация
9.	/orgs/{orgOid}/vhls/{vhl-id}	Транспортное средство организации	<name> - имя автомобиля (например, марка или другое пользовательское описание); <numberPlate> - государственный регистрационный знак; <regCertificate> - данные свидетельства о государственной регистрации, включает в себя атрибуты: - <series> - серия свидетельства; - <number> - номер свидетельства.

Пример ответа с кратким наименованием организации (разрывы строки даны для удобства чтения):

Пример ответа с контактными данными об адресах организации при использовании возможностей встраивания*(35) (разрывы строки даны для удобства чтения):

Б.5 Предоставление списка участников организации

Для получения данных об участниках организации система-клиент должна направить по в https-адрес REST-API системы ЕСИА*(36) запрос методом GET. В запросе должен быть указан ресурс, содержащий необходимые данные. Идентификатор этого ресурса в ЕСИА имеет следующий вид для получения списка сотрудников организации необходимо использовать uri / orgs/ {orgOid}/emps/{prn_oid}, где:

- emps - перечень (коллекция) сотрудников организаций с данным {orgOid}; для определения orgOid соответствующей организации необходимо использовать атрибут orgOid, передающийся в утверждениях SAML;

- prn_oid - внутренний идентификатор физического лица в ЕСИА.

В запрос должен быть добавлен header с маркером доступа, позволяющим получить доступ к данному ресурсу (scope http://esia.gosuslugi.ru/org_emps с параметрами).

Пример запроса (вызов сервиса в среде разработки):

Данные, которые ЕСИА возвращает в ответ на запрос, представлены в таблице 8.

Таблица 8 - Параметры ответа на запрос об участниках организации

N	URI запрашиваемого ресурса	Описание ресурса	Предоставляемые данные
1.	/orgs/{orgOid}/emps	Перечень сотрудников организации	Перечень сотрудников данной организации (в виде ссылок на ресурс c указанием {prn_oid}, содержащий данные о каждом сотруднике)
2.	/orgs/{orgOid}/emps/{prn_oid}	Данные о сотруднике организации с идентификатором {prn_oid}	Данные о сотруднике: <position> - должность; <chief> - сведения о том, является ли сотрудник руководителем организации (в этом случае имеет значение "true") или нет ("false"); <orgOid> - идентификатор организации, сотрудником которой является пользователь; <brhOid> - идентификатор филиала организации, сотрудником которой является пользователь (если сотрудник присоединен к филиалу); <blocked> - признак блокировки сотрудника (имеет значение "true" или "false").

Для просмотра перечня сотрудников филиала организации необходимо указать в запросе параметр brhOid и значение идентификатора соответствующего филиала. Пример ссылки, по которой будет возвращен перечень сотрудников филиала с идентификатором 1004082214:

При отображении всех коллекций (orgs, emps) используется механизм paging.

Пример ответа на запрос сведений о перечне сотрудников организации с идентификатором 1000000000 (фрагмент, разрывы строк даны для удобства чтения):

Пример ответа с контактными данными о сотрудниках организации при использовании возможности встраивания*(37) (разрывы строки даны для удобства чтения):

Б.6 Предоставление сведений о вхождении пользователя в группы

Для получения данных о вхождении пользователя в группы организации система-клиент должна направить по в https-адрес REST-API системы ЕСИА*(38) запрос методом GET. В запросе должен быть указан ресурс, содержащий необходимые данные.

В запрос должен быть добавлен header с маркером доступа, позволяющим получить доступ к данному ресурсу - scope http://esia.gosuslugi.ru/org_emps с параметрами. Для доступа к полному перечню групп, владельцем которых является данная организация, необходим scope http://esia.gosuslugi.ru/org_grps.

Пример запроса (вызов сервиса в среде разработки):

Данные, которые ЕСИА возвращает в ответ на запрос, представлены в Таблица 9.

Таблица 9 - Параметры ответа на запрос о вхождении сотрудников организации в группы

N	URI запрашиваемого ресурса	Описание ресурса	Предоставляемые данные
1.	/orgs/{orgOid}/grps	Перечень групп организации	Перечень групп, владельцем которых является данная организация (в виде перечня строк grp_id - указывающих на мнемонику имеющихся в рамках данной организации групп). Для получения этого перечня групп запрос должен быть добавлен header с маркером доступа на scope http://esia.gosuslugi.ru/org_ful
2.	/orgs/{orgOid}/grps/{grp_id}	Данные о группе организации с мнемоникой {grp- id}	Данные о группе: <name> - имя; <description> - описание; <system> - сведения о том, является ли группа системной (в этом случае имеет значение "true") или нет ("false"). Также при запросе данных о конкретной группе возвращаются ссылки (links) на информационные системы, к которым относятся данные группы
3.	/orgs/{orgOid}/emps/{prn_oid}/grps	Перечень групп, членом которых является данный сотрудник	Перечень групп, членом которых является сотрудник с данным {prn_oid} (в виде перечня строк grp_id - указывающих на мнемонику имеющихся в рамках данной организации групп)

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

/orgs/{orgOid}/emps/{prn_oid}/grps/{grp_id}/{it_sys_id}, где it_sys_id - мнемоника информационной системы, в рамках которой действует данная группа. Пример ссылки на группу:

Данная ссылка означает, что пользователь с идентификатором 1000000105 как сотрудник организации 1000000224 включен в группу администраторов профиля организации (ORG_ADMIN) системы ЕСИА (мномоника ESIA). Выполнив запрос по данной ссылке можно получить краткую информацию о группе, которая включает в себя.

- мнемонику группы (grp_id);

- название группы (name);

- описание группы (description);

- признак того, что группа является системной (system);

- мнемоника системы-владельца группы (itSystem).

Например:

Если группа не является системной и не привязана ни к какой системе, то ссылка на нее имеет следующй формат:

/orgs/{orgOid}/emps/{prn_oid}/grps/{grp_id}

В кратких данных об этой группе атрибут "system" будет иметь значение "false".

При запросе перечня групп, членом которых является данный сотрудник, имеется возможность получить только те группы, которые относятся к определенной информационной системе. Для этого необходимо добавить условие на отбор групп выбранной системы (itSystemName), равное мнемонике данной системы. Пример запроса на получение групп системы ЕСИА (ESIA), в которые включен сотрудник:

Б.7 Управление данными организации

Программные интерфейсы на основе REST обеспечивают возможность управления данными организации для информационных систем этой организации. Обеспечена возможность:

- изменять данные профиля организации;

- управлять приглашениями должностным лицам, зарегистрированным в ЕСИА, на присоединение к учетной записи соответствующей организации;

- управлять служебными данными присоединенных сотрудников, а также блокировать и удалять должностных лиц организации;

- управлять полномочиями должностных лиц посредством изменения их членства в группах доступа;

- предоставлять и отзывать доступ к непубличным группам;

- добавлять и изменять данные филиалов организации.

Для осуществления данных операций система организации должна направить в https- адрес программного интерфейса ЕСИА запрос методом POST, PUT или DELETE. Данный запрос в общем виде включает в себя новые атрибуты организации. Кроме того, запрос должен включать в себя следующие данные:

- маркер доступа, выданный системе на scope (в зависимости от полномочий системы) с параметром org_oid, принимающим значение идентификатора организации;

- тег объекта - метка изменяемого объекта (эта метка указывается в заголовке "If-Match" и в ряде случаев в теле запроса в параметре "eTag");

Для получения информации о метке изменяемого объекта необходимо сделать стандартный запрос методом GET на получение изменяемого ресурса - конкретных данных организации (если последующий запрос делается на адрес контейнера, то требуется указывать тег контейнера).

Пример метки изменяемого объекта (выделено полужирным шрифтом):

Б.7.1 Изменение данных профиля организации

Программный интерфейс позволяет выполнить следующие операции:

- задать (изменить) организационно-правовую форму организации;

- задать, изменить и удалить служебные контакты организации (адрес электронной почты, номер телефона и факса).

- задать, изменить и удалить почтовый адрес организации;

- задать, изменить и удалить транспортные средства организации.

Б.7.1.1 Редактирование организационно-правовой формы организации

Для изменения организационно-правовой формы организации должен быть выполнен запрос методом POST на https-адрес программного интерфейса ЕСИА*(39). В заголовке запроса должен быть указан маркер доступа и тег объекта (метка, полученная при запросе ресурса https://esia-portal1.test.gosuslugi.ru/rs/orgs/{oid}). В тело запроса должны быть включены:

- <eTag> - тег изменяемого объекта (данных организации);

- <leg> - новый код организационно-правовой формы по общероссийскому классификатору организационно-правовых форм.

Пример запроса (разрывы строки даны для удобства чтения):

В качестве ответа ЕСИА возвращает данные организации с измененной организационно-правовой формой.

Б.7.1.2 Редактирование контактов организации

Для добавления контакта организации должен быть выполнен запрос методом POST на https-адрес программного интерфейса ЕСИА*(40). В заголовке запроса должен быть указан маркер доступа и тег контейнера с адресами (метка, полученная при запросе ресурса https://esia-portal1.test.gosuslugi.ru/rs/orgs/{oid}/ctts). В тело запроса должны быть включены:

- <type> - тип добавляемого контакта, принимает значение "OEM" для адреса электронной почты, "OPH" - телефона, "OFX" - факса;

- <value> - значение контакта.

Пример запроса (разрывы строки даны для удобства чтения):

Для изменения контакта организации должен быть выполнен запрос методом POST на https-адрес программного интерфейса ЕСИА*(41). В заголовке запроса должен быть указан маркер доступа и тег объекта (метка, полученная при запросе ресурса https://esia-portal1.test.gosuslugi.ru/rs/orgs/{oid}/ctts/{ctt_id}). В тело запроса должны быть включены:

- <eTag> - тег изменяемого объекта (контакта);

- <type> - тип изменяемого контакта, принимает значение "OEM" для адреса электронной почты, "OPH" - телефона, "OFX" - факса;

- <value> - значение контакта.

Пример запроса (разрывы строки даны для удобства чтения):

Изменение контакта возможно и без указания в URL запроса идентификатора контакта, в этом случае контакт будет изменен, но ему будет присвоен другой идентификатор.

Для удаления контакта организации должен быть выполнен запрос методом DELETE на https-адрес программного интерфейса ЕСИА*(42). В заголовке запроса должен быть указан маркер доступа и тег удаляемого объекта.

Пример запроса (разрывы строки даны для удобства чтения):

Б.7.1.3 Редактирование почтового адреса организации

Для добавления почтового адреса организации необходимо сделать запрос методом POST на https-адрес программного интерфейса ЕСИА*(43). Заголовок запроса должен включать в себя маркер доступа и тег контейнера адресов (метка, полученная при запросе ресурса https://esia-portal1.test.gosuslugi.ru/rs/orgs/{oid}/addrs).

Тело запроса должно включать следующие данные (указываются все данные, которые должны отображаться в адресе этого типа):

- тип адреса (type), принимает значение "OPS";

- регион (region);

- код ФИАС (fiasCode);

- строка адреса (addressStr), например, "Москва город, Тверская улица";

- идентификатор страны (countryId), для России - "RUS";

- почтовый индекс (zipCode);

- улица (street);

- дом (house);

- квартира (flat);

- корпус (frame);

- строение (building).

Пример запроса (разрывы строки даны для удобства чтения):

Изменение адреса осуществляется по аналогии с добавлением, недопустимо делать запрос с указанием конкретного идентификатора адреса.

Для удаления почтового адреса организации необходимо сделать запрос методом DELETE на https-адрес программного интерфейса ЕСИА*(44). Заголовок запроса должен включать в себя маркер доступа и тег удаляемого адреса (метка, полученная при запросе ресурса https://esia-portal1.test.gosuslugi.ru/rs/orgs/{oid}/addrs/{addr_id}).

Пример запроса (разрывы строки даны для удобства чтения):

Б.7.1.4 Управление транспортными средствами организации

Для добавления записи о транспортном средстве необходимо сделать запрос на https- адрес программного интерфейса ЕСИА методом POST*(45). Заголовок запроса должен включать в себя маркер доступа, тег контейнера транспортных средств (метка, полученная при запросе ресурса https://esia-portal1.test.gosuslugi.ru/rs/orgs/{oid}/vhls).

Тело запроса должно включать следующие данные:

- <name> - название транспортного средства;

- <numberPlate> - государственный номерной знак;

- <regCertificate> - данные свидетельства о регистрации:

- <series> - серия;

- <number> - номер.

Пример запроса:

Для изменения записи о транспортном средстве необходимо сделать запрос на https-адрес программного интерфейса ЕСИА методом POST*(46). Заголовок запроса должен включать в себя маркер доступа, тег записи транспортного средства (метка, полученная при запросе ресурса https://esia-portal1.test.gosuslugi.ru/rs/orgs/{oid}/vhls/{vhl-id}).

Тело запроса должно включать следующие данные:

- <eTag> - тег записи транспортного средства;

- <name> - название транспортного средства;

- <numberPlate> - государственный номерной знак;

- <regCertificate> - данные свидетельства о регистрации:

- <series> - серия;

- <number> - номер.

Пример запроса (разрывы строки даны для удобства чтения):

Для удаления записи о транспортном средстве необходимо сделать запрос на https-адрес программного интерфейса ЕСИА методом DELETE*(47). Заголовок запроса должен включать в себя маркер доступа, тег записи транспортного средства (метка, полученная при запросе ресурса https://esia-portal1.test.gosuslugi.ru/rs/orgs/{oid}/vhls/{vhl-id}).

Пример запроса (разрывы строки даны для удобства чтения):

Б.7.2 Управление приглашениями должностным лицам, зарегистрированным в ЕСИА, на присоединение к учетной записи соответствующей организации

Программный интерфейс ЕСИА позволяет выполнять следующие функции:

- просмотр отправленных, но не принятых приглашений;

- формирование нового приглашения;

- отзыв ранее отправленного приглашения.

Для просмотра отправленных приглашений необходимо сделать запрос на https-адрес программного интерфейса ЕСИА методом GET*(48). Заголовок запроса должен включать в себя маркер доступа. Пример запроса:

В качестве ответа ЕСИА возвращает перечень приглашений на присоединение к данной организации. Пример ответа:

Для получения данных об отдельном приглашении необходимо выполнить запрос методом GET по адресу с данными конкретного приглашения. Каждое приглашение описывается следующими параметрами:

- <invtId> - идентификатор приглашения;

- <eTag> - тег записи приглашения;

- <email> - адрес, на который было отправлено приглашение;

- <firstName> - имя приглашаемого сотрудника;

- <lastName> - фамилия приглашаемого сотрудника;

- <middleName> - отчество приглашаемого сотрудника (необязательно);

- <snils> - СНИЛС приглашаемого сотрудника (необязательно);

- <status> - статус приглашения (принимает значение "A" (активно) и "I" (инициировано, но не отправлено));

- <createdOn> - дата отправления приглашения;

- <groups> - группа, в которую будет включен пользователь (указывается мнемоника группы) (необязательно).

Пример описания приглашения:

Чтобы отправить приглашение, необходимо сделать запрос на https-адрес программного интерфейса ЕСИА методом PUT*(49). Заголовок запроса должен включать в себя маркер доступа, а тело запроса должно включать следующие данные:

- <email> - адрес, на который отправлять приглашение;

- <firstName> - имя приглашаемого сотрудника;

- <lastName> - фамилия приглашаемого сотрудника;

- <middleName> - отчество приглашаемого сотрудника (необязательно);

- <snils> - СНИЛС приглашаемого сотрудника (необязательно).

Пример запроса (разрывы строки даны для удобства чтения):

Чтобы удалить приглашение, необходимо сделать запрос на https-адрес программного интерфейса ЕСИА методом DELETE*(50). Заголовок запроса должен включать в себя маркер доступа. Пример запроса:

Б.7.3 Управление служебными данными присоединенных сотрудников, а также блокировка и удаление должностных лиц организации

Для изменения данных сотрудника организации, в том числе - изменения признака блокировки - необходимо сделать запрос на https-адрес программного интерфейса ЕСИА методом POST*(51). Заголовок запроса должен включать в себя маркер доступа, тег данных сотрудника (метка, полученная при запросе ресурса https://esia- portal1.test.gosuslugi.ru/rs/orgs/{oid}/emps/{emp_id}).

Тело запроса должно включать следующие данные (все параметры обязательны):

- <eTag> - тег данных сотрудника;

- <position> - должность сотрудника;

- <corporateContact> - адрес электронной почты сотрудника;

- <blocked> - признак блокировки ("false" - не заблокирован, "true" - не заблокирован). Если какой-либо параметр не будет указан, то он будет очищен.

Пример запроса (разрывы строки даны для удобства чтения):

Для удаления сотрудника необходимо сделать запрос на https-адрес программного интерфейса ЕСИА методом DELETE*(52). Заголовок запроса должен включать в себя маркер доступа. Пример запроса:

Б.7.4 Управление полномочиями должностных лиц посредством изменения их членства в группах доступа

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

Добавление сотрудника в группу осуществляется запросом методом PUT на следующий https-адрес программного интерфейса ЕСИА:

Параметр <it_sys_id> - мнемоника информационной системы, в рамках которой создана данная группа. Пример запроса:

Данный запрос включает сотрудника с идентификатором 1000023747 в группу "Администраторы профиля организации", принадлежащей ЕСИА.

Для исключения сотрудника из группы нужно вызвать программный интерфейс ЕСИА по указанному выше адресу (адрес для добавления сотрудника в группу) методом DELETE. Пример запроса:

Б.7.5 Управление доступом к непубличным группам

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

Пусть организация с идентификатором 1000000001 - владелец приватной группы RA.USR_CFM ("Операторы системы подтверждения личности"). С помощью программного интерфейса эта организация может:

- посмотреть перечень организаций, которым предоставлена данная группа;

- дать некоторой организации доступ к данной группе;

- отозвать у организации доступ к группе.

Для просмотра списка организаций, которым предоставлен доступ к указанной группе, необходимо выполнить запрос методом GET в адрес программного интерфейса ЕСИА*(53). В заголовке запроса должен быть указан маркер доступа. Имеется возможность вызвать этот сервис с функцией встраивания (embed), чтобы сразу был виден перечень организаций, которым предоставлен доступ. Пример запроса:

Пример ответа, из которого видно, что доступ предоставлен четырем организациям (указаны их ОГРН и идентификаторы разрешений):

Для добавления организации в этот перечень необходимо выполнить запрос методом POST в адрес этого же программного интерфейса ЕСИА*(54). В заголовке запроса должен быть указан маркер доступа. В теле запроса должны быть указаны параметры:

- <ogrn> - ОГРН организации;

- <rqCfm> - признак, определяющий, что включение в группу требует персонального согласования со стороны владельца группа (для этого он должен иметь значение "true").

Пример запроса (разрывы строки даны для удобства чтения):

Для отзыва доступа необходимо выполнить запрос методом DELETE по адресу конкретного разрешения. Пример запроса:

Б.7.6 Добавление и изменение данных филиалов организации

Программный интерфейс ЕСИА позволяет выполнить следующие операции:

- добавить филиал организации;

- изменить данные филиала организации.

Для добавлен