npm package: @podpislon/podpislon-sdk
Description: JavaScript SDK для работы с API сервиса электронной подписи Podpislon
Author: Podpislon
Latest version: 1.0.1

# Podpislon JavaScript SDK

JavaScript SDK для работы с API сервиса электронной подписи [Podpislon](https://api.podpislon.ru/).

## Установка

### NPM

```bash
npm install podpislon-sdk
```

### CDN

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

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

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

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

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

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

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

## API Reference

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

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

---

### Документы

#### `getDocuments(params?)`

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

```javascript
// Все документы
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.

```javascript
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)`

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

```javascript
// Простой документ с одним подписантом
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`

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

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

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

```javascript
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.

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

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

---

#### `downloadFile(id, filename?)`

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

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

---

#### `deleteDocument(fileId)`

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

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

---

### Информация

#### `getInfo()`

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

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

---

#### `getPaySystems()`

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

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

---

### Операции

#### `resend(code, contactId?)`

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

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

---

## Утилиты

### `PodpislonSDK.fileToBase64(file)`

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

```javascript
const base64 = await PodpislonSDK.fileToBase64(file);
```

### `PodpislonSDK.base64ToBlob(base64, mimeType?)`

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

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

### `PodpislonSDK.STATUSES`

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

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

---

## Примеры

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

```html
<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

```javascript
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
});
```

---

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

```javascript
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 определения:

```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: support@podpislon.ru