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). Подпись принимается в форматах raw DER, base64 и PEM — обёртка определяется автоматически. Кроме того, если файл имеет нестандартное расширение (например, оператор переименовал .sig в .txt или вставил base64 подписи в текстовый файл) и его размер не превышает 256 KB, сервис проверяет содержимое и распознаёт CMS по сигнатуре signedData — после этого файл встаёт в пайплайн как обычная подпись. Документом может быть любой файл — .pdf, .docx, .xlsx, .doc, .xml, .txt, .html, .rtf и любой бинарный.
• CAdES — те же расширения, что и CMS; распознаются профили BES, EPES, T, C, X-L Type 1, A. Штампы времени RFC 3161 проверяются end-to-end (TSA-подпись + сравнение imprint), для CAdES-A реконструируется imprint archive-timestamp v2.
• PAdES — встроенная подпись в PDF (.pdf): чтение /ByteRange, /Contents, поддержка нескольких подписей в одном документе и словаря /DSS (DSS dictionary).
• Opaque CMS — «совмещённая» подпись: PKCS#7 signedData, в котором подписываемый документ зашит внутри (encapContentInfo.eContent, RFC 5652 §5.2). Такой формат выдаёт Госключ при подписании PDF: файл может быть назван doc.pdf, но его байты — это CMS-обёртка, а сам PDF лежит внутри контейнера. Сервис автоматически распознаёт opaque CMS у любого расширения, извлекает встроенный документ и верифицирует подпись против него (отдельный файл-документ не требуется). В отчёте «имя файла подписи» получает синтетическое значение «{name} (opaque CMS)», а «имя файла документа» — фактическое имя загруженного файла.
• S/MIME — почтовые сообщения multipart/signed и opaque application/pkcs7-mime. Расширения: .eml, .p7m, .mime, .msg.
• XMLDSig / XAdES — XML-файлы (.xml) с алгоритмами ГОСТ Р 34.10-2001/2012 (256/512) или RSA/ECDSA. Поддерживаются преобразования c14n, exc-c14n, enveloped-signature, base64, W3C-1999 XPath и W3C-2002 XPath-Filter 2, а также проприетарные urn://smev-gov-ru/xmldsig/transform (СМЭВ-3) и urn:xml-dsig:transformation:v1.1 (ФТС таможня — частично, для мульти-namespace субдеревьев см. Известные ограничения в общей документации). Принимаются обе URI-семьи алгоритмов: urn:ietf:params:xml:ns:cpxmlsec:algorithms:* (CryptoPro xmlsec) и http://www.w3.org/2001/04/xmldsig-more#* (RFC 4490).
• OOXML — .docx, .xlsx, .pptx с поддержкой RelationshipTransform по ECMA-376 п.13.
• ZIP-архивы — .zip распаковывается на один уровень: документы и подписи внутри сопоставляются по содержимому (хеш) и по имени. Также поддерживается «архив подписан целиком»: foo.zip + foo.zip.sig либо archive.zip с сиблингом .sig, чей messageDigest совпадает с хешем архива.

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

Канонические пути 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-подписью, opaque-CMS файлы (документ зашит в encapContentInfo — типичный выхлоп Госключа), .eml с S/MIME, файлы .docx, .xlsx, .pptx и .xml (XMLDSig).

Про revocation в ответе. CRL-проверка делается поиском в CRL-банке в памяти — никаких сетевых запросов в момент проверки. Если CDP-URL сертификата ещё не проиндексирован банком (первая встреча УЦ), проверка revocation-crl приходит со статусом Skipped и пометкой «CRL not yet indexed»; URL автоматически кладётся в очередь фоновой прокачки, следующая проверка отдаст Good/Revoked. OCSP по умолчанию асинхронный: revocation-ocsp приходит как Pending, клиент обращается к /api/v1/revocation и подменяет результат. OCSP сразу в ответе — флаг ?withRevocation=true (медленнее на 0.5–10 с).

Параметры запроса (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":         { "issuingUcSki": "23F0DA4A5DE30C96E91F976A3E641689A1F8553C",
                                     "issuingUcName": "УЦ ФНС России",
                                     "accreditedFrom": "2024-01-01T00:00:00+00:00",
                                     "accreditedTo":   null },
          // null accreditedTo  → УЦ accredited at the moment of the response.
          // null issuingUcSki  → issuing УЦ wasn't found in the Минцифры registry.
          // Clients derive "accredited at signing time" by comparing
          // signingTime against AccreditedFrom / AccreditedTo themselves.
          "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":     { "issuingUcSki": "...", "issuingUcName": "УЦ Казначейства",
                           "accreditedFrom": "2024-01-01T00:00:00+00:00", "accreditedTo": null },
    "revocation":        null,
    "revocationCrl":     null
  }]
}

Асинхронная OCSP-проверка сертификата

Эндпоинт делает OCSP-запрос к responder'у УЦ (RFC 6960) для одного сертификата. Спроектирован как асинхронное продолжение /api/v1/verify и /api/v1/cert/check: по умолчанию они откладывают OCSP-запрос (он может занять до нескольких секунд) и возвращают check со статусом Pending и URL OCSP-endpoint'а. Клиент (фронт или CLI) дёргает этот эндпоинт с DER-сертификатом подписанта и получает финальный статус.

CRL revocation через этот эндпоинт не запрашивается. Начиная с версии с CRL-банком, CRL-проверка делается сразу в ответе /verify и /cert/check по индексу отозванных серийников в памяти (см. /api/v1/crl-bank/stats) — это поиск за константное время без обращений по сети. Здесь только OCSP, который остаётся онлайн-запросом к серверу УЦ.

Сертификат-издатель резолвится из TrustStore по SubjectKeyIdentifier / IssuerDN. Если издателя нет в trust-store (зарубежные / тестовые УЦ — EJBCA, Let's Encrypt, DigiCert), check возвращается как NotApplicable с пометкой «issuer cert not in trust store» — без открытого ключа издателя OCSP-запрос построить нельзя.

Без rate-limit: UI стреляет в этот эндпоинт параллельно для каждого подписанта в multi-signer документе. Bearer-токен остаётся обязательным.

Запрос

POST /api/v1/revocation
Content-Type: application/json
Authorization: Bearer <session-token>

{
  "signerCertBase64": "MIIH..."
}

Параметры тела

Ответ — OCSP прошёл

200 OK

{
  "ocsp": {
    "status":     "Good",
    "producedAt": "2026-05-16T19:49:55+00:00",
    "thisUpdate": "2026-05-16T19:49:55+00:00",
    "ocspUrl":    "http://ocsp1.taxcom.ru/OCSPAL/ocsp.srf"
  },
  "ocspCheck": {
    "id":      "revocation-ocsp",
    "status":  "Ok",
    "details": "Endpoint: http://ocsp1.taxcom.ru/..."
  }
}

Поля ответа

Ответ — сертификат отозван

200 OK

{
  "ocsp": {
    "status":           "Revoked",
    "revocationTime":   "2025-08-12T11:14:00+00:00",
    "revocationReason": "keyCompromise",
    "ocspUrl":          "http://pki.tax.gov.ru/ocsp02/ocsp.srf"
  },
  "ocspCheck": {
    "id":       "revocation-ocsp",
    "status":   "Failed",
    "critical": true,
    "details":  "Revoked at 2025-08-12T11:14:00Z, reason: keyCompromise. Endpoint: http://pki.tax.gov.ru/..."
  }
}

Ответ — issuer не в trust-store (зарубежный/тестовый УЦ)

200 OK

{
  "ocsp": null,
  "ocspCheck": {
    "id":      "revocation-ocsp",
    "status":  "NotApplicable",
    "details": "Cannot check OCSP: the signer's issuer certificate is not in the trust store..."
  }
}

Для зарубежных УЦ (EJBCA, Let's Encrypt, DigiCert и т.п.) — это ожидаемый ответ. Чтобы OCSP заработал, добавьте сертификат-издатель в trust-store/intermediates/.

Ответ — OCSP выключен в конфиге

200 OK

{
  "ocsp": null,
  "ocspCheck": {
    "id":      "revocation-ocsp",
    "status":  "Skipped",
    "details": "Disabled in configuration (CleanSign:TrustStore:EnableOcsp=false)."
  }
}

Использование из браузера

// Достали cert из ответа /verify
const cert = response.items[0].signers[0].certificateBase64;

// Дёрнули revocation
const r = await fetch('/api/v1/revocation', {
  method: 'POST',
  headers: {
    'Authorization': 'Bearer ' + token,
    'Content-Type': 'application/json',
  },
  body: JSON.stringify({ signerCertBase64: cert }),
});
const { ocspCheck } = await r.json();

// Заменили Pending-чек на финальный
signer.checks = signer.checks.map(c =>
  c.id === ocspCheck.id ? ocspCheck : c);

Inline-альтернатива для бизнес-API

Если асинхронная схема неудобна (например, скрипт по расписанию) — можно попросить /verify вернуть OCSP сразу в ответе:

POST /api/v1/verify?withRevocation=true
Content-Type: multipart/form-data
...

То же для /api/v1/cert/check?withRevocation=true. В этом режиме отдельный вызов /revocation не нужен, но первый ответ возвращается на 0.5–10 секунд медленнее (зависит от скорости responder'а УЦ). CRL в любом случае проверяется inline через CRL-банк.

Список аккредитованных УЦ

Возвращает текущий снимок реестра аккредитованных удостоверяющих центров Минцифры из памяти. Источник — TSL-XML по адресу https://e-trust.gosuslugi.ru/CA/DownloadTSL?schemaVersion=0, сохраняется в trust-store/registry/tsl-cache.xml и обновляется фоновой задачей каждые 24 часа. На «свежем» хосте — ~481 УЦ.

Эндпоинт открыт (без сессии и rate-limit), читает только из памяти — подходит для регулярных опросов из мониторинга или интеграций.

Параметры

Нет.

Ответ

200 OK

{
  "loadedAt":   "2026-05-13T01:44:04.5976972Z",
  "source":     "tsl-cache.xml",
  "count":      481,
  "items": [
    {
      "subjectKeyIdentifier": "23F0DA4A5DE30C96E91F976A3E641689A1F8553C",
      "name":                 "УЦ ФНС России",
      "inn":                  "7707329152",
      "ogrn":                 "1047707030513",
      "accreditedFrom":       "2021-12-29T00:00:00",
      "accreditedTo":         null,
      "notes":                "Действует"
    },
    ...
  ]
}

Поля ответа

Поиск УЦ по SKI

Возвращает запись о конкретном УЦ по hex-значению SubjectKeyIdentifier. SKI можно получить из leaf-сертификата подписанта — он совпадает с SKI его эмитента, либо из ответа /verify (accreditation.issuingUcSki).

Параметры пути

Ответ

200 OK — объект AccreditedUc (поля как в items[] выше).
404 Not Found — УЦ с таким SKI в реестре нет.

Поиск отозванных сертификатов по серийному номеру

Поиск серийника в банке CRL в памяти — фоновая служба раз в сутки выкачивает Certificate Revocation List каждого аккредитованного УЦ из TSL Минцифры и держит в памяти индекс отозванных серийников. Этот эндпоинт ищет hex-серийник по всем CRL, которые сейчас в банке.

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

Важно: пустой результат означает «не найден в покрытых банком УЦ» — это не то же самое, что «гарантированно не отозван». Источник списка URL — <АдресаСписковОтзыва> в TSL Минцифры, поэтому покрываются все 481 аккредитованных УЦ. Сертификаты неаккредитованных или зарубежных издателей в банке отсутствуют.

Авторизация

Bearer-токен сессии. Rate-limit slot не тратится — подходит для регулярных опросов.

Параметры пути

Ответ

200 OK

{
  "serialHex":       "23f0da4a5de30c96e91f976a3e641689a1f8553c",
  "bankSize":        17,
  "lastRefreshedAt": "2026-05-17T01:42:11.319Z",
  "hits": [
    {
      "url":            "http://pki.tax.gov.ru/cdp/...crl",
      "issuerDn":       "C=RU, O=ФНС России, ...",
      "issuerAkiHex":   "23f0da4a5de30c96e91f976a3e641689a1f8553c",
      "revocationDate": "2025-08-12T11:14:00Z",
      "reason":         "keyCompromise"
    }
  ]
}

Поля ответа

Состояние CRL-банка

Сведения о банке в памяти: сколько CRL покрыто, общее число проиндексированных отозванных записей, время последнего обновления. С параметром ?per=1 возвращает разбивку по каждому CRL (URL, issuer DN, окно thisUpdate / nextUpdate, число записей, флаг проверки подписи).

Как банк наполняется

Источник CDP-URL'ов — сам TSL Минцифры. В XML по адресу https://e-trust.gosuslugi.ru/CA/DownloadTSL?schemaVersion=0 для каждого аккредитованного УЦ перечислены теги <АдресаСписковОтзыва><Адрес>…</Адрес> — это полный авторитетный список (~3000 уникальных URL'ов по 481 УЦ, сопровождается Минцифры ежедневно). Никаких ручных списков и догадок по факту использования — только данные из TSL.

1. На старте сервиса MintsifryRegistryRefreshService читает TSL из trust-store/registry/tsl-cache.xml. Тут же ParseTslCrlUrls извлекает все CDP-URL'ы и добавляет в trust-store/crl-bank/known-urls.json. Внутренние / VPN-only хосты (10.x.x.x, 192.168.x.x, *.local) отфильтрованы как недостижимые с публичного хоста.
2. Фоновая служба CrlBankRefreshService запускается раз в сутки в 03:00 МСК (00:00 UTC) — минимальная нагрузка на сервис, к началу рабочего дня в Москве (~09:00) банк уже полностью прокачан. Час и минута настраиваются: CleanSign:CrlBank:ScheduleUtcHour / ScheduleUtcMinute.
3. Если при запуске банк пустой (первый запуск либо удалили trust-store/crl-bank/crls/) — служба запускает немедленный догоняющий прогон, не дожидаясь ночного слота.
4. На каждом прогоне служба проходит весь known-urls.json с параллелизмом Concurrency (по умолчанию 8): для каждого URL делает HTTP GET, парсит BouncyCastle'ом, проверяет подпись CRL относительно trust-store, индексирует отозванные серийники в FrozenDictionary<BigInteger,RevokedEntry>, и пишет на диск:
   • trust-store/crl-bank/crls/<sha256(url)>.crl — сырые DER-байты.
   • trust-store/crl-bank/crls/<sha256(url)>.json — сопроводительные сведения: URL, issuerDn, AKI, thisUpdate/nextUpdate, signatureVerified, last_fetched.
5. После прохождения всех URL делается атомарная замена снимка в памяти (потокобезопасное чтение без блокировок).
6. На каждом обновлении TSL (раз в сутки) новые URL'ы из <АдресаСписковОтзыва> добавляются в known-urls.json. Старые URL'ы оттуда не удаляются — они остаются актуальными для сертификатов, которые были выпущены под старым ключом УЦ до его ротации.
7. При перезапуске сервиса конструктор CrlBank синхронно восстанавливает индексы с диска — не теряем покрытие в промежутке между ночными прогонами.

Что в памяти. На каждый CRL держим только то, что нужно для поиска: FrozenDictionary<BigInteger,RevokedEntry> отозванных серийников + thisUpdate/nextUpdate/signatureVerified. Сами «не отозванные» серийники не нужны — CRL по определению содержит только отозванные, остальное считается действительным в пределах окна.

Что на диске. Полный CRL DER + сопроводительные сведения JSON. При перезапуске всё восстанавливается без обращения по HTTP.

Покрытие. Полное по всем 481 аккредитованным УЦ Минцифры. Если в TSL появляется новый УЦ — его CRL прокачается на ближайшем ночном прогоне. УЦ, который не аккредитован (зарубежные тестовые EJBCA, Let's Encrypt и т.п.), банком не покрывается — что корректно по смыслу: 63-ФЗ обязывает доверять только аккредитованным УЦ.

Предельный размер CRL. Файл больше CleanSign:CrlBank:MaxCrlSizeBytes (по умолчанию 500 МБ) пропускается с предупреждением в журнале — защита от случайно опубликованного гигабайта.

Если CRL у УЦ не отвечает / 404. Старый CRL и его индекс в памяти и на диске остаются — следующая попытка через сутки. Покрытие не теряется из-за временного сбоя CDP.

Запаздывание отзыва. Сертификат, отозванный сразу после ночного прогона, попадёт в наш банк только на следующий день. Окно — до 24 ч. Для большинства задач это приемлемо (КриптоПро CSP по умолчанию делает то же самое).

Авторизация

Bearer-токен сессии. Rate-limit slot не тратится.

Параметры запроса

Ответ

200 OK

{
  "totalCrls":            17,
  "totalRevokedEntries":  1842153,
  "lastRefreshedAt":      "2026-05-17T01:42:11.319Z",
  "perCrl": [
    {
      "url":               "http://pki.tax.gov.ru/cdp/...crl",
      "issuerDn":          "C=RU, O=ФНС России, ...",
      "thisUpdate":        "2026-05-16T15:13:47Z",
      "nextUpdate":        "2026-05-17T15:13:47Z",
      "revokedCount":      1240811,
      "signatureVerified": true
    },
    ...
  ]
}

Поля ответа

VerificationResponse

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

DocumentVerificationResult

SignerInfoResult

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

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

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

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

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

VerificationCheck

Унифицированная запись об одной из проверок конвейера верификации. Лежит в массиве signers[i].checks в том порядке, в котором проверки фактически срабатывают.

Поля

Значения status

Каталог проверок (id → что делает)

Замечание про Unreachable: CleanSign fail-open — если OCSP/CRL responder недоступен или TLS-ГОСТ прокси упал, подпись не отбивается. В checks такой пункт будет Unreachable, а свойство isValid родительского документа останется true. Если revocation-check критичен для вашего use-case — фильтруйте на стороне клиента (checks.some(c => c.id.startsWith('revocation-') && c.status === 'Unreachable')).

Forward-compatibility: новые проверки могут появляться в каталоге, новые значения status — нет (текущие шесть фиксированы). Если ваш клиент не знает какой-то id — просто игнорируйте такую запись или рендерьте её как-нибудь нейтрально.

CertificateCheckResponse

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

Файлы ЭДО ФНС — расшифровка имён

В бандлах от операторов ЭДО (Контур, Диадок, Такском, СБИС) и из личного кабинета ФНС/ОФД встречаются XML-файлы с именами вида <префикс>_<тип>_<ИНН отправителя>_<ИНН получателя>_<дата>_<UUID>.xml. Префикс называет роль документа в обмене (приказы ФНС России о форматах ЭДО — например ММВ-7-6/138@, серия 383@).

Префиксы

Примеры из реальных бандлов

Как идёт обмен

1. Налогоплательщик подписывает ON + TR своей КЭП → шлёт оператору ЭДО (Контур, Такском, Диадок и т.д.).
2. Оператор подписывает IZ своей КЭП → шлёт в ФНС.
3. ФНС проверяет формат, подписывает KV своей КЭП → шлёт обратно через оператора.
4. Оператор подписывает свою IZ на KV → отдаёт налогоплательщику.

Итого один обмен документом — пакет из 3–5 подписанных XML-файлов, между ними цепочка извещений и квитанций. Все подписи — отдельные .sig (CMS detached) либо встроенные в <Signature> внутри XML.

confirmation.xml

Файл confirmation.xml — это уже не ФНС-формат, а внутренний формат конкретного оператора ЭДО (Goskey / Диадок / СБИС): подтверждение принятия документа в системе оператора, ID транзакции и т.п. Имя стандартизировано на уровне оператора, не ФНС.

Что делает CleanSign

Пакет из таких файлов обрабатывается естественно: каждая XML + её .sig верифицируются отдельно. Если имена файлов рассогласованы (некоторые операторы кладут confirmation.sig рядом с XML, имя которого не совпадает с реальным подписанным документом) — срабатывает сопоставление по содержимому через messageDigest в CMS, и пара восстанавливается корректно.

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

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

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

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

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