REST API электронной подписи — интеграция подписания УКЭП и ПЭП (21 метод)

vpn_key Базовый адрес и авторизация

Cert4U — это не REST с путями вида /api/v1/.... Все запросы идут на единый файл, а нужный метод задаётся параметром action:

https://cert4u.ru/api.php?action=<ACTION>

Где взять API-ключ

Ключ выдаётся самостоятельно в личном кабинете: раздел Настройки → API-ключи → создать ключ. API доступен на тарифах Бизнес и Корпорат. На тарифе Старт API нет; на Тестовом — до 10 операций в день для ознакомления. Подробнее о применении для компаний — на странице электронная подпись для бизнеса.

Три способа передать ключ

Заголовок предпочтителен. Поддерживаются три варианта (любой):

# 1) Заголовок X-Api-Key (рекомендуется)
X-Api-Key: ВАШ_КЛЮЧ

# 2) Authorization: Bearer
Authorization: Bearer ВАШ_КЛЮЧ

# 3) Параметр запроса (legacy)
https://cert4u.ru/api.php?action=api_1c_documents&api_key=ВАШ_КЛЮЧ

Мультиарендность

Каждый ключ видит только данные своего аккаунта — фильтр по владельцу применяется ко всем спискам документов, клиентов, вебхуков. Чужие документы по API недоступны.

Лимиты

• Rate limit: 60 запросов в минуту с одного IP и 60 в минуту на ключ. При превышении — 429.
• Дневные лимиты операций по тарифу: Бизнес — 100 операций/день; Корпорат — без лимита; Тестовый — 10/день. Исчерпан дневной лимит — 429; тариф без API или закончились отправки — 402.
• Защита от дублей: заголовок Idempotency-Key на методах создания и отправки — см. идемпотентность.

Формат ответа

Кодировка — UTF-8, ответ — JSON:

# Успех
{ "success": true, ... }

# Ошибка
{ "success": false, "message": "Описание ошибки" }

rocket_launch Быстрый старт

Три рабочих примера. Полные параметры каждого метода — в справочнике API (api-docs.html).

curl "https://cert4u.ru/api.php?action=api_1c_documents&limit=20" \
  -H "X-Api-Key: ВАШ_КЛЮЧ"

# Ответ:
{
  "success": true,
  "documents": [
    { "id": "d_001", "name": "Договор №14.pdf", "status": "new" }
  ]
}

curl -X POST "https://cert4u.ru/api.php?action=api_1c_upload_signed" \
  -H "X-Api-Key: ВАШ_КЛЮЧ" \
  -F "document=@dogovor.pdf" \
  -F "signature=@dogovor.pdf.sig" \
  -F "doc_name=Договор №14" \
  -F "description=Поставка"

# Ответ:
{ "success": true, "document": { "id": "d_042", "status": "signed_admin", ... },
  "crypto_verify": true, "sig_format": "attached" }

# Отправка клиенту (ПЭП по SMS)
curl -X POST "https://cert4u.ru/api.php?action=api_1c_send" \
  -H "X-Api-Key: ВАШ_КЛЮЧ" \
  -d "doc_id=d_042" \
  -d "client_id=c_007" \
  -d "sign_type=pep_only"

# Ответ:
{
  "success": true,
  "document": { "id": "d_042", "status": "sent", ... },
  "sign_url": "https://cert4u.ru/client.html?token=...",
  "pep_code": "483920",
  "sandbox": false
}

curl -X POST "https://cert4u.ru/api.php?action=api_1c_send_document" \
  -H "X-Api-Key: ВАШ_КЛЮЧ" \
  -H "Idempotency-Key: 1c-doc-000123" \
  -F "document=@dogovor.pdf" \
  -F "client_name=Петров Пётр Петрович" \
  -F "client_phone=+79001234567" \
  -F "sign_type=pep_only"

# Ответ:
{
  "success": true,
  "document_id": "d_043",
  "sign_url": "https://cert4u.ru/client.html?token=...",
  "sign_token": "...",
  "pep_code": "533441",
  "client": { "id": "c_015", "name": "Петров Пётр Петрович", ... },
  "sandbox": false
}

list_alt 21 метод API

Базовый вызов для любого метода: https://cert4u.ru/api.php?action=<action>. Полные параметры, форматы ответов и примеры — в справочнике api-docs.html. Для готовой интеграции с учётной системой смотрите страницу интеграция 1С и подписание.

Ниже 18 методов работы с документами и клиентами; ещё 3 метода управляют вебхуками.

Виды подписи: УКЭП (CAdES, КриптоПро) и ПЭП (одноразовый код по SMS/email). Подробности валидации и юридической значимости — в справочнике.

draw Формат подписи и совместная подпись

• Открепленная (detached) — файл .sig содержит только подпись, документ лежит отдельно.
• Прикреплённая (attached) — документ находится внутри .sig.
• Совместная — один прикреплённый .sig, в котором документ и подписи всех сторон (отправитель + клиент). Такой файл целиком проверяется, например, в Контур.Крипто. Формируется, когда подпись отправителя прикреплённая, а клиент подписывает УКЭП. В ZIP отдаётся как Документ.pdf.sig, в api_1c_verify — блок cosigned_signature.

Формат выбирается в личном кабинете: Настройки → Формат подписи УКЭП (настройка вашего аккаунта). 1С узнаёт его через api_1c_settings, прежде чем сформировать подпись для api_1c_upload_signed. Проверка подписей принимает оба формата независимо от настройки. Подробнее — в справочнике.

Как сформировать нужный формат: в 1С — последний параметр НачатьПодписаниеДанныхCAdES(…, ТипПодписиCAdES.BES, Отсоединенная): Ложь → прикреплённая, Истина → открепленная; в cryptcp — без ключа -detached → прикреплённая, с ним → открепленная; в КриптоПро Browser plug-in — SignCades(oSigner, CADESCOM_CADES_BES, bDetached). Примеры — в справочнике.

timeline Статусы документа

new  →  signed_admin  →  sent  →  completed   (обе стороны подписали)
                                 ↘  rejected    (клиент отклонил)
                                 ↘  revoked     (отозван через api_1c_revoke)

error_outline Ошибки и коды

При ошибке возвращается {"success":false,"message":"..."} с соответствующим HTTP-кодом.

webhook Вебхуки

Вместо опроса статусов настройте вебхук — Cert4U сам отправит POST на ваш URL при изменении документа. Управление вебхуками — те же методы api.php?action=…, авторизация как у остальных методов, доступ только владельцу ключа.

Методы управления

События

Серверные события (sent, revoked) отправляются сразу в момент вызова метода. События клиентского подписания (signed, completed, rejected) ловит крон-вотчер, сравнивающий статусы со снимком состояния и шлющий вебхуки на изменения.

Формат доставки

POST на ваш url, тело JSON. Таймаут 10 секунд, доставка best-effort.

POST https://ваш-сервер/webhook
Content-Type: application/json
X-Cert4U-Event: document.signed
X-Cert4U-Signature: sha256=<hex hmac_sha256(тело, secret)>

{
  "event": "document.signed",
  "doc_id": "d_042",
  "status": "signed",
  "client_id": "c_007",
  "occurred_at": "2026-06-17T10:15:00Z",
  "document": {
    "id": "d_042",
    "name": "Договор №14",
    "status": "signed",
    "client_name": "Иванов И.И."
  }
}

science Песочница (sandbox)

Песочница позволяет интегратору тестировать сценарии без реальной отправки SMS/email и без расхода денег и тарифных лимитов.

Как включить

Любым из трёх способов:

• поле sandbox=true на API-ключе;
• заголовок X-Cert4U-Sandbox: 1;
• параметр запроса sandbox=1.

Поведение

В методах api_1c_send, api_1c_send_document, api_1c_pep_send, api_1c_pep_bulk:

• реальные SMS/email не отправляются;
• код ПЭП всегда 000000;
• документ помечается sandbox:true, и в ответе возвращается "sandbox":true;
• тарифные лимиты не списываются;
• вебхук document.sent не отправляется.

На api_1c_pep_send_code (переотправка кода) песочница не распространяется — код отправляется реально.

curl -X POST "https://cert4u.ru/api.php?action=api_1c_pep_send" \
  -H "X-Api-Key: ВАШ_КЛЮЧ" \
  -H "X-Cert4U-Sandbox: 1" \
  -F "client_id=c_007" \
  -F "document=@dogovor.pdf" \
  -F "doc_name=Тест"

# Ответ:
{ "success": true, "sandbox": true, "pep_code": "000000" }

replay Идемпотентность

Чтобы обрыв связи и повтор запроса не создавали дубли документов и повторные платные SMS, передавайте заголовок Idempotency-Key: <уникальная строка> (или параметр idempotency_key). Поддерживают: api_1c_upload, api_1c_upload_signed, api_1c_send_document, api_1c_pep_send, api_1c_pep_bulk.

Повтор с тем же ключом в течение 24 часов возвращает ранее созданный документ и "idempotent": true (для api_1c_pep_bulk — "results": []) без новой отправки. Ключи действуют в пределах вашего аккаунта. Удобно использовать GUID документа 1С.

curl -X POST "https://cert4u.ru/api.php?action=api_1c_upload" \
  -H "X-Api-Key: ВАШ_КЛЮЧ" \
  -H "Idempotency-Key: 5f0c9a2e-1c-000123" \
  -F "document=@dogovor.pdf" \
  -F "doc_name=Договор №14"

translate Кириллица и 1С

Кодировка API — UTF-8. Кириллицу в query-параметрах необходимо URL-кодировать (urlencode). В 1С:Предприятие используйте встроенную функцию:

КодироватьСтроку(Значение, КодировкаURL.КодировкаURL)

Готовая обработка и пошаговая инструкция по подключению — на странице интеграция 1С и подписание. Параметры всех методов — в справочнике api-docs.html.

help_outline FAQ по интеграции

Как получить API-ключ для интеграции с 1С?

В личном кабинете: Настройки → API-ключи → создать ключ (self-serve). API доступен на тарифах Бизнес и Корпорат. На Старте API нет, на Тестовом — 10 операций в день.

Какой базовый адрес у REST API Cert4U?

Один эндпоинт: https://cert4u.ru/api.php?action=<ACTION>. Это не пути /api/v1/... — метод задаётся параметром action. Авторизация — X-Api-Key, либо Authorization: Bearer, либо api_key в query.

Как передавать кириллицу из 1С в параметрах запроса?

Кодировка UTF-8, query-параметры с кириллицей нужно урл-кодировать. В 1С — КодироватьСтроку(Значение, КодировкаURL.КодировкаURL).

Можно ли тестировать без реальной отправки SMS и расхода лимитов?

Да — включите песочницу (sandbox=true на ключе, X-Cert4U-Sandbox: 1 или sandbox=1). SMS/email не уходят, код ПЭП всегда 000000, лимиты не списываются.

Видит ли мой ключ документы других компаний?

Нет. API мультиарендный: ключ видит только данные своего аккаунта — фильтр по владельцу применяется ко всем методам. Подробнее об использовании в компании — электронная подпись для бизнеса.