API: общее


POST /api/exported - получение идентификаторов документа и подписи по ранее экспортированной подписи документа

В передаваемой подписи допускается наличие метки времени TSP (signature-time-stamp) и квитанции OCSP (revocation-values). Важно чтобы метка времени и квитанция, в том случае, если они присутствуют, были именно теми же, которые зарегистрированы в сервисе. Это обусловлено тем, что метка времени и квитанция фиксируют момент подписания и, в том случае, если были получены другие метка времени и квитанция, эти данные не будут совпадать с теми, которые зарегистрированы в сервисе.

Запрос (Content-Type необходимо установить в application/json):

{
  "signType": "cms",
  "signature": "signature"
}
  • signType - опциональное поле, тип регистрируемой подписи, поддерживается два строковых значения "cms" и "xml", по умолчанию "cms";
  • signature - в случае CMS это должна быть подпись в кодировке DER дополнительно закодированная в base64, либо в кодпировке PEM без дополнительного кодирования, в случае XML - текстовое представление XML.

Ответ:

{
  "documentId": "lQsqLBaS4nQAIIMm",
  "signId": 1
}
  • documentId - уникальный идентификатор документа;
  • signId - уникальный идентификатор подписи.

POST /api/parseDDC?registerUnknownSignatures=false - разбор карточки электронного документа

  • registerUnknownSignatures=false - опционально, определяет должен ли сервис регистрировать новые неизвестные подписи, по умолчанию false.

Сервис выполнит следующее:

  • выполнит разбор полученного файла, удостоверится в том, что это файл карточки электронного документа;
  • проверит зарегистрированы ли в SIGEX все вложенные подписи;
  • в том случае, если были обнаружены еще не зарегистрированные вложенные подписи и registerUnknownSignatures=true, попробует их зарегистрировать, вернет ошибку в том случае, если не удалось зарегистрировать какую-либо из них;
  • в том случае, если были обнаружены еще не зарегистрированные вложенные подписи и registerUnknownSignatures=false, вернет ошибку;
  • удостоверится в том, что все вложенные подписи относятся к одному и тому же зарегистрированному в SIGEX документу;
  • удостоверится в том, что вложенные подписи являются подписями именно под вложенным в карточку документом (то есть что не произошло подмены или изменения документа);
  • выполнит проверку каждой подписи на момент ее регистрации в системе используя сохраненные данные OCSP и TSP;
  • вернет идентификатор электронного документа, идентификаторы подписей и извлеченный вложенный подлинник электронного документа.

Запрос должен содержать HTTP заголовок Content-Type=application/octet-stream.

В качестве тела запроса следует передать файл Карточки электронного документа.

При обработке этого API сервис автоматически выполняет архивирование подписанных данных в том случае, если в настройках хотя бы одной из подписавших документ сторон включено архивирование и, при этом, не превышена квота.

Ответ:

{
  "documentId": "lQsqLBaS4nQAIIMm",
  "signIds": [1, 2],
  "document": "MTEK",
  "dataArchived": false
}
  • documentId - идентификатор документа;
  • signIds - массив идентификаторов подписей;
  • document - файл извлеченного подлинника подписанного документа в виде base64 строки;
  • dataArchived - информирует о том, находятся ли подписанные данные в архиве.

POST /api/checkPDFForDDC - проверка PDF на возможность визуализации в карточке

Так как для визуализации PDF файлов в Карточках электронных документов сервису необходимо выполнять специфические манипуляции с содержимым и структурой этих PDF файлов, то необходимо быть уверенными в том, что каждый конкретный PDF файл обрабатывается сервисом корректно. Такая проверка выполняется сервисом в начале обработки POST /api/{id}/buildDDC?fileName=X&withoutDocumentVisualization=false&withoutSignaturesVisualization=false&withoutQRCodesInSignaturesVisualization=false&withoutID=false&qrWithIDLink=false&withLabelVerified=false&language=ru - формирование карточки электронного документа, но если она завершается ошибкой возникает неприятная ситуация - электронный документ (PDF файл) уже подписан ЭЦП, но сформировать из него Карточку невозможно.

Для того, чтобы удостовериться в том, что из PDF после подписания точно получится сформировать Карточку, можно воспользоваться этим API. Он сформирует Карточку с пробными данными.

Запрос должен содержать HTTP заголовок Content-Type=application/octet-stream.

В качестве тела запроса следует передать PDF файл.

Ответ:

{
  "sampleDDC": "MTEK"
}
  • sampleDDC - сформированная Карточка с пробными данными.

GET /api/idFromFileName/?name=XXX - получить идентификатор SIGEX из имени файла

  • name=XXX - имя файла из которого необходимо извлечь идентификатор.

Ответ:

{
  "documentId": "lQsqLBaS4nQAIIMm"
}
  • documentId - полученный из имени файла идентификатор документа.

GET /api/normalizeId/{specialId} - получить нормализованный идентификатор и его тип по специальному идентификатору

  • specialId - специальный идентификатор.

Ответ:

{
  "id": "lQsqLBaS4nQAIIMm",
  "type": "document"
}
  • id - нормализованный идентификатор;
  • type - тип идентификатора, может быть:
    • "document" - идентификатор документа.

GET /api/externalServicesStats - статистика доступности сторонних сервисов

Сервис постоянно поддерживает текущую статистику доступности различных сторонних сервисов, таких как OCSP и TSP НУЦ РК. Статистика формируется за некий определенный промежуток времени, обычно от 10 до 30 минут.

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

  • "white" - наш сервис в последнее время не обращался к данному сервису, статистика не доступна;
  • "green" - в последнее время все обращения к сервису были успешны;
  • "yellow" - в последнее время были как успешные, так и не успешные (включая сетевые проблемы и неожиданные коды или ответы) обращения к сервису;
  • "red" - в последнее время были только не успешные (включая сетевые проблемы и неожиданные коды или ответы) обращения к сервису.

Ответ:

[
  {
    "protocol": "ocsp",
    "url": "https://ocsp.pki.gov.kz",
    "status": "yellow"
  },
  {
    "protocol": "tsp",
    "url": "https://tsp.pki.gov.kz",
    "status": "green"
  }
]
  • protocol - протокол, такой как "ocsp", "tsp", либо какой-то другой;
  • url - URL стороннего сервиса;
  • status - состояние доступности в последнее время, может быть "white", "green", "yellow" или "red".

GET /api/strings - перечень известных строк

Ответ:

{
  "errorMessages": {
    "Access denied": {
      "ru": "доступ запрещен",
      "kk": "қосылуға мүмкіндік жоқ",
      "description": "сервис возвращает эту ошибку при попытке выполнить действие, для выполнения которого у текущего аутентифицированного пользователя или ИС не достаточно прав"
    },
    ...
  },
  "consts": {
    "OIDs": {
      "1.2.398.3.10.1.1.1.1": {
        "ru": "Ключ ГОСТ 34.310-2004",
        "kk": "МЕМСТ 34.310-2004 кілт"
      },
      ...
    },
    "policyOIDs": {
      "1.2.398.3.3.2.1": {
        "ru": "Политика применения регистрационных свидетельств электронной цифровой подписи юридических лиц Республики Казахстан",
        "kk": "Қазақстан Республикасы заңды тұлғаларының электрондық цифрлық қолтаңбасын тіркеу куәліктерін қолдану саясаты"
      },
      ...
    },
    "timeStampPolicyOIDs": {
      "1.2.398.3.3.2.6.1": {
        "ru": "Политика для подписи квитанции метки времени на алгоритме ГОСТ 34.310-2004 с OID 1.2.398.3.10.1.1.1.2",
        "kk": "OID 1.2.398.3.10.1.1.1.2 бар ГОСТ 34.310-2004 алгоритмінде уақыт белгісі түбіртегіне қол қоюға арналған саясат"
      },
      ...
    },
    "extKeyUsageOIDs": {
      "1.2.398.3.3.4.1.1": {
        "ru": "Физическое лицо",
        "kk": "Жеке тұлға"
      },
      ...
    },
    "signatureAlgorithmOIDs": {
      "1.2.398.3.10.1.1.1.2": {
        "ru": "Подпись ГОСТ 34.310-2004",
        "kk": "МЕМСТ 34.310-2004 қолтаңбасы"
      },
      ...
    },
    "ncaAuthorityOIDs": {
      "1.2.398.3.3.4.1.2.1": {
        "ru": "Первый руководитель юридического лица/совместное предпринимательство",
        "kk": "Заңды тұлғаның бірінші басшысы/бірлескен кәсіпкерлік"
      },
      ...
    },
    "keyStorageOIDs": {
      "1.2.398.3.3.5": {
        "ru": "Хранилище ключей",
        "kk": "Кілттер қоймасы"
      },
      ...
    },
    "keyUsages": {
      "cRLSign": {
        "ru": "Подписание CRL",
        "kk": "CRL қол қою"
      },
      ...
    }
  }
}
  • errorMessages - реестр всех сообщений об ошибках, которые может возвращать сервис в виде объекта, поля которого - строки сообщений, а значения содержат перевод и описание;
  • consts - реестр известных OIDов и других специфических строк, поля - строки, значения содержат перевод:
    • OIDs - все известные OIDы,
    • policyOIDs - OIDы политик сертификатов,
    • timeStampPolicyOIDs - OIDы политик TSP,
    • extKeyUsageOIDs - OIDы значений расширенного использования ключа,
    • signatureAlgorithmOIDs - OIDы алгоритмов ЭЦП,
    • ncaAuthorityOIDs - OIDы полномочий НУЦ,
    • keyStorageOIDs - OIDы типов хранилищ ключей ЭЦП,
    • keyUsages - константы использования ключа.

GET /api/version - версия сервиса

Ответ:

{
  "version":"vX.X.X",
  "buildTimeStamp":"XXXXXXXXXX",
  "licenseOwner":"BIN200240002381",
  "licenseUntil":"2030-09-04"
}
  • version - версия сервиса;
  • buildTimeStamp - время сборки сервиса в секундах с UNIX Epoch;
  • licenseOwner - владелец лицензии (BIN);
  • licenseUntil - дата окончания действия лицензии (UTC).

"Множество" ЖШС-нде 2026 жылы әзірленген