README

PHP SDK для работы с API сервиса электронной подписи Podpislon.

Требования

PHP 8.1 или выше
Расширение cURL
Расширение JSON

Установка

Composer

composer require podpislon/podpislon-sdk

Ручная установка

Скачайте содержимое папки src
Подключите автозагрузку:

require_once 'path/to/sdk/src/PodpislonSDK.php';
require_once 'path/to/sdk/src/Exceptions/PodpislonException.php';
require_once 'path/to/sdk/src/Exceptions/AuthenticationException.php';
require_once 'path/to/sdk/src/Exceptions/RateLimitException.php';
require_once 'path/to/sdk/src/Exceptions/ValidationException.php';

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

<?php

use Podpislon\PodpislonSDK;

// Инициализация SDK
$sdk = new PodpislonSDK('ваш_api_токен');

// Получить информацию о компании
$info = $sdk->getInfo();
echo "Компания: " . $info['company']['name'] . "\n";
echo "Баланс подписаний: " . $info['signings'] . "\n";

API Reference

Конфигурация

use Podpislon\PodpislonSDK;

$sdk = new PodpislonSDK('api_token', [
    'baseUrl' => 'https://podpislon.ru',  // опционально
    'timeout' => 30                        // опционально, в секундах
]);

Документы

`getDocuments(array $params = [])`

Получить список документов.

// Все документы
$result = $sdk->getDocuments();
$docs = $result['data'];
$pagination = $result['pagination'];

// По конкретным ID
$result = $sdk->getDocuments(['ids' => [1, 2, 3]]);

// С фильтрацией
$result = $sdk->getDocuments([
    'filter' => [
        'dates' => ['>=' => strtotime('2024-01-01')],
        'status' => '30',  // подписанные
        'fio' => 'Иванов',
        'phone' => '79001234567'
    ],
    'page' => 1,
    'expand' => 'package'
]);

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

Код	Константа	Статус
10	`STATUS_DRAFT`	Черновик
12	`STATUS_SCHEDULED`	Запланировано
15	`STATUS_SENT`	Отправлен
20	`STATUS_VIEWED`	Просмотрен
25	`STATUS_PARTIALLY_SIGNED`	Частично подписан
30	`STATUS_SIGNED`	Подписан
35	`STATUS_ANNULMENT_REQUESTED`	Запрошено аннулирование
40	`STATUS_ANNULLED`	Аннулирован

`getDocument(int $id)`

Получить документ по ID.

$doc = $sdk->getDocument(123);

if ($doc) {
    echo "Документ: " . $doc['name'] . "\n";
    echo "Статус: " . PodpislonSDK::getStatusName($doc['status']) . "\n";
    
    // Контакты
    foreach ($doc['contacts'] as $contact) {
        echo "Подписант: " . $contact['last_name'] . " " . $contact['name'] . "\n";
    }
} else {
    echo "Документ не найден\n";
}

`createDocument(array $params)`

Создать документ для подписания.

// Простой документ с одним подписантом (файл на диске)
$result = $sdk->createDocument([
    'name' => 'Иван',
    'last_name' => 'Иванов',
    'second_name' => 'Иванович',
    'phone' => '79001234567',
    'agreement' => true,  // Согласие на обработку персональных данных
    'file' => '/path/to/document.pdf'
]);

if ($result['status']) {
    echo "Документ создан! ID: " . $result['result'] . "\n";
}

Параметры:

Параметр	Тип	Обязательный	Описание
`name`	string	Да	Имя подписанта
`last_name`	string	Да	Фамилия подписанта
`second_name`	string	Нет	Отчество подписанта
`phone`	string	Да	Телефон (формат: 79001234567)
`agreement`	bool	Да	Согласие на обработку персональных данных
`file`	string/array	Да	Путь к файлу или base64
`fileName`	string/array	При base64	Имена файлов
`contacts`	array	Нет	Массив подписантов (дополнительно к основному)
`redirect_url`	string	Нет	URL редиректа после подписания
`payment`	array	Нет	Данные платежа ['pid' => int, 'sum' => float]
`stroke_doc`	int	Нет	Строгий порядок (1 - да)
`no_sms`	bool	Нет	Не отправлять SMS
`send_date`	int	Нет	Unix timestamp для отложенной отправки
`sign_by_time`	int	Нет	Срок подписания (Unix timestamp)

Несколько подписантов:

$result = $sdk->createDocument([
    'name' => 'Иван',
    'last_name' => 'Иванов',
    'phone' => '79001234567',
    'agreement' => true,
    'contacts' => [
        ['name' => 'Иван', 'last_name' => 'Иванов', 'phone' => '79001234567'],
        ['name' => 'Петр', 'last_name' => 'Петров', 'phone' => '79999999999']
    ],
    'file' => '/path/to/document.pdf',
    'stroke_doc' => 1  // строгий порядок подписания
]);

Несколько документов:

$result = $sdk->createDocument([
    'name' => 'Иван',
    'last_name' => 'Иванов',
    'phone' => '79001234567',
    'agreement' => true,
    'file' => [
        '/path/to/contract.pdf',
        '/path/to/appendix.pdf'
    ]
]);
// result['result'] содержит массив ID созданных документов

С редиректом (без SMS):

$result = $sdk->createDocument([
    'name' => 'Иван',
    'last_name' => 'Иванов',
    'phone' => '79001234567',
    'agreement' => true,
    'file' => '/path/to/document.pdf',
    'redirect_url' => 'https://mysite.com/success',
    'no_sms' => true
]);

// result['result']['links'] содержит ссылки для подписания
foreach ($result['result']['links'] as $link) {
    echo "Ссылка для подписания: " . $link . "\n";
}

С использованием base64:

$base64Content = PodpislonSDK::fileToBase64('/path/to/document.pdf');

$result = $sdk->createDocument([
    'name' => 'Иван',
    'last_name' => 'Иванов',
    'phone' => '79001234567',
    'agreement' => true,
    'file' => $base64Content,
    'fileName' => 'contract.pdf'
]);

С платежом:

$result = $sdk->createDocument([
    'name' => 'Иван',
    'last_name' => 'Иванов',
    'phone' => '79001234567',
    'agreement' => true,
    'file' => '/path/to/document.pdf',
    'payment' => [
        'pid' => 2,      // ID платежной системы
        'sum' => 1500.00 // Сумма
    ]
]);

`getFile(int $id)`

Получить содержимое файла в base64.

$result = $sdk->getFile(123);

if ($result['status']) {
    // Декодировать и сохранить
    file_put_contents('document.pdf', base64_decode($result['result']));
    
    // Или отправить браузеру
    header('Content-Type: application/pdf');
    echo base64_decode($result['result']);
}

`downloadFile(int $id, string $savePath)`

Скачать и сохранить файл на диск.

if ($sdk->downloadFile(123, '/path/to/save/document.pdf')) {
    echo "Файл сохранен\n";
} else {
    echo "Ошибка сохранения\n";
}

`deleteDocument(int $fileId)`

Удалить документ.

$result = $sdk->deleteDocument(123);

if ($result['ok']) {
    echo "Документ удален\n";
} else {
    echo "Ошибка: " . $result['mess'] . "\n";
}

`resend(string $packageId, ?string $contactId = null)`

Повторно отправить SMS со ссылкой для подписания.

// Всем контактам в пакете
$result = $sdk->resend('cb4b683');

// Конкретному контакту
$result = $sdk->resend('cb4b683', 'ODYxMjI=');

if ($result['ok']) {
    echo "SMS отправлено\n";
} else {
    echo "Ошибка: " . $result['mess'] . "\n";
}

Информация о компании

`getInfo()`

Получить информацию о компании и балансе.

$info = $sdk->getInfo();

echo "Статус: " . ($info['status'] ? 'OK' : 'Ошибка') . "\n";
echo "Баланс подписаний: " . $info['signings'] . "\n";
echo "Компания: " . $info['company']['name'] . "\n";
echo "ИНН: " . $info['company']['inn'] . "\n";
echo "КПП: " . $info['company']['kpp'] . "\n";

`getPaySystems()`

Получить список платежных систем.

$result = $sdk->getPaySystems();

foreach ($result['result'] as $paySystem) {
    echo $paySystem['id'] . ': ' . $paySystem['name'] . "\n";
}

Утилиты

`PodpislonSDK::fileToBase64(string $filePath)`

Конвертировать файл в base64.

$base64 = PodpislonSDK::fileToBase64('/path/to/document.pdf');

`PodpislonSDK::base64ToFile(string $base64, string $savePath)`

Сохранить base64 в файл.

PodpislonSDK::base64ToFile($base64Content, '/path/to/save/document.pdf');

`PodpislonSDK::getStatusName(int|string $statusCode)`

Получить название статуса.

echo PodpislonSDK::getStatusName(30); // "Подписан"

Константы статусов

PodpislonSDK::STATUS_DRAFT;               // 10
PodpislonSDK::STATUS_SCHEDULED;           // 12
PodpislonSDK::STATUS_SENT;                // 15
PodpislonSDK::STATUS_VIEWED;              // 20
PodpislonSDK::STATUS_PARTIALLY_SIGNED;    // 25
PodpislonSDK::STATUS_SIGNED;              // 30
PodpislonSDK::STATUS_ANNULMENT_REQUESTED; // 35
PodpislonSDK::STATUS_ANNULLED;            // 40

// Словарь всех статусов
PodpislonSDK::STATUSES; // [10 => 'Черновик', ...]

Обработка ошибок

SDK генерирует исключения при ошибках:

use Podpislon\PodpislonSDK;
use Podpislon\Exceptions\PodpislonException;
use Podpislon\Exceptions\AuthenticationException;
use Podpislon\Exceptions\RateLimitException;
use Podpislon\Exceptions\ValidationException;

try {
    $result = $sdk->createDocument([...]);
} catch (ValidationException $e) {
    // Ошибка валидации параметров
    echo "Ошибка валидации: " . $e->getMessage();
} catch (AuthenticationException $e) {
    // Неверный API ключ (401)
    echo "Ошибка авторизации: " . $e->getMessage();
} catch (RateLimitException $e) {
    // Превышен лимит запросов (429)
    echo "Слишком много запросов, подождите";
} catch (PodpislonException $e) {
    // Другие ошибки API
    echo "HTTP код: " . $e->getHttpCode() . "\n";
    echo "Сообщение: " . $e->getMessage() . "\n";
    print_r($e->getResponse());
}

Полные примеры

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

<?php

require_once 'vendor/autoload.php';

use Podpislon\PodpislonSDK;
use Podpislon\Exceptions\PodpislonException;

$sdk = new PodpislonSDK('YOUR_API_TOKEN');

try {
    // Проверяем баланс
    $info = $sdk->getInfo();
    echo "Баланс: " . $info['signings'] . " подписаний\n";
    
    if ((int)$info['signings'] < 1) {
        die("Недостаточно подписаний на балансе\n");
    }
    
    // Создаем документ
    $result = $sdk->createDocument([
        'name' => 'Иван',
        'last_name' => 'Иванов',
        'second_name' => 'Иванович',
        'phone' => '79001234567',
        'agreement' => true,
        'file' => '/path/to/contract.pdf'
    ]);
    
    if ($result['status']) {
        $docId = $result['result'];
        echo "Документ создан! ID: {$docId}\n";
        
        // Получаем информацию о созданном документе
        $doc = $sdk->getDocument($docId);
        echo "Статус: " . PodpislonSDK::getStatusName($doc['status']) . "\n";
    }
    
} catch (PodpislonException $e) {
    echo "Ошибка: " . $e->getMessage() . "\n";
}

Мониторинг статуса документа

<?php

use Podpislon\PodpislonSDK;

$sdk = new PodpislonSDK('YOUR_API_TOKEN');
$docId = 123;

// Получаем документ
$doc = $sdk->getDocument($docId);

if (!$doc) {
    die("Документ не найден\n");
}

echo "Документ: " . $doc['name'] . "\n";
echo "Статус: " . PodpislonSDK::getStatusName($doc['status']) . "\n";

// Проверяем, подписан ли документ
if ((int)$doc['status'] === PodpislonSDK::STATUS_SIGNED) {
    echo "Документ подписан! Скачиваем...\n";
    
    if ($sdk->downloadFile($docId, "/downloads/{$doc['name']}.pdf")) {
        echo "Файл сохранен\n";
    }
}

Интеграция с веб-формой

<?php

require_once 'vendor/autoload.php';

use Podpislon\PodpislonSDK;
use Podpislon\Exceptions\PodpislonException;

if ($_SERVER['REQUEST_METHOD'] === 'POST') {
    $sdk = new PodpislonSDK('YOUR_API_TOKEN');
    
    try {
        // Валидация
        if (empty($_POST['name']) || empty($_POST['last_name']) || empty($_POST['phone'])) {
            throw new Exception('Заполните все обязательные поля');
        }
        
        if (empty($_FILES['document']['tmp_name'])) {
            throw new Exception('Загрузите документ');
        }
        
        // Отправляем документ
        $result = $sdk->createDocument([
            'name' => $_POST['name'],
            'last_name' => $_POST['last_name'],
            'second_name' => $_POST['second_name'] ?? '',
            'phone' => preg_replace('/\D/', '', $_POST['phone']),
            'agreement' => true,  // Пользователь должен дать согласие на форме
            'file' => $_FILES['document']['tmp_name'],
            'redirect_url' => 'https://mysite.com/thank-you'
        ]);
        
        if ($result['status']) {
            header('Location: /success?doc_id=' . $result['result']);
            exit;
        }
        
    } catch (PodpislonException $e) {
        $error = "Ошибка API: " . $e->getMessage();
    } catch (Exception $e) {
        $error = $e->getMessage();
    }
}
?>

<!DOCTYPE html>
<html>
<head>
    <title>Отправить документ на подпись</title>
</head>
<body>
    <?php if (!empty($error)): ?>
        <div style="color: red;"><?= htmlspecialchars($error) ?></div>
    <?php endif; ?>
    
    <form method="post" enctype="multipart/form-data">
        <input type="text" name="name" placeholder="Имя" required><br>
        <input type="text" name="last_name" placeholder="Фамилия" required><br>
        <input type="text" name="second_name" placeholder="Отчество"><br>
        <input type="tel" name="phone" placeholder="Телефон" required><br>
        <input type="file" name="document" accept=".pdf" required><br>
        <button type="submit">Отправить на подпись</button>
    </form>
</body>
</html>

Обработка вебхуков

<?php

/**
 * Обработчик вебхуков от Podpislon
 * URL этого скрипта нужно указать в настройках интеграции
 */

// Получаем данные вебхука
$event = $_POST['EVENT'] ?? null;
$fileId = $_POST['FILE_ID'] ?? null;
$companyId = $_POST['COMPANY_ID'] ?? null;
$signature = $_POST['SIGNATURE'] ?? null;

// Логируем событие
error_log("Podpislon webhook: {$event}, file: {$fileId}");

switch ($event) {
    case 'DOCUMENT_OPENED':
        $contact = $_POST['CONTACT'] ?? null;
        // Документ просмотрен
        // Можно обновить статус в вашей системе
        break;
        
    case 'DOCUMENT_SIGNED':
        // Документ подписан
        // Можно скачать подписанный документ и сохранить
        $sdk = new \Podpislon\PodpislonSDK('YOUR_API_TOKEN');
        $sdk->downloadFile((int)$fileId, "/signed_docs/{$fileId}.pdf");
        break;
        
    case 'CLIENT_DATA_REQUEST_SUBMITTED':
        $clientId = $_POST['CLIENT_ID'] ?? null;
        $clientName = $_POST['CLIENT_NAME'] ?? null;
        $clientLastName = $_POST['CLIENT_LAST_NAME'] ?? null;
        $clientPhone = $_POST['CLIENT_PHONE'] ?? null;
        // Форма персональных данных заполнена
        // Можно создать контакт в вашей CRM
        break;
}

// Отвечаем 200 OK
http_response_code(200);
echo 'OK';

Лицензия

MIT

Поддержка

Документация API: https://api.podpislon.ru/
Email: support@podpislon.ru

podpislon / podpislon-sdk

Maintainers

Details