4.3.1. Для разработчиков собственного обмена. Описание API
API интерфейс используется для того, чтобы интегрировать возможности сервиса в личный проект клиента. API предназначен для разработчиков.
REST API сервиса работает по протоколу HTTP и представляет собой набор методов, с помощью которых совершаются запросы и возвращаются ответы для
каждой операции.
Все ответы приходят в виде JSON структуры вида :
{"error":0,
"description":"Ошибок нет",
"number":"2",
"alive":0,
"balance":0}
Ограничение на количество запросов - 10 запросов в секунду.
Все ссылки на запросы к API в данной документации включают обязательный основной URL: https://dominat.pro/poscloud/posmain/posmain_1.php
Процесс авторизации возможен при наличии персонального ключа (токена), который содержится во входящих параметрах в каждом запросе к API.
Состоит из трех частей "токен клиента", "токен точки подключения", "Токен оборудования". Токены выдает менеджер сервиса по запросу. Названия параметров и пример запроса: https://dominat.pro/poscloud/posmain/posmain_1.php?pos=ТокенТочкиПодключения&enter_point=ТокенКлиента&cash_iden=ТокенОборудования
Основным идентификатором покупателя является номер карты. Дополнительным идентификатором - номер мобильного телефона. Номер телефона при передаче и
получении всегда начинается с цифры "9".
Алгоритмы работы с API:
1. Синхронизировать сторонний аккаунт с аккаунтом системы лояльности :
- запросите у покупателя номер телефона.
- для подтверждения принадлежности покупателя к номеру телефона, который он указал - сделайте запрос "Отправить СМС с кодом регистрации". Если покупатель ввел правильный код, продолжите подключение аккаунта:
- сделайте запрос к API баланс бонусов по номеру телефона.
Если запрос возвращает ошибку 81 (номер телефона отсутствует в базе), зарегистрируйте пользователя в системе лояльности при помощи запроса "Получить новую карту", сохраните в своем аккаунте номер карты и номер телефона.
Если запрос не возвращает ошибку, сохраните в своем аккаунте номер карты и номер телефона.
2. Для оплаты товара бонусами - сделайте запрос "Списать бонусы"
3. Для начисления бонусов после покупки товара - сделайте запрос "Начислить бонусы"
Описание запросов:
Получить остаток бонусов по карте/номеру телефона :
Входящие параметры :
direction=’getbalance’ number – номер карты, back =0, phone – номер телефона (необязательный параметр, если присутствует, то клиент ищется по нему, а не по номеру карты)
Ответ на запрос :
JSON : error – код ошибки, description – описание ошибки, number – номер карты, alive – блокировка карты (0 - карта заблокирована, 1 - активна), balance – запрашиваемый баланс
Получить новую карту (зарегистрировать нового покупателя в системе лояльности) :
Входящие параметры:
direction=’cardselfreg’, phone - номер телефона
Ответ на запрос:
JSON: error – код ошибки, description – описание ошибки, number – номер карты, alive =0, balance=0
Начислить бонусы на карту :
Входящие параметры:
direction=’in’, number – номер карты, balance – величина начисляемого бонуса, description – текстовый комментарий к операции
Ответ на запрос :
JSON : error – код ошибки, description – описание ошибки, number – номер карты, alive – блокировка карты (0 - карта заблокирована, 1 - активна), balance – остаток на карте после совершённой операции начисления бонусов
Списать бонусы с карты:
Входящие параметры :
direction=’out’, number – номер карты, balance – величина списываемого бонуса, description – текстовый комментарий к операции
Ответ на запрос:
JSON: error – код ошибки, description – описание ошибки, number – номер карты, alive – блокировка карты (0 - карта заблокирована, 1 - активна), balance – остаток на карте после совершённой операции списания бонусов
Отправить СМС с кодом регистрации :
Входящие параметры:
direction=’sendchecksms’, phone – телефон, по которому будет определён покупатель и на который будет выслана СМС
Ответ на запрос:
JSON строка, параметры: error – код ошибки, description – описание ошибки (если ошибок нет, то код, отправленный по СМС), number – номер карты, alive – блокировка карты (0 - карта заблокирована, 1 - активна), balance – остаток бонусов
Создать заказ на доставку товаров:
Входящие параметры:
direction=’zakazcreate’, phone – номер телефона покупателя, number - номер карты покупателя, fio - фио покупателя (если нет карты), uid – внешний код, street - улица, house - номер дома, flat - номер квартиры, liter - буква номера дома, doorway - номер подъезда, floor - этаж, latitude - широта, longitude - долгота, ontime - время начала доставки заказа, ontime_end - время окончания доставки заказа, id_courier - id курьера, prod_code – внешний код продавца, id_typeopl - id типа оплаты, delivery_price - цена доставки, info - дополнительное описание, person_count - количество персон, zakaz_price - цена заказа, zakaz_number - внешний номер заказа, pickup - самовывоз, prepare_change - приготовить сдачу, intercom - код домофона, id_city – код города, list – JSON строка с массивом товаров goods. Поля массива goods: uid - uid товара, outcode – внешний код товара, cnt - количество товара, price - цена, pr_disc - цена со скидкой. Кодировка текстовых полей: UTF-8
Ответ на запрос:
JSON строка, параметры: error – код ошибки, description – описание ошибки, number = id заказа, alive=0, balance=0
Установить ID товара на сайте:
Входящие параметры:
direction=’setgoodwebsite’, list = '[{ "outcode":"Код товара во внешней системе", "website":"ID товара на сайте"}, {...}, ...]'
Ответ на запрос:
JSON строка, параметры: error – код ошибки, description – описание ошибки, result – пустой массив
Установить заказу заданный статус:
Входящие параметры:
direction=’setzakazstat’, id_zakaz – id заказа, id_status – id устанавливаемого статуса
Ответ на запрос:
JSON строка, параметры: error – код ошибки, description – описание ошибки, number =0, alive =0, balance=0
Добавить строку оплаты заказа:
Входящие параметры:
direction=’addzakazpay’, id_zakaz – id заказа, id_typeopl – id типа оплаты, paysum – сумма оплаты, author - автор оплаты (необязательный параметр), paytime - дата и время оплаты (необязательный параметр), smena - смена (необязательный параметр)
Ответ на запрос:
JSON строка, параметры: error – код ошибки, description – описание ошибки, result – пустой массив
Получить список касс (точек подключения):
Входящие параметры:
direction=’getcasharray’
Ответ на запрос:
JSON строка, параметры: error – код ошибки, description – описание ошибки, result – массив, содержащий поля: {POS- код кассы, NAME - имя кассы}
Получить список чеков по смене:
Входящие параметры:
direction=’chequebysmena’, smena - номер смены, smenpos - код кассы, если не задан будет использован код текущей кассы.
Ответ на запрос:
JSON строка, параметры: error – код ошибки, description – описание ошибки, result – массив, содержащий поля: {CHEQUENUM - номер чека, CHEQUEDATE - дата чека, SUM_OTCH - сумма Z-отчёта по чеку }
Получить информацию по чеку:
Входящие параметры:
direction=’getcheque’, cheqnum - номер чека, cheqdate - дата чека, cheqpos - код кассы, если не задан будет использован код текущей кассы.
Ответ на запрос:
JSON строка, параметры: error – код ошибки, description – описание ошибки, result – массив, содержащий массивы:
CHEQUE - итоговые данные по чеку, поля:
SUM_SALE - сумма со скидками,
SUM_LESSDISC - сумма без скидок,
SUM_PAY_BONUS - оплачено бонусами,
SUM_PAY_CERTIF - оплачено сертификатами,
PAY_INSTALLMENT - оплачено в рассрочку,
SMENA - номер смены,
PROD_CODE - внешний код кассира,
CARD_CODE - номер карты
GOODS - товары из чека, поля:
OUTCODE - внешний код товара,
COUNT - количество товара,
SUM_LESSDISC - сумма без скидок,
SUM_SALE - сумма со скидками товара,
SUM_DISCOUNT - сумма начисленная продавцу,
PROD_CODE - внешний код продавца,
CLAS_CODE - внешний код классификатора,
DESCRIPTION - описание операции
PAYCHEQUE - оплаты по чеку, поля:
OPL_CODE - код типа оплаты,
PAY_NAME - наименование типа оплаты,
PAY_SUM - сумма оплаты
OPER - бонусы, поля:
BALANCE - сумма бонусов,
DESCRIPTION - описание
SALECRED - продажи в кредит, поля:
BALANCE - сумма бонусов,
DESCRIPTION - описание
CERTIFICATE - сертификаты, поля:
NUMBER - номер сертификата
NEW_STATUS - код нового статуса
REMCHEQ - удаление товаров из чеков, поля:
OUTCODE - внешний код товара,
COUNT - количество товара,
PRICE - цена товара
TYPE - код типа удаления
PROD_CODE - внешний код кассира
MAKETIME - время производства, поля:
OUTCODE - внешний код товара,
LINE_NUM - номер строки чека,
TIME_BEG - время начала,
TIME_END - время окончания