API Numera Docs

Версия v1. Базовый адрес https://docs.numeraai.kz/api/v1

Начало работы

Через API ваша CRM, 1С или сайт загружает документ, отправляет его контрагенту на подпись и узнаёт результат. Подписывают люди, как и в кабинете: своей ЭЦП НУЦ РК через NCALayer, по ссылке, без регистрации. API берёт на себя всё остальное, от создания процесса до архива с подписями.

Обычная интеграция выглядит так:

1. Загрузить файл: POST /documents, или собрать документ из шаблона.
2. Отправить на подпись: POST /documents/{id}/send. В ответе будут ссылки для подписантов.
3. Передать ссылку контрагенту. Если указать email, письмо отправим сами.
4. Получить вебхук document.completed и скачать архив с подписями.

Все запросы и ответы в JSON и UTF-8, даты в ISO 8601 (UTC). Загрузка файла принимает и multipart/form-data.

Ключи и авторизация

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

curl https://docs.numeraai.kz/api/v1/me \
  -H "Authorization: Bearer nd_live_ваш_ключ"

Ключи бывают двух видов. nd_live_… работает с настоящими документами. nd_test_… работает в тестовой среде, о ней ниже. Запросы по ключу выполняются от имени сотрудника, который его выпустил, с его ролью. Если отключить сотрудника в команде, его ключи перестанут работать сразу.

Держите ключ на сервере. В коде сайта или мобильного приложения его увидит любой посетитель.

GET /me возвращает организацию, тариф, остаток лимитов за месяц и лимит запросов. Удобно для проверки ключа.

Тестовая среда

Тестовый ключ nd_test_… ходит в тот же адрес и в те же методы, но документы попадают в песочницу:

• они бесплатны и не тратят лимит тарифа (в сутки можно создать до 100);
• их не видно в кабинете и по боевому ключу, а боевые документы не видно по тестовому;
• письма подписантам не уходят;
• подписать можно только методом «подпись в песочнице»: подпись ставит тестовый удостоверяющий центр Numera, а не НУЦ РК. Ссылку из песочницы можно открыть, но настоящей ЭЦП такой документ не подписать, на странице будет пометка «Тестовый документ»;
• вебхуки тестовых документов приходят только на вебхуки тестовой среды, в теле стоит "sandbox": true.

В остальном песочница ведёт себя как боевая среда: те же статусы, ошибки и события. Отладьте интеграцию на тестовом ключе, потом замените его на боевой.

Лимиты

API включён во все тарифы. Цены те же, что в кабинете, а лимиты зависят от тарифа:

Документы из API и из кабинета считаются вместе. Лимит запросов общий на организацию. Ключи считаются вместе, тестовые и боевые. Вебхуков можно столько, сколько указано, отдельно для каждой среды. В каждом ответе есть заголовки X-RateLimit-Limit, X-RateLimit-Remaining и X-RateLimit-Reset (секунд до сброса окна). Если лимит превышен, придёт 429 с заголовком Retry-After: подождите указанное число секунд и повторите запрос.

Ошибки

Ошибка приходит с HTTP-кодом и телом одного формата. error стабилен, по нему удобно ветвиться в коде. message написан по-русски для человека. Если запрос не прошёл проверку схемы (validation_error), в fields перечислены поля с ошибкой.

{
  "error": "documents_limit_reached",
  "message": "Достигнут лимит тарифа Start: 20 новых документов в месяц"
}

Документы

Форматы: PDF, DOCX и TXT, до 20 МБ. Тип определяется по содержимому файла, а не по расширению. PDF с JavaScript и DOCX с макросами или внешними связями не принимаются. В base64 файл занимает на треть больше места, поэтому через /documents/base64 передавайте файлы до 18 МБ, а крупнее загружайте через multipart.

Повтор без дублей. Передайте заголовок Idempotency-Key (например, номер заказа в вашей системе, от 8 символов). Если запрос оборвался и вы отправили его снова с тем же ключом, вернётся уже созданный документ, второй не появится и лимит не потратится.

curl https://docs.numeraai.kz/api/v1/documents \
  -H "Authorization: Bearer $NUMERA_KEY" \
  -F title="Договор поставки № 15/2026" \
  -F doc_type=CONTRACT \
  -F file=@dogovor.pdf

{
  "id": "3f6c1e2a-…",
  "title": "Договор поставки № 15/2026",
  "doc_type": "CONTRACT",
  "status": "DRAFT",
  "sandbox": false,
  "version": 1,
  "created_at": "2026-10-20T09:12:44Z",
  "template_id": null,
  "url": "https://docs.numeraai.kz/documents/3f6c1e2a-…",
  "workflow": null
}

Отправка на подпись

В recipients перечислите получателей. Если указать iin, подпись примем только от сертификата с этим ИИН. Без ИИН подписать может любой, у кого есть ссылка, а в документ запишутся ФИО и ИИН из его ЭЦП. bin требует, чтобы ЭЦП была выдана на эту организацию. view_only: true отправляет документ на ознакомление без подписи.

Повтор без второго процесса. Передайте Idempotency-Key и в /send. Если ответ потерялся и вы повторили запрос с тем же ключом, придёт уже запущенный процесс с "replayed": true. Ссылки в повторном ответе не показываются, новую выдаёт /signers/{signer_id}/link.

Если вы тоже подписываете, передайте i_sign: true. Подписать можно в кабинете (сотрудник, выпустивший ключ, должен указать ИИН в профиле), а в песочнице методом из раздела ниже. При последовательном подписании получатели подписывают в порядке списка, а вы после них. Другой порядок задают order у получателей и my_order у вас. Одинаковый номер означает «одновременно», а это параллельное подписание, оно есть на тарифах Team и Business.

curl https://docs.numeraai.kz/api/v1/documents/$DOC_ID/send \
  -H "Authorization: Bearer $NUMERA_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "recipients": [
      {"full_name": "ТОО «Бета Логистик»", "email": "director@beta.kz", "iin": "900101300111", "order": 1}
    ],
    "i_sign": true,
    "my_order": 2,
    "expires_in_days": 14
  }'

{
  "document": { "id": "3f6c1e2a-…", "status": "PENDING_SIGNATURE", "workflow": { … } },
  "links": [
    { "signer_id": "a1b2…", "url": "https://docs.numeraai.kz/invite/Xk2…" }
  ]
}

Если указать phone, ссылку отправим по SMS. Способ подписи задаёт sign_method, об этом в следующем разделе.

Ссылки в ответе есть только у тех, чья очередь уже подошла. Когда очередь дойдёт до следующего подписанта, придёт вебхук signer.invited. Если у подписанта есть email, письмо со ссылкой он получит сам, больше ничего делать не нужно. Если email нет, запросите ссылку методом /signers/{signer_id}/link и отправьте её в WhatsApp или Telegram. Этот метод выпускает новую ссылку, а прежнюю (в том числе ту, что ушла письмом) отключает. Ссылка показывается один раз: в базе хранится только её хеш.

/remind возвращает {"reminded": число, "invitation_links": {signer_id: url}}: внешним подписантам выпускаются свежие ссылки. /link возвращает {"signer_id", "url"}.

Подпись по SMS

Получатель с "sign_method": "sms" подписывает кодом из SMS, без ЭЦП. Для него обязательны full_name и phone (мобильный номер Казахстана). Значение any оставляет выбор за подписантом: SMS или ЭЦП, а ecp, значение по умолчанию, допускает только ЭЦП.

curl https://docs.numeraai.kz/api/v1/documents/$DOC_ID/send \
  -H "Authorization: Bearer $NUMERA_KEY" -H "Content-Type: application/json" \
  -d '{"recipients": [{"full_name": "Иванов Иван", "phone": "+77011234567", "sign_method": "sms"}]}'

Мы отправим ссылку на этот номер. Подписант откроет документ, подтвердит согласие и введёт код. Код приходит только на указанный вами номер, изменить его подписант не может. Дальше всё как обычно: те же статусы, вебхуки, квитанция и архив.

Чем это отличается от ЭЦП. Код из SMS не является ЭЦП НУЦ РК. По статье 47 Цифрового кодекса РК это цифровое подтверждение, которое применяется по соглашению сторон: оно показывает, что код ввели на этом номере. Личность по ИИН сервис не проверяет. В signature такого подписанта стоит "method": "sms" и маска номера, а cert_iin и cert_bin содержат то, что указал отправитель. Если закон требует ЭЦП, используйте ЭЦП.

Ссылка и код считаются как отдельные SMS в лимите тарифа. Если лимит закончился, процесс не прерывается: вы получите links и событие signer.sms_failed, а запрос кода вернёт 402 sms_limit_reached. То же событие приходит, если оператор не доставил ссылку. Пока SMS не подключены, такие получатели отклоняются с 409 sms_disabled, проверить можно в sms_enabled из GET /me. В песочнице SMS не уходят, подпись ставит метод из раздела «Подпись в песочнице».

Номер договора и абонентская плата

Любой документ может хранить номер договора. Компаниям с пометкой «особая компания» (contract_fields_enabled в GET /me; пометку ставит поддержка) при создании договора обязательны номер и абонентская плата. Поля передаются в meta в JSON, а при загрузке multipart строкой с JSON в поле meta. Эти данные служат для учёта и не меняют подписанный файл.

curl https://docs.numeraai.kz/api/v1/documents/base64 \
  -H "Authorization: Bearer $NUMERA_KEY" -H "Content-Type: application/json" \
  -d '{"title": "Договор", "filename": "d.pdf", "content_base64": "…",
       "meta": {"contract_number": "15/2026", "fields": {"monthly_fee": 150000}}}'

В ответе fields содержит значения самого документа, effective_fields текущие значения договора с учётом подписанных допсоглашений, а fields_history историю изменений. Для расчётов берите effective_fields. Суммы приходят строкой с двумя знаками: "150000.00".

Допсоглашения и расторжение

Соглашение заключается к договору, который подписан всеми сторонами или загружен подписанным. Это обычный документ со связью: создаёте и отправляете через /send.

# Допсоглашение: новая абонплата начнёт действовать, когда его подпишут все стороны
curl https://docs.numeraai.kz/api/v1/documents/base64 \
  -H "Authorization: Bearer $NUMERA_KEY" -H "Content-Type: application/json" \
  -d '{"title": "ДС № 1", "filename": "ds.pdf", "content_base64": "…",
       "meta": {"relation": "ADDENDUM", "parent_document_id": "'$DOC_ID'", "fields": {"monthly_fee": 180000}}}'

# Расторжение: текст соберём сами, либо передайте filename и content_base64
curl https://docs.numeraai.kz/api/v1/documents/$DOC_ID/termination \
  -H "Authorization: Bearer $NUMERA_KEY" -H "Content-Type: application/json" \
  -d '{"reason": "По соглашению сторон", "effective_on": "2026-12-31"}'

Номер договора наследуется, если не указан другой. Когда все стороны подпишут расторжение, у договора станет "lifecycle": "TERMINATED" и появится terminated_at; его статус подписания остаётся SIGNED. Незавершённые допсоглашения при этом отменяются. Если соглашение отклонили, договор продолжает действовать. В GET /documents/{id} есть parent_id и children.

Для соглашений приходят события с данными договора: document.addendum_signed с полем addendum_id и document.terminated с termination_id, reason и effective_on. В обоих data.document содержит сам договор и актуальные effective_fields.

Подписанные документы

Такой документ хранится для учёта и поиска со статусом UPLOADED_SIGNED и не тратит лимит новых документов. Мы не проверяем подписи в файле, поэтому квитанции и публичной проверки для него нет, а на подпись его не отправить. Допсоглашения и расторжение к нему работают. Загруженное подписанным соглашение (relation и parent_document_id в meta) вступает в силу сразу.

Статусы

Статус документа (status) равен статусу его последнего процесса подписания:

Статус подписанта: WAITING (очередь не подошла), PENDING (может подписать), SIGNED, REJECTED, SKIPPED (документ завершён без его подписи). У подписавшего в signature лежат способ подписи method и данные сертификата: ФИО, ИИН, БИН и серийный номер. Расторгнут ли договор, показывает отдельное поле lifecycle: ACTIVE или TERMINATED.

Скачивание

Архив удобно класть в вашу систему как доказательство подписания: его можно проверить OpenSSL или NCANode без нашего участия.

Шаблоны

Шаблоны создаются в кабинете, раздел «Шаблоны». Поле в тексте выглядит как {{summa_dogovora}}. Через API передайте значения по ключам полей:

curl https://docs.numeraai.kz/api/v1/documents/from-template \
  -H "Authorization: Bearer $NUMERA_KEY" -H "Content-Type: application/json" \
  -d '{"template_id": "…", "title": "Акт № 7", "values": {"summa_dogovora": "1 500 000 тенге"}}'

Если не заполнить обязательное поле, придёт 422 template_fields_missing со списком полей.

Вебхуки

Вебхук сообщает вашему серверу о событии по документу, и опрашивать API не нужно. Адрес должен быть публичным, работать по https на порту 443 или 8443 и не содержать логина и пароля. Редиректы мы не выполняем.

Вебхуки настраивает роль с правом управлять настройками (владелец или администратор). Тестовый ключ видит только вебхуки песочницы, боевой только боевые.

POST https://crm.example.kz/numera/webhook
X-Numera-Event: signer.signed
X-Numera-Delivery: 5b1e…
X-Numera-Signature: t=1760951564,v1=8f3c…

{
  "id": "evt_9c2f…",
  "seq": 18342,
  "type": "signer.signed",
  "created_at": "2026-10-20T09:32:44Z",
  "sandbox": false,
  "data": {
    "document": { "id": "3f6c1e2a-…", "title": "Договор поставки № 15/2026", "status": "PARTIALLY_SIGNED" },
    "workflow_id": "c0de…",
    "signer": { "id": "a1b2…", "full_name": "Нурланова Динара", "email": "dinara@beta.kz", "status": "SIGNED", "signed_at": "2026-10-20T09:32:43Z" }
  }
}

У document.rejected и document.cancelled в data.reason лежит причина. Ответьте кодом 2xx в течение 10 секунд, а долгую обработку делайте после ответа. Если ответ другой или его нет, повторим через 1 минуту, 5 минут, 30 минут, 2, 6, 12 часов и затем раз в сутки трижды, всего около 4 суток. Одно событие может прийти дважды, поэтому сверяйте id. seq — сквозной номер события: по нему удобно упорядочивать события и дочитывать пропущенные из ленты. Порядок доставки не гарантирован: актуальный статус всегда есть в data.document.status и в GET /documents/{id}. Журнал доставок виден в кабинете.

Проверяйте подпись, иначе кто угодно сможет прислать вашему серверу поддельное событие. Секрет whsec_… выдаётся при создании вебхука. Подпись считается так: HMAC-SHA256 от строки {t}.{тело запроса}, где t взят из заголовка. Сравнивайте с v1 и отклоняйте запросы старше 5 минут.

import hashlib, hmac, time

def verify(secret: str, header: str, body: bytes) -> bool:
    parts = dict(x.split("=", 1) for x in header.split(","))
    t, sig = parts.get("t", ""), parts.get("v1", "")
    if not t.isdigit() or abs(time.time() - int(t)) > 300:
        return False
    expected = hmac.new(secret.encode(), f"{t}.".encode() + body, hashlib.sha256).hexdigest()
    return hmac.compare_digest(expected, sig)

# Flask:
# ok = verify(WHSEC, request.headers["X-Numera-Signature"], request.get_data())

Считайте подпись по сырому телу запроса, а не по JSON, который ваш фреймворк уже разобрал и собрал заново.

Лента событий

Лента пишется всегда, даже если вебхук не настроен. Сохраните seq последнего обработанного события и запрашивайте after=<seq>: придут только новые. Пока has_more равен true, повторяйте запрос с after=next_after. Фильтр по документу: document_id. Тестовый ключ видит события песочницы, боевой только боевые.

{
  "data": [ { "id": "evt_…", "seq": 18342, "type": "signer.signed", "created_at": "…", "sandbox": false, "data": { … } } ],
  "has_more": false,
  "next_after": 18342
}

Надёжная интеграция

1. Создание и отправка с Idempotency-Key. Используйте свой стабильный идентификатор (номер заказа или сделки). Повтор после таймаута или 5xx не создаст дубль.
2. Вебхук: быстрый ответ и дедупликация. Проверьте подпись, сохраните событие по id (уникальный ключ), ответьте 2xx, обработку делайте отдельно.
3. Догоняющее чтение. При старте сервиса и раз в 5–15 минут читайте /events?after=<последний seq>. Так вы получите всё, что пропустили, даже если сервер лежал дольше 4 суток повторов (до 90 дней).
4. Источник истины — GET /documents/{id}. Решения «подписан / отклонён» принимайте по статусу документа, а не по порядку пришедших событий.
5. Повторы ваших запросов. На 429 ждите Retry-After, на 5xx и сетевые ошибки повторяйте с паузой 1, 2, 4… секунды; 4xx (кроме 429) не повторяйте.

Подпись в песочнице

Методы работают только с тестовым ключом. Подпись проходит обычную проверку: статусы меняются, вебхуки приходят, архив собирается. В подписи стоит "test": true, а в архиве пометка, что это не ЭЦП НУЦ РК. Юридической силы такая подпись не имеет.

Пример целиком

Скрипт на Python загружает договор в песочницу, отправляет его контрагенту, подписывает за обе стороны и скачивает архив. Замените ключ на свой тестовый.

import requests

API = "https://docs.numeraai.kz/api/v1"
H = {"Authorization": "Bearer nd_test_ваш_ключ"}

doc = requests.post(f"{API}/documents", headers=H,
                    data={"title": "Тестовый договор"},
                    files={"file": open("dogovor.pdf", "rb")}).json()

sent = requests.post(f"{API}/documents/{doc['id']}/send", headers=H, json={
    "recipients": [{"full_name": "ТОО «Бета»", "iin": "900101300111", "order": 1}],
    "i_sign": True, "my_order": 2,
}).json()

for s in sent["document"]["workflow"]["signers"]:
    r = requests.post(f"{API}/sandbox/documents/{doc['id']}/signers/{s['id']}/sign", headers=H)
    print(s["full_name"], "→", r.json()["status"])   # PARTIALLY_SIGNED, затем SIGNED

zip_ = requests.get(f"{API}/documents/{doc['id']}/download", headers=H, params={"kind": "archive"})
open("archive.zip", "wb").write(zip_.content)

Вопросы по интеграции присылайте на info@numeraai.kz или в чат поддержки в кабинете. Клиентам тарифа Business помогаем с подключением.