Сервис «N3.Health.Сервис электронной подписи»

«N3.Health.СЭП» предназначен для реализации процесса подписания документов с пациентом (клиентом) юридического лица как простой электронной подписью, так и иными видами электронной подписи, в т.ч. квалифицированной.

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

Для осуществления интеграции требуется создавать комплект документов в формате docx, PDF и файлы открепленной подписи (sig, sign, p7ks) при необходимости.

Сценарий использования предполагает создание комплекта документов на стороне ИС и осуществления их отправки в сервис СЭП – одним post запросом /sep/api/signing с указанием типа доставки: (на данный момент только SMS) и указание на необходимость авторизации через ЕСИА (для ИДС, Телемедицинских консультаций и иных сценариев требующих подписание с использованием ЕСИА).

МЕТОДЫ POST

Эндпоинт https://b2b-demo.n3health.ru/sep/api

• Метод POST /sep/api/signing – направление комплекта документов на подпись в сервис СЭП.

Метод осуществляет немедленную доставку ссылки с кодом и паролем указанным способом доставки и возвращает trackingId отправления или ошибку.

Рекомендуем сохранять связь ID отправления СЭП (trackingId) с карточкой Пациента в используемой информационной системе для осуществления запросов GET методами статуса и направленного комплекта документов с визуализацией подписи в дальнейшем.

Пакетное подписание — при передачи нескольких документов, будет осуществлено пакетное подписание всех входящих в запрос документов

Тарификация осуществляется за пакеты (1 документ – 1 пакет, 5 документов в запросе – 1 пакет).

АВТОРИЗАЦИЯ

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

POST /sep/api/signing

HTTP/1.1

Host: b2b-demo.n3health.ru
Authorization: 44556afd-0e84-b847-2312-75999668f777
X-Id-Lpu: 12346afd-0e84-b847-2322-75999668f500a
Content-Type: multipart/form-data; boundary=razdelitel

—razdelitel
Content-Disposition: form-data; name=»meta»
Content-Type: application/json; charset=utf-8

{
  «organization«: {
    «idLpu»: «d39269b3-289d-4c5d-aa33-b3c945ad22ee»,
    «inn»: «1234567890»,
    «ogrn»: «1234567890123»,
    «name»: «Городская больница №1»,
    «telecom»: [
      { «system»: «Email», «value»: «email@example.com» },
      { «system»: «Telephone», «value»: «+7XXXXXXXXXX» }
    ]
  },
  «practitioner«: {
    «mrProxyNumber»: «12-52884аАА»,
    «familyName»: «Иванов»,
    «givenName»: «Иван»,
    «middleName»: «Иванович»,
    «userIdLpu»: «doc-123»,
    «telecom»: [
      { «system»: «Email», «value»: «email@example.com» },
      { «system»: «Telephone», «value»: «+7XXXXXXXXXX» }
    ]
  },
  «patients»: [
    {
      «idPatientMis»: «patient-456»,
      «mpiId»: «123e4567-e89b-12d3-a456-426614174000»,
      «familyName»: «Петров»,
      «givenName»: «Пётр»,
      «middleName»: «Петрович»,
      «birthDate»: «1980-01-01»,
      «sex»: «male»,
      «telecom»: [
        { «system»: «Email», «value»: «email@example.com» },
        { «system»: «Telephone», «value»: «+7XXXXXXXXXX» }
      ],
      «documentDto»: [
        {
          «providerName»: «ОВД»,
          «issuedDate»: «2010-05-15»,
          «docN»: «1234»,
          «docS»: «123456»,
          «documentName»: «Паспорт гражданина РФ»,
          «idDocumentType»: 14
        }
      ]
    }
  ],
  «medDocument»: {
    «esiaAuth»: true,
    «attachments»: [
      { «partName»: «file0», «documentType»: «2» },
      { «partName»: «file1», «documentType»: «3» },
      { «partName»: «file2», «documentType»: «4» }
    ]
  },
  «delivery»: [«sms»],
  «welcomeTG»: «ABCD1234»
}

—razdelitel
Content-Disposition: form-data; name=»file0″; filename=»document.pdf»
Content-Type: application/pdf

<бинарные данные PDF документа>

—razdelitel
Content-Disposition: form-data; name=»file1″; filename=»document.docx»
Content-Type: application/vnd.openxmlformats-officedocument.wordprocessingml.document

<бинарные данные DOCX документа>

—razdelitel
Content-Disposition: form-data; name=»file2″; filename=»signature.p7s»
Content-Type: application/pkcs7-signature

<бинарные данные файла подписи>

—razdelitel—

Ответ сервера

Успех:

HTTP/1.1 201 Created
Location: /sep/api/signing/123e4567-e89b-12d3-a456-426614174000
Content-Type: application/json

{
  «status»: «created»,
  «trackingId»: «123e4567-e89b-12d3-a456-426614174000»
}

Ошибка:

HTTP/1.1 400 Bad Request
Content-Type: application/json

{
  «status»: «error»,
  «trackingId»: «123e4567-e89b-12d3-a456-426614174000»,
  «errorCode»: «INVALID_ATTACHMENT»,
  «errorMessage»: «Файл file1 отсутствует в multipart-теле»
}

* Все варианты ошибок ниже

1. Заголовок (Headers)

2. Организация (organization)

3. Медицинский работник (practitioner)

4. Пациенты (patients)

Массив объектов, где каждый объект содержит:

Массив объектов (обязательно хотя бы 1 документ, предпочтительнее передавать номер СНИЛС» (код документа «223»)):

5. Медицинский документ (medDocument)

6. Доставка (delivery)

Важные примечания:

1. Для полиса ДМС (idDocumentType: 240) обязательно указать второй документ (например, паспорт). Предпочтительнее паспорт.
2. Если esiaAuth: true, пациент должен авторизоваться через ЕСИА для подписи.
3. Все даты — в формате ISO 8601 (YYYY-MM-DD).

Обработка ошибок

GET /sep/api/signing
Authorization: 44556afd-0e84-b847-2322-75999668f590
X-Id-Lpu: 0453937e-fad5-402d-aacb-3ce6df2bf6fe

GET /sep/api/signing?idPatientMis=123e4567-e89b-12d3-a456-426614174000
Authorization: 44556afd-0e84-b847-2322-75999668f590
X-Id-Lpu: 0453937e-fad5-402d-aacb-3ce6df2bf6fe

# Поиск по idPatientMis
GET /signing?idPatientMis=Красносолнышкин

# Поиск по фамилии
GET /signing?familyName=Красносолнышкин

# Поиск по ФИО
GET /signing?familyName=Иванов&givenName=Павел&middleName=Святославович

# Поиск по контактным данным
GET /signing?email=examplename@anydomain.net
GET /signing?telephone=79262119529

# Комбинированный поиск
GET /signing?familyName=Иванов&givenName=Павел&telephone=79262119529

# С пагинацией
GET /signing?familyName=Иванов&limit=20&offset=40

"data": [
        {
            "id": "660b3057-a0dc-4be1-a309-5cd730bf6bf3",
            "status": {
                "code": 208,
                "name": "Успешно. Подписан всеми - обработка",
                "message": "Успешно. Подписан всеми - обработка",
                "description": "Успешно. Подписан всеми - обработка"
            },
            "updatedAt": "2025-11-10T14:24:42.604Z",
            "practitioner": {
                "userIdLpu": "doc-123",
                "status": {
                    "code": 204,
                    "description": "Получатель подписал документ"
                }
            },
            "patients": [
                {
                    "idPatientMis": "",
                    "status": {
                        "code": 204,
                        "description": "Получатель подписал документ"
                    }
                }
            ]
        },
        {
            "id": "2eb002f0-5e9e-4ddd-886e-b5c3bcccdb28",
            "status": {
                "code": 208,
                "name": "Успешно. Подписан всеми - обработка",
                "message": "Успешно. Подписан всеми - обработка",
                "description": "Успешно. Подписан всеми - обработка"
            },
            "updatedAt": "2025-11-10T12:16:43.420Z",
            "practitioner": {
                "userIdLpu": "doc-123",
                "status": {
                    "code": 204,
                    "description": "Получатель подписал документ"
                }
            },
            "patients": [
                {
                    "idPatientMis": "",
                    "status": {
                        "code": 204,
                        "description": "Получатель подписал документ"
                    }
                }
            ]
        }
]

{
    "data": {
        "id": "2eb002f0-5e9e-4ddd-886e-b5c3bcbbdb28",
        "status": "208",
        "createdAt": "2025-11-10T12:15:27.787Z",
        "practitioner": {
            "mrProxyNumber": "10-test-223",
            "familyName": "Иванов",
            "givenName": "Иван",
            "middleName": "Иванович",
            "userIdLpu": "doc-123",
            "status": {
                "code": 204,
                "description": "Получатель подписал документ"
            }
        },
        "patients": [
            {
                "idPatientMis": "sepTestProd07102025",
                "familyName": "Виноградов",
                "givenName": "Вячеслав",
                "middleName": "Александрович",
                "status": {
                    "code": 204,
                    "description": "Получатель подписал документ"
                }
            }
        ],
        "medDocument": {
            "attachments": [
                {
                    "content": "JVB....
         }
            ]
        }
    }
}