CleanSign API

REST-API сервиса CleanSign для проверки электронных подписей (ЭП/ЭЦП). Принимает документы и файлы подписи через multipart/form-data, возвращает JSON со сведениями о подписантах, цепочкой сертификатов и классификацией подписи. Использует тот же движок проверки, что и веб-форма на главной странице. Подходит для пакетной обработки документов и мониторинга срока действия сертификатов; готовых коннекторов к учётным системам и операторам ЭДО сервис не поставляет — встраивание выполняется на стороне клиента.

Какие проверки выполняются

• Соответствие хеша документа подписанному атрибуту messageDigest — отсекает подмену подписанного содержимого.
• Криптографическая проверка подписи (ГОСТ Р 34.10-2012, RSA, ECDSA).
• Построение цепочки сертификатов до закреплённого trust-anchor (ГУЦ Минцифры) в режиме fail-closed.
• Проверка привязки signingCertificateV2 (RFC 5126), исключающая подмену сертификата подписанта.
• Проверка аккредитации УЦ-эмитента в реестре Минцифры на текущий момент и на момент подписания.
• Опционально: проверки OCSP и CRL, верификация контр-подписей и меток времени CAdES (профили BES — A).
• Классификация подписи по 63-ФЗ — КЭП (она же УКЭП — усиленная квалифицированная), НЭП (усиленная неквалифицированная) или иная — с указанием класса средства ЭП (КС1, КС2, КС3) и СКЗИ.

Поддерживаемые форматы

• CMS / PKCS#7 — отделённая подпись в виде самостоятельного файла рядом с документом. Расширения: .sig, .sgn, .sign, .p7s, .bin (плюс числовые суффиксы вида .sig2, .sig.001). Документом может быть любой файл — .pdf, .docx, .xlsx, .doc, .xml, .txt, .html, .rtf и любой бинарный.
• CAdES — те же расширения, что и CMS; распознаются профили BES, EPES, T, C, X-L, X Long Type 1, A.
• PAdES — встроенная подпись в PDF (.pdf): чтение /ByteRange, /Contents, поддержка нескольких подписей в одном документе и словаря /DSS (DSS dictionary).
• S/MIME — почтовые сообщения multipart/signed. Расширения: .eml, .p7m, .mime, .msg.
• XMLDSig / XAdES — XML-файлы (.xml) с алгоритмами ГОСТ или RSA; поддерживаются преобразования c14n, exc-c14n и enveloped-signature.
• OOXML — .docx, .xlsx, .pptx с поддержкой RelationshipTransform по ECMA-376 §13.
• ZIP-архивы — .zip распаковывается на один уровень: документы и подписи внутри сопоставляются по содержимому (хеш) и по имени; поддержка имён в кодировке CP866. Зашитые внутрь архива другие архивы хранятся как опаковые байтовые блобы и отдельно не распаковываются. Применяются защитные лимиты: число записей, размер записи, кумулятивный размер, коэффициент сжатия (zip-bomb), глубина вложенности папок и потенциальной рекурсии (см. CleanSign:Limits).

Версионирование

Канонические пути API располагаются под префиксом /api/v{N}/. Контракт v1 зафиксирован: в существующие ответы могут добавляться новые необязательные поля, но имена и типы существующих полей не изменяются и не удаляются. Несовместимое изменение (переименование поля, изменение типа, удаление секции ответа) выпускается параллельной версией /api/v2; /api/v1 продолжает работать в прежнем виде.

Незаверсионированные пути /api/verify и /api/cert/check — это псевдонимы, ведущие на текущую актуальную версию. Они сохраняются для обратной совместимости со старыми интеграциями. В новых интеграциях используйте только версионированные пути, чтобы зафиксировать контракт.

Аутентификация

Доступ к API авторизуется по токену. Токен выдаётся при подключении и передаётся в заголовке Authorization: Bearer <token>. Запросы без валидного токена отклоняются с кодом 401 Unauthorized.

Все запросы выполняются по HTTPS. Максимальный размер тела запроса — 200 МБ.

Коды ошибок

POST /api/v1/verify

Проверяет одну или несколько связок «документ + подпись». Принимает ZIP-архивы (распаковываются рекурсивно), пары вида «doc.pdf + doc.pdf.sig», PDF со встроенной PAdES-подписью, .eml с S/MIME, файлы .docx, .xlsx, .pptx и .xml (XMLDSig).

Параметры запроса (query или поле формы)

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

curl -X POST 'https://api.cleanvoice.ru/cleansign/api/v1/verify?returnCertificateFile=true' \
  -F 'files=@invoice.pdf' \
  -F 'files=@invoice.pdf.sig' \
  -H 'Authorization: Bearer YOUR_KEY'

import requests

files = [
    ('files', ('invoice.pdf',     open('invoice.pdf',     'rb'))),
    ('files', ('invoice.pdf.sig', open('invoice.pdf.sig', 'rb'))),
]
resp = requests.post(
    'https://api.cleanvoice.ru/cleansign/api/v1/verify',
    params={'returnCertificateFile': 'true'},
    files=files,
    headers={'Authorization': 'Bearer YOUR_KEY'},
)
data = resp.json()
print(data['summary']['validlySigned'], 'valid of', data['summary']['totalDocuments'])

const fd = new FormData();
fd.append('files', pdfFile,  'invoice.pdf');
fd.append('files', sigFile,  'invoice.pdf.sig');

const r = await fetch('https://api.cleanvoice.ru/cleansign/api/v1/verify?returnCertificateFile=true', {
  method: 'POST',
  body: fd,
});
const data = await r.json();
console.log(data.summary.validlySigned + ' / ' + data.summary.totalDocuments);

using var http = new HttpClient { BaseAddress = new Uri("https://api.cleanvoice.ru/cleansign/") };
http.DefaultRequestHeaders.Authorization = new("Bearer", "YOUR_KEY");

using var form = new MultipartFormDataContent();
form.Add(new ByteArrayContent(File.ReadAllBytes("invoice.pdf")),     "files", "invoice.pdf");
form.Add(new ByteArrayContent(File.ReadAllBytes("invoice.pdf.sig")), "files", "invoice.pdf.sig");

var resp = await http.PostAsync("api/v1/verify?returnCertificateFile=true", form);
var json = await resp.Content.ReadAsStringAsync();

Пример ответа (200 OK)

{
  "summary": {
    "totalDocuments":    1,
    "signed":            1,
    "validlySigned":     1,
    "invalidSignatures": 0,
    "notSigned":         0,
    "orphanSignatures":  0
  },
  "items": [
    {
      "documentFile":           "invoice.pdf",
      "documentSize":            182734,
      "signatureFile":           "invoice.pdf.sig",
      "isSigned":                true,
      "isValid":                 true,
      "status":                  "Valid",
      "documentHashAlgorithm":   "GOST R 34.11-2012 (256)",
      "documentHashHex":         "8E5C…",
      "messageDigestMatches":    true,
      "isPowerOfAttorney":       false,
      "signers": [
        {
          "subjectCommonName":     "Иванов Иван Иванович",
          "subjectType":           "ЮЛ",
          "signerShortName":       "Иванов И. И.",
          "signingTime":           "2026-04-30T17:42:11+00:00",
          "signatureValid":        true,
          "trustStatus":           "Trusted",
          "chainTrusted":          true,
          "trustedRootSubject":    "CN=Минцифры России",
          "classification":        { "kind": "КЭП", "kindFull": "Квалифицированная электронная подпись",
                                     "classes": ["КС1"], "subjectSignTool": "КриптоПро CSP (5.0.12000)",
                                     "usesGost": true, "issuedByAccreditedUc": true, "isGoskey": false,
                                     "deprecationWarnings": [] },
          "attributes":            { "inn": "772372861423", "innLe": "7709000010",
                                     "ogrn": "1047709098315", "snils": "14233464635",
                                     "email": "i.ivanov@example.com",
                                     "givenName": "Иван Иванович", "surname": "Иванов",
                                     "organization": "ООО «Пример»" },
          "accreditation":         { "currentStatus": "Accredited", "atSigningTimeStatus": "Accredited" },
          "certificateBase64":     "MIIH…"   // только если returnCertificateFile=true
        }
      ],
      "errors":   [],
      "warnings": []
    }
  ]
}

POST /api/v1/cert/check

Проверка только сертификата, без документа. Эндпоинт оптимизирован для регулярных запусков из cron. Принимает .cer, .crt, .pem, .der или CMS-файл (.sig); во втором случае сертификат подписанта извлекается по SignerID. Возвращает срок действия, число дней до истечения, аккредитацию УЦ, статус OCSP и CRL, классификацию.

Пример: ежедневный мониторинг

#!/bin/bash
# Завершиться с ошибкой, если до истечения сертификата осталось менее 30 дней.
RESP=$(curl -sf -F files=@/etc/ssl/edo.cer https://api.cleanvoice.ru/cleansign/api/v1/cert/check)
DAYS=$(echo "$RESP" | jq '.items[0].daysUntilExpiry')
[ "$DAYS" -lt 30 ] && echo "ALERT: cert expires in $DAYS days" && exit 1

Пример ответа

{
  "summary": { "total": 1, "currentlyValid": 1, "expiringSoon": 0, "expired": 0,
               "trusted": 1, "untrusted": 0, "revoked": 0 },
  "items": [{
    "fileName":          "edo.cer",
    "source":            "X509",
    "subjectCommonName": "ООО «Пример»",
    "issuer":            "CN=Удостоверяющий центр Федерального казначейства",
    "notBefore":         "2025-08-12T08:14:00+00:00",
    "notAfter":          "2026-08-12T08:14:00+00:00",
    "isCurrentlyValid":  true,
    "daysUntilExpiry":   97,
    "publicKeyAlgorithm":"GOST R 34.10-2012 (256)",
    "classification":    { "kind": "КЭП", "classes": ["КС1"], "issuedByAccreditedUc": true },
    "trust":             { "status": "Trusted", "trusted": true,
                           "rootSubject": "CN=Минцифры России",
                           "chain": [...] },
    "accreditation":     { "currentStatus": "Accredited" },
    "revocation":        null,
    "revocationCrl":     null
  }]
}

VerificationResponse

Ответ POST /api/v1/verify.

DocumentVerificationResult

SignerInfoResult

Полная карточка подписанта. Поля сгруппированы для удобства.

Идентификация

Срок действия и алгоритмы

Криптопроверка и доверие

Расширенная информация

CertificateCheckResponse

Ответ POST /api/v1/cert/check. Структура простая:

Типичные интеграции

Сценарии, в которых API применяется на практике.

curl -F files=@cert.cer \
  https://api.cleanvoice.ru/cleansign/api/cert/check \
  | jq '.items[0].daysUntilExpiry < 30'

Состав подписки

Подписка включает не только доступ к API, но и операционное обслуживание сервиса в режиме 24/7: