API VERIDOC

Как это устроено

1. Ваша программа отправляет файл отчёта в POST /v1/documents и получает sign_url.
2. Открываете sign_url в браузере — оценщик подписывает своей ЭЦП через NCALayer. Закрытый ключ никуда не передаётся.
3. Опрашиваете GET /v1/documents/{id}, пока status не станет signed.
4. Забираете отсоединённую подпись через /v1/documents/{id}/signature и кладёте её рядом с отчётом.
5. Ссылку verify_url печатаете в отчёте — по ней банк, суд или палата проверят подлинность.

Руководитель организации подписывает тот же документ вторым — просто открывает ту же ссылку. Подписей может быть сколько угодно, порядок сохраняется.

Ключ доступа

Войдите по ЭЦП и создайте ключ в кабинете — он подставится сюда автоматически.

Ключ передаётся заголовком Authorization: Bearer <ключ>.

Остаток по ключу

curl https://veridoc.kz/v1/me \
  -H "Authorization: Bearer qk_ВАШ_КЛЮЧ"

{
  "plan": "business",
  "plan_title": "Бизнес",
  "documents_limit": 200,
  "documents_used": 47,
  "documents_left": 153,
  "max_file_mb": 100,
  "resets_at": "01.10.2026"
}

Считаются загруженные документы, а не подписи: подписантов под одним документом может быть сколько угодно и они бесплатны. При исчерпании лимита загрузка отвечает кодом 402 с понятным текстом — обрабатывайте его и показывайте пользователю, а не «ошибку сервера».

Загрузить отчёт на подпись

curl -X POST https://veridoc.kz/v1/documents \
  -H "Authorization: Bearer qk_ВАШ_КЛЮЧ" \
  -F "file=@otchet-ob-ocenke-1042.pdf"

{
  "id": "8f2Kd1PqWm",
  "code": "A0911E",
  "sha256": "9c1f…",
  "sign_url": "https://veridoc.kz/d/8f2Kd1PqWm",
  "verify_url": "https://veridoc.kz/v/A0911E"
}

Узнать статус и кто подписал

curl https://veridoc.kz/v1/documents/8f2Kd1PqWm \
  -H "Authorization: Bearer qk_ВАШ_КЛЮЧ"

{
  "status": "signed",
  "signatures": [
    {
      "signed_at": 1788988000,
      "verdict": "valid",
      "signer": {
        "full_name": "ИВАНОВ ИВАН",
        "iin": "800101300123",
        "bin": "230140042917",
        "org": "ТОО \"Оценка и право\"",
        "issuer": "ҰЛТТЫҚ КУӘЛАНДЫРУШЫ ОРТАЛЫҚ",
        "not_after": "2027-09-10T12:00:00"
      }
    }
  ]
}

verdict принимает три значения: valid — подпись действительна, invalid — недействительна, unknown — проверить не удалось. Третий случай не означает подделку: так бывает, когда служба проверки отзыва временно недоступна. Никогда не показывайте unknown пользователю как ошибку.

Забрать подпись для приложения к делу

curl https://veridoc.kz/v1/documents/8f2Kd1PqWm/signature \
  -H "Authorization: Bearer qk_ВАШ_КЛЮЧ"

{ "format": "CMS", "encoding": "base64", "cms": "MIIG1wYJKoZ…" }

Раскодируйте base64 и сохраните как отчёт.cms рядом с PDF. Эти два файла вместе и есть юридически значимый комплект.

Подписание на вашей стороне, хранение — у нас

Если подписание уже реализовано в вашей программе, присылайте готовую CMS. Мы добавим метку времени, проверим и сохраним доказательную базу.

curl -X POST https://veridoc.kz/v1/documents/8f2Kd1PqWm/signatures \
  -H "Authorization: Bearer qk_ВАШ_КЛЮЧ" \
  -F "cms=$(base64 -w0 otchet.cms)"

{
  "ok": true,
  "verdict": "valid",
  "ades_level": "T",
  "best_signature_time": "2026-09-10T16:14:57Z",
  "signer": {
    "full_name": "ЧУЯСОВ АНДРЕЙ ВЛАДИМИРОВИЧ",
    "iin": "810329050451",
    "bin": "230140042917",
    "org": "ТОО \"Мой арбитр\"",
    "issuer": "ҰЛТТЫҚ КУӘЛАНДЫРУШЫ ОРТАЛЫҚ (GOST) 2022",
    "not_after": "2026-10-02T13:23:42"
  }
}

Обратно вы всегда можете забрать и файл, и подпись, и краткую карточку подписанта: GET /v1/documents/{id} отдаёт статус и данные подписантов, /signature — саму CMS в base64. Этого достаточно, чтобы хранить комплект у себя и не зависеть от нас.

Проверить чужую подпись

curl -X POST https://veridoc.kz/v1/verify \
  -H "Authorization: Bearer qk_ВАШ_КЛЮЧ" \
  -F "document=@otchet.pdf" \
  -F "signature=@otchet.cms"

Работает с подписями из Documentolog, SIGEX, idocs, 1С и госсистем. Файлы не сохраняются — проверка идёт в памяти.

Пример на Python

import time, requests

API = "https://veridoc.kz"
H = {"Authorization": "Bearer qk_ВАШ_КЛЮЧ"}

with open("otchet.pdf", "rb") as f:
    doc = requests.post(f"{API}/v1/documents", headers=H,
                        files={"file": f}).json()

print("Отправьте оценщику:", doc["sign_url"])

while True:
    st = requests.get(f"{API}/v1/documents/{doc['id']}", headers=H).json()
    if st["status"] == "signed":
        break
    time.sleep(5)

sig = requests.get(f"{API}/v1/documents/{doc['id']}/signature",
                   headers=H).json()
open("otchet.cms", "wb").write(__import__("base64").b64decode(sig["cms"]))
print("Подписал:", st["signatures"][0]["signer"]["full_name"])
print("Проверка:", doc["verify_url"])

Что учесть оценщикам

Отчёт об оценке подписывается оценщиком и, если оценка велась в организации, утверждается её руководителем. Это две подписи под одним файлом — отправьте одну и ту же ссылку обоим.

Если оценку по разным объектам вели несколько оценщиков, каждый подписывает отдельно. Все подписи лягут под один документ, порядок и время фиксируются. Ссылку verify_url имеет смысл печатать в самом отчёте вместе с кодом — тогда проверяющему не нужен доступ к вашей системе.