# Подпислон API

> REST API сервиса Подпислон для автоматизации документооборота с физическими лицами: отправка документов на подпись, получение статусов и файлов, управление контактами компании, кастомными полями и обработчиками событий (вебхуками). Предназначен для интеграции с CRM, ERP, CMS и SAP, чтобы работать в одном окне.

Важно: документация находится на `api.podpislon.ru`, а сами запросы к API отправляются на другой хост — базовый URL `https://podpislon.ru/integration`. Все пути ниже указаны относительно базового URL.

Авторизация: заголовок `X-Api-Key: ВашАпиКлюч`. Ключ создаётся в личном кабинете на странице «Интеграции». Ограничение — 4 запроса в секунду на один ключ; при превышении возвращается `429`.

Версия спецификации — OpenAPI 3.1.0, версия API — 1.0.4.

- [OpenAPI-спецификация (YAML)](https://api.podpislon.ru/podpislon-api.yaml): полное машиночитаемое описание всех эндпоинтов, схем и кодов ответов — основной источник для интеграции
- [Интерактивная документация (Swagger UI)](https://api.podpislon.ru/): те же методы с примерами запросов и возможностью выполнить их из браузера
- [Создание API-ключа](https://podpislon.ru/lk/integrations): страница «Интеграции» в личном кабинете, где выпускается ключ и настраиваются вебхуки

## Документы

Работа с документами: отправка на подпись, получение списка и статусов, скачивание файла, переотправка ссылки клиенту, удаление.

В ответе на список документов приходят заголовки пагинации: `x-pagination-current-page`, `x-pagination-page-count`, `x-pagination-per-page`, `x-pagination-total-count`. Параметр `contact` устарел — вместо него следует использовать массив `contacts`.

- [POST /](https://api.podpislon.ru/#/Document/getDocs): получить список документов с фильтрами и пагинацией
- [PUT /add-document](https://api.podpislon.ru/#/Document/addDoc): добавить документ и отправить его на подпись
- [POST /get-file](https://api.podpislon.ru/#/Document/getDoc): получить файл документа по id
- [POST /resend/{package_id}](https://api.podpislon.ru/#/Document/resend): переотправить клиенту ссылку на подписание
- [DELETE /delete-document/{file_id}](https://api.podpislon.ru/#/Document/deleteDocument): удалить документ

## Контакты (REST API v2)

Ресурсный REST API для управления контактами компании. Создание, изменение и удаление доступны только API-ключу пользователя с правами администратора компании.

- [GET /v2/contacts](https://api.podpislon.ru/#/Contact/listContacts): список контактов
- [POST /v2/contacts](https://api.podpislon.ru/#/Contact/createContact): создать контакт
- [GET /v2/contacts/{id}](https://api.podpislon.ru/#/Contact/getContact): получить контакт по id
- [PUT /v2/contacts/{id}](https://api.podpislon.ru/#/Contact/updateContact): обновить контакт
- [DELETE /v2/contacts/{id}](https://api.podpislon.ru/#/Contact/deleteContact): удалить контакт

## Кастомные поля контактов (REST API v2)

Дополнительные поля карточки контакта. Изменяющие методы требуют прав администратора компании.

- [GET /v2/custom-fields](https://api.podpislon.ru/#/Custom-Fields/listCustomFields): список кастомных полей
- [POST /v2/custom-fields](https://api.podpislon.ru/#/Custom-Fields/createCustomField): создать кастомное поле
- [PUT /v2/custom-fields/{id}](https://api.podpislon.ru/#/Custom-Fields/updateCustomField): переименовать кастомное поле
- [DELETE /v2/custom-fields/{id}](https://api.podpislon.ru/#/Custom-Fields/deleteCustomField): удалить кастомное поле

## Обработчики событий (REST API v2)

Управление адресами, на которые сервис отправляет вебхуки. Настраиваются также вручную в личном кабинете на странице «Интеграции». Изменяющие методы требуют прав администратора компании.

- [GET /v2/webhooks](https://api.podpislon.ru/#/Webhook-Endpoints/listWebhooks): список обработчиков событий
- [POST /v2/webhooks](https://api.podpislon.ru/#/Webhook-Endpoints/createWebhook): добавить обработчик событий
- [GET /v2/webhooks/{id}](https://api.podpislon.ru/#/Webhook-Endpoints/getWebhook): получить обработчик событий
- [PUT /v2/webhooks/{id}](https://api.podpislon.ru/#/Webhook-Endpoints/updateWebhook): изменить обработчик событий
- [DELETE /v2/webhooks/{id}](https://api.podpislon.ru/#/Webhook-Endpoints/deleteWebhook): удалить обработчик событий

## События (вебхуки)

Система событий отправляет HTTP POST-запросы на указанные URL обработчиков. Тело запроса кодируется как `application/x-www-form-urlencoded`.

Общие поля: `EVENT` (тип события), `COMPANY_ID` (ID компании), `SIGNATURE` (подпись запроса для проверки целостности).

- `DOCUMENT_OPENED` — документ просмотрен. Дополнительно: `FILE_ID`, `CONTACT` (телефон клиента).
- `DOCUMENT_SIGNED` — документ подписан. Дополнительно: `FILE_ID`.
- `CLIENT_DATA_REQUEST_SUBMITTED` — форма персональных данных заполнена. Дополнительно: `CLIENT_ID`, `CLIENT_NAME`, `CLIENT_LAST_NAME`, `CLIENT_PHONE`.

Пример тела запроса: `EVENT=DOCUMENT_SIGNED&FILE_ID=1234&COMPANY_ID=12&SIGNATURE=1a2b3c4d5e6f`

- [Документ просмотрен](https://api.podpislon.ru/#/Webhooks/webhookDocumentOpened): описание payload события `DOCUMENT_OPENED`
- [Документ подписан](https://api.podpislon.ru/#/Webhooks/webhookDocumentSigned): описание payload события `DOCUMENT_SIGNED`
- [Форма персональных данных заполнена](https://api.podpislon.ru/#/Webhooks/webhookClientDataRequestSubmitted): описание payload события `CLIENT_DATA_REQUEST_SUBMITTED`

## Компания

- [GET /get-info](https://api.podpislon.ru/#/Company/getInfo): информация о компании — название, ИНН, КПП, баланс документов
- [GET /pay-systems](https://api.podpislon.ru/#/Pay-System/paySystems): список платёжных систем компании

## SDK

Официальные библиотеки для работы с API. Во всех случаях инициализация выполняется API-ключом из личного кабинета.

- JavaScript — npm-пакет `@podpislon/podpislon-sdk`, установка `npm install @podpislon/podpislon-sdk`. Доступен и через CDN: `https://cdn.jsdelivr.net/npm/@podpislon/podpislon-sdk/podpislon.min.js`
- PHP — Composer-пакет `podpislon/podpislon-sdk`, установка `composer require podpislon/podpislon-sdk`. Использование: `$sdk = new Podpislon\PodpislonSDK('ваш_api_токен');`
- Python — PyPI-пакет `podpislon`, установка `pip install podpislon`, требуется Python 3.8+. Использование: `sdk = PodpislonSDK('ваш_api_токен')`

- [Пакет podpislon на PyPI](https://pypi.org/project/podpislon/): Python SDK, установка и changelog

## Коды ответов

- `400` — некорректный запрос
- `401` — отсутствует или недействителен API-ключ
- `403` — недостаточно прав (для изменяющих методов v2 нужны права администратора компании)
- `404` — ресурс не найден
- `422` — ошибка валидации данных
- `429` — превышен лимит 4 запроса в секунду
- `500` — внутренняя ошибка сервиса

## Optional

- [Подпислон — главная](https://podpislon.ru/): описание сервиса электронного документооборота с физическими лицами
- [Готовые интеграции](https://podpislon.ru/integrations): Битрикс24, amoCRM, AlfaCRM и 1С — без разработки
- [База знаний](https://podpislon.ru/knowledge-base/registraciia-v-servise): инструкции по работе с личным кабинетом
- [Обновления сервиса](https://podpislon.ru/updates): история релизов, включая изменения API