API для работы с файлами (PAdES и CMS)

В этой инструкции вы узнаете, как интегрировать функции электронной подписи в ваши приложения с помощью API КриптоАРМ Server. Мы подробно разберем форматы PAdES для PDF-документов и CMS/CAdES для произвольных файлов, рассмотрим оба варианта взаимодействия — через загрузку файлов и через JSON (Base64), а также приведем практические примеры запросов для подписания, проверки и улучшения подписей.

Содержание:

• Обзор
• PAdES API
• CMS API
• JSON API (Base64)
• Примеры использования
• Группировка методов в Swagger
• Поддерживаемые форматы файлов

💡 Полную спецификацию API можно скачать или импортировать в Swagger UI: swagger.yml

---

Обзор

КриптоАРМ Server предоставляет набор API-методов для работы с электронными подписями.

Поддерживаются два формата подписи:

• PAdES — электронная подпись PDF-документов
• CMS / CAdES — универсальная подпись произвольных файлов

API предоставляет два варианта работы:

Тип API	Назначение
Файловый API	загрузка файлов через multipart/form-data
JSON API	передача данных в формате Base64

Файловые методы обычно используются при интеграции с веб-формами и внешними системами.

---

PAdES API

1. Подписание PDF файла

POST

/pades/sign-file

Метод загружает PDF-документ и создает подпись PAdES с визуализацией штампа подписи.

Параметры запроса (multipart/form-data)

Параметр	Тип	Обязательный	Описание
pdf	file	да	PDF файл для подписания
cert	file	нет	сертификат (.cer, .p7b, .crt)
password	string	нет	пароль контейнера ключа
params	string	нет	JSON с параметрами штампа

Пример параметров штампа:

{
  "stampMargin": 80,
  "stampColor": "#4c40d2",
  "stampScale": 1
}

Ответ

Метод возвращает файл:

signed.pdf

2. Проверка подписи PDF файла

POST

/pades/verify-file

Метод проверяет подписи в PDF документе.

Параметры запроса (multipart/form-data)

Параметр	Тип	Обязательный	Описание
pdf	file	да	PDF файл
meta	string	нет	дополнительные параметры проверки

Пример ответа

{
  "status": 200,
  "message": "Все подписи действительны",
  "isValid": true,
  "isValidSign": true,
  "signs": [...]
}

---

CMS API

1. Создание подписи файла

POST

/cms/sign-file

Метод создает CMS подпись для переданного файла.

Параметры запроса (multipart/form-data)

Формат: multipart/form-data

Параметр	Тип	Обязательный	Описание
data	file	да	файл для подписания
cert	file	нет	сертификат (.cer, .p7b, .crt)
password	string	нет	пароль контейнера ключа

Ответ

Метод возвращает файл подписи:

signed.sig

2. Проверка подписи файла

POST

/cms/verify-file

Метод проверяет подпись CMS.

Параметры запроса (multipart/form-data)

Параметр	Тип	Обязательный	Описание
cms	file	да	файл подписи
data	file	нет	файл данных (для открепленной подписи)
enhancedType	string	нет	тип усовершенствования подписи
meta	string	нет	дополнительные параметры

Ответ

{
  "status": 200,
  "message": "Все подписи действительны",
  "isValid": true,
  "isValidSign": true,
  "signs": [...]
}

3. Улучшение подписи файла

POST

/cms/enhance-file

Метод улучшает существующую CMS подпись.

Параметры запроса (multipart/form-data):

Параметр	Тип	Обязательный	Описание
cms	file	да	файл подписи
data	file	да	файл данных
enhancedType	string	да	тип улучшения подписи

Поддерживаемые типы улучшения

Тип	Описание
CAdES-T	подпись с временной меткой
CAdES-X Long Type 1	долгосрочная подпись
CAdES-A	архивная подпись

Ответ

Метод возвращает файл:

enhanced.sig

---

JSON API (Base64)

Помимо файловых методов, сервис поддерживает API с передачей данных в Base64.

PAdES-методы

Метод	Назначение
POST /pades/sign	подписание PDF
POST /pades/verify	проверка подписи

CMS методы

Метод	Назначение
POST /cms/sign	создание подписи
POST /cms/verify	проверка подписи
POST /cms/enhance	улучшение подписи

Примеры использования

cURL для подписания PDF файла

curl -X POST "http://localhost:3037/pades/sign-file" \
  -H "Content-Type: multipart/form-data" \
  -F "pdf=@document.pdf" \
  -F "cert=@certificate.cer" \
  -F "password=your_password" \
  -F 'params={"stampMargin": 80, "stampColor": "#4c40d2", "stampScale": 1}' \
  --output signed.pdf

cURL для проверки PDF файла

curl -X POST "http://localhost:3037/pades/verify-file" \
  -H "Content-Type: multipart/form-data" \
  -F "pdf=@signed_document.pdf"

cURL для создания CMS подписи

curl -X POST "http://localhost:3037/cms/sign-file" \
  -H "Content-Type: multipart/form-data" \
  -F "data=@document.pdf" \
  -F "cert=@certificate.cer" \
  -F "password=your_password" \
  --output signed.sig

cURL для проверки CMS подписи

curl -X POST "http://localhost:3037/cms/verify-file" \
  -H "Content-Type: multipart/form-data" \
  -F "cms=@signature.p7b" \
  -F "data=@document.pdf"

cURL для улучшения CMS подписи

curl -X POST "http://localhost:3037/cms/enhance-file" \
  -H "Content-Type: multipart/form-data" \
  -F "cms=@signature.p7b" \
  -F "data=@document.pdf" \
  -F "enhancedType=CAdES-T" \
  --output enhanced.sig

---

Группировка методов в Swagger

Методы API сгруппированы по тегам:

Тег	Описание
PAdES	работа с подписями PDF
CMS	работа с CMS / CAdES подписями

Это упрощает навигацию по методам в Swagger UI.

---

Поддерживаемые форматы файлов

Поддерживаемые форматы сертификатов

Формат	Описание
.cer	X.509 сертификат
.crt	сертификат X.509
.p7b	PKCS#7 контейнер сертификатов

Поддерживаемые форматы данных

Поддерживаются любые файлы для создания подписи.

Наиболее распространенные:

• .pdf
• .xml
• .docx
• .xlsx

Форматы результирующих файлов

Расширение	Описание
.pdf	PDF документ с подписью PAdES
.sig	CMS / CAdES подпись

Предыдущая

Следующая