Подпись документов через eGov

Android, iPhone и QR на компьютере. Подпись выполняется в eGov Mobile или eGov Business через SIGEX. Ключ ЭЦП и пароль не передаются в DocHub.

Поддерживается один PDF до 5 МиБ. Перед запуском пользователь должен согласиться на передачу документа через SIGEX в eGov. Документ должен ожидать подписи этого участника, с указанным ИИН/БИН и соблюдённой очередностью.

Авторизация

Во всех запросах передайте Authorization: Bearer USER_JWT либо X-Sign-Token: PERSONAL_SIGN_TOKEN из персональной ссылки подписанта. Токен передаётся только заголовком. Общий API-ключ не разрешает подписание за человека.

1. Создать сессию

POST /api/signing/sigex/start

{ "doc_id": "DOCUMENT_UUID" }

Пример:

curl https://doc-hub.net/api/signing/sigex/start \
  -H 'Content-Type: application/json' \
  -H 'Authorization: Bearer USER_JWT' \
  --data '{"doc_id":"DOCUMENT_UUID"}'

Ответ:

{
  "operation_id": "OPERATION_UUID",
  "doc_id": "DOCUMENT_UUID",
  "status": "waiting",
  "expires_at": "ISO_DATETIME",
  "qr_code": "BASE64_PNG",
  "mobile_url": "HTTPS_LINK_FROM_EGOV",
  "business_url": "HTTPS_LINK_FROM_EGOV"
}

Покажите QR как data:image/png;base64,…, либо откройте соответствующую ссылку на этом телефоне. При повторном запуске активной сессии возвращается её текущий статус: QR-поля доступны только для waiting.

2. Получить результат

GET /api/signing/sigex/status?doc_id=DOCUMENT_UUID&operation_id=OPERATION_UUID

Передавайте operation_id из ответа /start. Опрашивайте раз в 4 секунды, включая возврат приложения на передний план. Ограничивайте повторы при ошибках сети.

curl 'https://doc-hub.net/api/signing/sigex/status?doc_id=DOCUMENT_UUID&operation_id=OPERATION_UUID' \
  -H 'Authorization: Bearer USER_JWT'

Статус	Значение
waiting	Ожидание пользователя в eGov
verifying / saving	Сервер проверяет CMS и сохраняет результат
signed	Подпись проверена и сохранена
canceled / expired / failed	Операция завершена без подтверждения подписи; при failed есть error

{
  "operation_id": "OPERATION_UUID",
  "doc_id": "DOCUMENT_UUID",
  "status": "signed",
  "success": true,
  "signature_id": "SIGNATURE_UUID",
  "all_signed": false,
  "doc_status": "reviewing"
}

all_signed: false означает, что подпись этого участника сохранена, но есть другие участники маршрута. Возврат из eGov сам по себе не подтверждает подпись.

Запрос только по документу

GET /api/signing/sigex/status?doc_id=DOCUMENT_UUID также поддерживается: возвращает последнюю операцию того же пользователя/персонального токена из памяти текущего сервера. Если её нет — 404 SIGEX_OPERATION_NOT_FOUND. Для восстановления сохранённой подписи после перезапуска нужен явный operation_id. Пустой или некорректный UUID операции — 400 INVALID_OPERATION_ID.

3. Отменить ожидание

POST /api/signing/sigex/cancel

{ "doc_id": "DOCUMENT_UUID", "operation_id": "OPERATION_UUID" }

Отменяет локальную операцию DocHub до сохранения. Не отзывает уже созданную в eGov ЭЦП. Если сохранение уже началось — 409 SIGNATURE_SAVING, продолжайте проверять статус.

Ошибки и восстановление

HTTP 200 при опросе означает, что состояние прочитано. Документ подписан только при status: signed, после проверки и сохранения CMS. При ошибке вернутся этап и причина:

{
  "operation_id": "OPERATION_UUID",
  "doc_id": "DOCUMENT_UUID",
  "status": "failed",
  "error": "SIGEX_INVALID_RESPONSE",
  "error_stage": "signature",
  "error_reason": "DOCUMENT_ID_MISMATCH"
}

Этапы: upload — передача PDF, signature — получение ответа, document_check — повторная проверка документа и доступа, verification — криптопроверка, saving — сохранение. Передайте поддержке UUID операции, этап и код ошибки. Старые QR и ссылки после истечения срока недействительны: создайте новую операцию через /start.

401/403 — нет доступа; 409 — документ или маршрут изменился; 413 — PDF слишком большой; 415 — не PDF; 429 — лимит; 503 — интеграция недоступна. При SIGNATURE_REJECTED проверка сертификата, OCSP, ИИН/БИН или файла не пройдена.

Сохраняйте UUID операции и проверяйте статус после возврата в приложение. После перезапуска сервера незавершённую сессию нужно начать заново; уже сохранённая подпись восстанавливается из базы. Сначала проверяйте результат, затем предлагайте повторное подписание.

Документация транспорта SIGEX