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

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 запросов в минуту на ключ. При превышении — 429.
• Дневные лимиты операций по тарифу: Бизнес — 100 операций/день; Корпорат — без лимита; Тестовый — 10/день.

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

Кодировка — 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" \
  -H "X-Api-Key: ВАШ_КЛЮЧ" \
  -F "document=@dogovor.pdf" \
  -F "doc_name=Договор №14" \
  -F "description=Поставка"

# Ответ:
{ "success": true, "doc_id": "d_042", "status": "new" }

# 3a. Серверная подпись (OpenSSL)
curl -X POST "https://cert4u.ru/api.php?action=api_1c_sign_admin" \
  -H "X-Api-Key: ВАШ_КЛЮЧ" \
  -d "doc_id=d_042"

# 3b. Отправка клиенту (ПЭП по 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,
  "status": "sent",
  "sign_url": "https://cert4u.ru/client.html?d=d_042&t=...",
  "pep_code": "483920"
}

list_alt 16 методов API

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

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

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_pep_send, api_1c_pep_bulk:

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

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" }

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 мультиарендный: ключ видит только данные своего аккаунта — фильтр по владельцу применяется ко всем методам. Подробнее об использовании в компании — электронная подпись для бизнеса.