API системы БСО-123

API - автоматическое создание бланков на Вашей стороне

API - это инструмент (протокол и средства) общения различных систем.
В нашем случае это - способ использовать функционал системы БСО-123 автоматически, из другой системы / программы / сайта.
Например, у Вас есть собственная система учёта заказов и Вы хотите распечатывать в ней готовые БСО по нажатию одной кнопки, чтобы Ваша система просто передавала нужные данные (услуга/цена) к нам.
API позволяет это сделать.

Известные ограничения
1. Общение Вашей системы с БСО-123 именное - то есть происходит от имени какого-то пользователя Вашего аккаунта.
В целях безопасности с API могут работать только пользователи с правами "БСО".
То есть, это не может быть "admin" (администратор аккаунта) или любой другой пользователь с полными правами.
Вполне нормальным считается создать отдельного пользователя для этой цели, например, с логином "api".

2. Нельзя создавать пустые бланки с помощью API, так как они должны быть распечатаны один раз, а удостовериться в этом мы можем только разрешая печать из нашего интерфейса.

Пожалуйста, учтите, что для внедрения (настройки) этого взаимодействия как правило необходимы навыки программирования. Как вариант, Вы можете пригласить разработчика со стороны, чтобы он это сделал для Вас.
Можете даже обратиться к нам, если у Вас нет своих разработчиков под рукой.
Далее следует описание нашей API с техническими подробностями интеграции, которые нужны непосредственным специалистам для разработки взаимодействия.
Если Вы приглашаете разработчиков, просто пришлите им ссылку на эту страницу.

Общее описание

API не отличается экстравагантностью и следует современным стандартам для межсайтовых API - принимает POST запросы, отвечает в JSON.
Запросы и ответы ожидаются и отдаются в кодировке UTF-8.
Адрес API один: https://bso123.ru/api

В целях безопасности с API могут работать только пользователи с правами "БСО".
То есть, это не может быть "admin" (администратор аккаунта) или любой другой пользователь с полными правами.

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

Название Параметр в запросе Формат Пример
Вызываемый метод action string check, create
E-mail email string moya@kompani.ya
Логин login string api-user
Хэш от пароля (md5) hash string(32) ade1234ade8769da6467e72c98a9b432

В ответ приходит JSON.
В минимальном варианте он содержит поле result (bool). Если result = false, то будет ещё поле error, которое содержит текст ошибки (string), например "Метод API не найден".

Метод check

Метод служит для проверки возможности пользователя создавать бланки в конкретной серии.
Полезно, если Вы интегрируете нашу систему в другую, где пользователи будут вводить свои учётные данные от БСО-123.
Помимо общих параметров, метод check ожидает ещё один:

Название Параметр в запросе Формат Пример
Имя серии series string(2) АВ, БХ, ЧП

Метод возвращает только стандартное поле - result.
Если result = true, значит этот пользователь в этой серии может создать бланк через API.
Если result = false, то будет ещё текст ошибки в error, например "Неверный логин или пароль", "В серии нельзя создавать бланки", "Серия не найдена".

Метод create

Метод служит для непосредственного создания бланков.
Помимо обязательных параметров, ожидает следующие:

Название Параметр в запросе Формат Пример
Имя серии series string(2) АВ, БХ, ЧП
Массив значений для бланка fields array смотри ниже

Поля в fields соответствуют названию полей в шаблонах бланков (на сайте раздел Настройки → Шаблоны бланков).
Все ключи должны быть в верхнем регистре (как приведено в примерах ниже).
Обязательные элементы fields:

  • fields[СПОСОБ-ОПЛАТЫ] - int (1 означает оплату картой, любое другое значение - наличными);
  • fields[БЛОК-УСЛУГ] - array с наименованием, ценой и кол-вом, например:
  • fields[БЛОК-УСЛУГ][0][НАИМЕНОВАНИЕ] = 'Замена слухового динамика Nokia 7600'
  • fields[БЛОК-УСЛУГ][0][ЦЕНА] = 5000
  • fields[БЛОК-УСЛУГ][0][КОЛИЧЕСТВО] = 1
  • fields[БЛОК-УСЛУГ][1][НАИМЕНОВАНИЕ] = 'Замена слухового динамика Nokia 7600-2'
  • fields[БЛОК-УСЛУГ][1][ЦЕНА] = 300
  • fields[БЛОК-УСЛУГ][1][КОЛИЧЕСТВО] = 3
  • ...

Остальные поля заполняются по желанию/необходимости (Имя клиента, Телефон, Адрес, любые собственные поля в своих шаблонах).
Создание пустых бланков через API на данный момент не предусмотрено, поэтому БЛОК-УСЛУГ - обязательный момент.
В ответ, если result = true, будет ещё одно поле с названием blank (string).
Поле содержит HTML-код бланка, сжатый gzip и в кодировке base64.
На своей стороне для получения HTML достаточно распаковать это обратно.
В PHP, например, это выглядит так:
$html = gzuncompress( base64_decode( $result['blank'] ) );

HTML-код бланка можно сразу выводить на печать для конечного юзера или преобразовать, скажем, в PDF или изображение средствами вроде wkhtmltopdf / wkhtmltoimage.
Сохранять HTML на своей стороне также можно, если он понадобится ещё.

Что дальше?

Мы разрабатывали (и дополняем) API по мере возникновения необходимости в этом у вас, наших клиентов.
Если Вам не хватает какого-то метода, что-то непонятно или не работает, напишите нам и скорее всего мы что-нибудь придумаем.

Спасибо за выбор БСО-123!