Podpislon JavaScript SDK

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

Установка

NPM

npm install podpislon-sdk

CDN

<script src="https://cdn.jsdelivr.net/npm/@podpislon/podpislon-sdk/podpislon.min.js"></script>

Скачать напрямую

Скачайте файл podpislon.js и подключите к проекту:

<script src="podpislon.js"></script>

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

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

// Получить информацию о компании
const info = await sdk.getInfo();
console.log(`Компания: ${info.company.name}`);
console.log(`Баланс подписаний: ${info.signings}`);

API Reference

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

const sdk = new PodpislonSDK({
  apiToken: string     // API токен (обязательно, включает ID компании)
});

Документы

getDocuments(params?)

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

// Все документы
const { data: docs, pagination } = await sdk.getDocuments();

// По конкретным ID
const { data: docs } = await sdk.getDocuments({ 
  ids: [1, 2, 3] 
});

// С фильтрацией
const { data: docs } = await sdk.getDocuments({
  filter: {
    dates: { '>': 1704067200 },  // timestamp
    status: '30',                // 10-отправлен, 20-открыт, 30-подписан, 40-аннулирован
    fio: 'Иванов Иван',
    phone: '79001234567'
  }
});

Статусы документов: | Код | Статус | |-----|--------| | 10 | Черновик | | 12 | Запланирован | | 20 | Просмотрен | | 25 | Частично подписан | | 30 | Подписан | | 35 | Запрошено аннулирование | | 40 | Аннулирован |

getDocument(id)

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

const doc = await sdk.getDocument(123);

if (doc) {
  console.log(`Документ: ${doc.name}`);
  console.log(`Статус: ${PodpislonSDK.STATUSES[doc.status]}`);
  console.log(`Подписант: ${doc.contact_last_name} ${doc.contact_name}`);
  console.log(`Телефон: ${doc.contact_phone}`);
  
  if (doc.sign_at) {
    console.log(`Подписан: ${new Date(doc.sign_at * 1000).toLocaleString()}`);
  }
} else {
  console.log('Документ не найден');
}

createDocument(params)

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

// Простой документ с одним подписантом
const result = await sdk.createDocument({
  name: 'Иван',
  last_name: 'Иванов',
  second_name: 'Иванович',
  phone: '79001234567',
  file: document.getElementById('fileInput').files[0],
  agreement: true // согласие на обработку данных
});

if (result.status) {
  console.log('Документ создан, ID:', result.result);
}

Параметры:

| Параметр | Тип | Обязательный | Описание | |----------|-----|--------------|----------| | name | string | Да* | Имя подписанта | | last_name | string | Да* | Фамилия подписанта | | second_name | string | Нет | Отчество подписанта | | phone | string | Да* | Телефон (формат: 79001234567) | | file | File/Blob/string | Да | Файл(ы) PDF/DOC/DOCX | | sigFile | File/Blob/string | Нет | Открепленная подпись КЭП | | contacts | Array | Нет | Массив подписантов (вместо name/last_name/phone) | | redirect_url | string | Нет | URL редиректа после подписания | | stroke_doc | 0/1 | Нет | Строгий порядок подписания | | no_sms | boolean | Нет | Не отправлять SMS | | auth | string[] | Нет | Доп. авторизация: ['sber'] | | agreement | boolean | Да | Согласие на обработку данных | | pid | number | Нет | ID платёжной системы | | sum | number | Нет | Сумма оплаты |

* Обязательные если не используется contacts

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

const result = await sdk.createDocument({
  contacts: [
    { name: 'Иван', last_name: 'Иванов', phone: '79001234567' },
    { name: 'Петр', last_name: 'Петров', phone: '79009876543' }
  ],
  file: pdfFile,
  stroke_doc: 1, // строгий порядок подписания
  agreement: true
});

С редиректом:

const result = await sdk.createDocument({
  name: 'Иван',
  last_name: 'Иванов', 
  phone: '79001234567',
  file: pdfFile,
  redirect_url: 'https://mysite.com/success',
  no_sms: true, // без SMS, ссылка вернется в ответе
  agreement: true
});

// result.result.links содержит ссылку для подписания

getFile(id)

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

const { status, result: base64 } = await sdk.getFile(123);

// Показать в iframe
const iframe = document.getElementById('preview');
iframe.src = 'data:application/pdf;base64,' + base64;

downloadFile(id, filename?)

Скачать файл документа (только для браузера).

await sdk.downloadFile(123, 'contract.pdf');

deleteDocument(fileId)

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

const result = await sdk.deleteDocument(123);
if (result.ok) {
  console.log('Документ удален');
}

Информация

getInfo()

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

const info = await sdk.getInfo();
// {
//   status: true,
//   signings: 150,
//   company: {
//     name: 'ООО "Компания"',
//     inn: '1234567890',
//     kpp: '123456789'
//   }
// }

getPaySystems()

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

const { result: paySystems } = await sdk.getPaySystems();
// [{ id: 1, name: 'Tinkoff' }, { id: 2, name: 'SberPay' }]

Операции

resend(code, contactId?)

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

const result = await sdk.resend('abc123xyz');
if (result.ok) {
  console.log('SMS отправлено');
}

Утилиты

PodpislonSDK.fileToBase64(file)

Конвертировать File в base64.

const base64 = await PodpislonSDK.fileToBase64(file);

PodpislonSDK.base64ToBlob(base64, mimeType?)

Конвертировать base64 в Blob.

const blob = PodpislonSDK.base64ToBlob(base64Content, 'application/pdf');
const url = URL.createObjectURL(blob);

PodpislonSDK.STATUSES

Словарь статусов документов.

console.log(PodpislonSDK.STATUSES[30]); // "Подписан"

Примеры

Полный пример с формой

<form id="signForm">
  <input type="text" name="name" placeholder="Имя" required>
  <input type="text" name="last_name" placeholder="Фамилия" required>
  <input type="tel" name="phone" placeholder="Телефон" required>
  <input type="file" name="file" accept=".pdf,.doc,.docx" required>
  <button type="submit">Отправить на подпись</button>
</form>

<script src="podpislon.js"></script>
<script>
const sdk = new PodpislonSDK({
  apiToken: 'YOUR_API_TOKEN'
});

document.getElementById('signForm').addEventListener('submit', async (e) => {
  e.preventDefault();
  
  const formData = new FormData(e.target);
  
  try {
    const result = await sdk.createDocument({
      name: formData.get('name'),
      last_name: formData.get('last_name'),
      phone: formData.get('phone').replace(/\D/g, ''),
      file: formData.get('file'),
      agreement: true // подписант дал согласие
    });
    
    if (result.status) {
      alert('Документ создан! ID: ' + result.result);
    } else {
      alert('Ошибка: ' + result.message);
    }
  } catch (error) {
    alert('Ошибка: ' + error.message);
  }
});
</script>

Node.js с FormData

const PodpislonSDK = require('podpislon-sdk');
const fs = require('fs');
const FormData = require('form-data');

const sdk = new PodpislonSDK({
  apiToken: 'YOUR_API_TOKEN'
});

// Для Node.js нужно передать файл как base64
const fileBuffer = fs.readFileSync('contract.pdf');
const base64File = fileBuffer.toString('base64');

const result = await sdk.createDocument({
  name: 'Иван',
  last_name: 'Иванов',
  phone: '79001234567',
  file: base64File,
  agreement: true
});

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

try {
  const result = await sdk.createDocument({ ... });
} catch (error) {
  console.error('HTTP статус:', error.status);
  console.error('Сообщение:', error.message);
  console.error('Ответ API:', error.response);
}

TypeScript

SDK включает TypeScript определения:

import PodpislonSDK, { CreateDocumentParams, GetInfoResponse } from 'podpislon-sdk';

const sdk = new PodpislonSDK({
  apiToken: 'your_token'
});

const params: CreateDocumentParams = {
  name: 'Иван',
  last_name: 'Иванов',
  phone: '79001234567',
  file: fileInput.files[0]
};

const info: GetInfoResponse = await sdk.getInfo();

Лицензия

MIT

Поддержка

• Документация API: https://api.podpislon.ru/
• Email: [email protected]