API — различия между версиями

Материал из PODS Wiki
Перейти к: навигация, поиск
Строка 156: Строка 156:
 
** 3 - выгружено
 
** 3 - выгружено
 
** 4 - отменено
 
** 4 - отменено
 +
 +
== Уведомления (передача данных из PODS в систему партнёра ) ==
 +
URL для всех уведомлений указывается в разделе [[Настройки]] - [[Интеграция]]
 +
 +
=== Уведомление об успешной выгрузке заказа ===
 +
 +
Не вызывается в случае перезаливки заказа. Параметры передаваемые в API:
 +
 +
*Общее для всех видов заказа*
 +
 +
**albumix_order_id - номер заказа в PODS
 +
**partner_order_id - номер заказа у партнёра
 +
**price (double) = стоимость заказа (не книги, а всего заказа с учетом скидок, т.е. сколько клиент должен заплатить)
 +
**payment_method = способ оплаты (заказ оплачен/оплата при получении)
 +
**user_name = ФИО клиента
 +
**phone = телефон клиента
 +
**email = email клиента
 +
**delivery_point = 0 (на адрес клиента) 1 (на адреса самовывоза партнера-печатника)
 +
**city =
 +
**street =
 +
**building =
 +
**appt =
 +
 +
форматы и термины адреса должны быть совместимыми с EMS-POST
 +
*delivery_provider = 0 (партнер), 1 (EMS), 2 (еще кто-то) ...
 +
*sign = контрольная сумма. считается как md5 от конкатенации некоторых параметров и секретного ключа. набор полей для рассчёта контрольной суммы отличается для фотокниг и фотопечати
 +
 +
 +
*Фотокниги*
 +
**albumix_order_id (string(100)) = номер заказа в системе PODS
 +
**stamp (date time string dd.mm.yyyy hh:nn:ss) = дата приема заказа
 +
**book_type = тип книги
 +
**book_type_id = ID типа книги
 +
**book_format = формат книги
 +
**book_format_id = ID формата книги
 +
**paper_type = тип листа
 +
**paper_type_id = ID типа листа
 +
**sheets = количество разворотов
 +
**qty (integer) = количество экземпляров
 +
**printmatic = 0 выключен, 1 включен.
 +
**pic_token - token для формирования URL картинки
 +
 +
набор полей, участвующих в рассчёте контрольной суммы:
 +
**"albumix_order_id", "stamp", "action_id", "qty", "price", "price_internal", "delivery_point", "delivery_address", "delivery_provider", "payment_method"
 +
 +
*Фотопечать*
 +
 +
**order_detail - строка описания заказа
 +
 +
формат строки
 +
ТИППРОДУКТА\tТИПБУМАГИ\tФОРМАТ\tКОЛВО\tЦЕНАЕДИНИЦЫ\r\n
 +
....
 +
ТИППРОДУКТА\tТИПБУМАГИ\tФОРМАТ\tКОЛВО\tЦЕНАЕДИНИЦЫ
 +
\t - табуляция
 +
\r\n - возврат каретки + новая стока
 +
 +
примеры
 +
100 фото на глянце 10х15
 +
<pre>Фотопечать\tГлянцевая\t10x15\t100\t3.50</pre>
 +
 +
100 фото на глянце 10х15 + 5 исправлений красных глаз
 +
<pre>Фотопечать\tГлянцевая\t10x15\t100\t3.50
 +
Прочее\t\tКрасные глаза\t5\t4</pre>
 +
 +
100 фото на глянце 10х15 + 10 фото на мат 15х20
 +
<pre>Фотопечать\tГлянцевая\t10x15\t100\t3.50
 +
Фотопечать\tМатовая\t15x20\t10\t15</pre>
 +
 +
набор полей, участвующих в рассчёте контрольной суммы:
 +
*"albumix_order_id", "stamp", "user_name", "delivery_point", "delivery_address", "delivery_provider", "payment_method"
 +
 +
*Возвращается от партнера*
 +
 +
В ответ на уведомление о выгрузке заказа партнёр имеет возможность передать присвоенный ID заказа. В этом случае ответ должен быть в виде:
 +
 +
*albumix_ID = идентификатор PODS в системе партнера
 +
*partner_order_ID = внутренний номер заказа в системе партнера
 +
 +
Пример
 +
<pre>
 +
albumix_ID=123
 +
partner_order_ID=12345
 +
</pre>
 +
 +
Если не требуется присваивать партнёрский ID после выгрузки заказа - можно вернуть просто строку "OK"

Версия 19:28, 3 апреля 2015

API создания/изменения заказа

Для изменения заказа необходимо сделать POST-запрос по адресу:

Параметры запроса (POST DATA):

  • albumix_ID (optional) - внутренний идентификатор партнёра в системе Алексея Букреева
  • partner_order_ID (required) - ID заказа в системе партнёра
  • status_order (optional, required если set_status) - статус заказа:
    • 1 - принят (по умолчанию);
    • 2 - напечатан и передан в доставку;
    • 3 - доставлен
    • 4 - выдан
    • 9 - отменён
  • count (optional) - Количество продукции, если не указано, считается = 1
  • project_id (required, если new) - ID проекта в PODS
  • paper_id (optioanl) - ID типа бумаги
  • total_amount (optional, required если new) - Стоимость заказа
  • delivery_point (optional) = 0 (на адрес клиента) 1 (на адреса самовывоза партнера-печатника)
  • delivery_address (optional) адрес доставки
  • send_to_print (optional) - если "1", заказ после создания отправляется в печать
  • stamp (optional) - метка времени в формате Unix timesta
  • token - контрольная сумма

Значение token вычисляется по разному в зависимости от типа запроса:

  • для new и edit как MD5 от конкатенации секретного ключа, задаваемого в настройках WL (параметр "Секретный ключ API (входящие запросы)") и всех параметров запроса:
    md5( albumix_ID + partner_order_ID + status_order + count + project_id + paper_id + total_amount + delivery_point + delivery_address + send_to_print + stamp + sekret)
  • для set_status вычисляется как MD5 от конкатенации секретного ключа, задаваемого в настройках WL (параметр "Секретный ключ API (входящие запросы)"), "albumix_ID", "partner_order_ID", "status_order" и "stamp", соединённых через знак тире ("-")


Пример вычисления на PHP: 

$key = 'SEKRET_KEY';
$fields = array('albumix_ID', 'partner_order_ID', 'status_order', 'stamp');
$values = array($key);
foreach($fields as $field) {
    $values[] = $_POST[$field];
}
$token = md5(implode('-', $values));

Ответ:

  • При успешной обработке запроса возвращается строка
 id={ID}

{ID} - номер заказа в PODS

  • В случае ошибки возвращается 
 error={Error descriptiom}
  • При использовании set_status в случае успеха возвращается строка "OK" (сохранено для совместимости с Avantnet)

Используется кодировка указанная в панели управления, в разделе Настройки - Интеграция

API отправки заказа в печать

Параметры запроса (POST DATA):

  • order_id - ID заказа (наш)
  • ftp-resend - "0" - отправит в печать, "1" - перезалить
  • token - контрольная сумма

Вычисление контрольной суммы: 

MD5  ([order_id][ftp-resend][secret])

Отправка заказа отличается от перезаливки только одим: в случае перезаливки (ftp-resend=1) не будет вызван API уведомления о выгрузке заказа.


API получения списка проектов пользователя

Для получения делается запрос по адресу

Результат вовзвращается в виде JSON, содержащего массив проектов со следующими полями:

  • pid - ID проекта в PODS
  • partner_pid - ID проекта у партнёра, если есть
  • title - название проекта
  • book_type = тип книги
  • book_type_id = ID типа книги
  • book_format = формат книги
  • book_format_id = ID формата книги
  • paper_type = тип листа
  • paper_type_id = ID типа листа
  • cover_id = ID обложки
  • sheets = количество разворотов
  • pic_token - token для формирования URL картинки
  • created - дата и время создания, в формате ДД.ММ.ГГГГ ЧЧ:ММ:СС
  • edited - дата и время создания, в формате ДД.ММ.ГГГГ ЧЧ:ММ:СС

API получения списка заказов пользователя

Для получения делается запрос по адресу https://yourdomain.printondemandsolution.ru/api/user_orders/{user id}?token={token}

  • {user id} - ID пользователя в PODS
  • {token} - контрольная сумма, считается как md5 от конкатенации {user id} и секретного ключа

Результат вовзвращается в виде JSON, содержащего массив проектов со всеми полями из проектов плюс:

  • oid - номер заказа в PODS
  • partner_oid - номер заказа у партнёра, если есть
  • qty (integer) = количество экземпляров
  • printmatic = 0 выключен, 1 включен.
  • delivery_point = 0 (на адрес клиента) 1 (на адреса самовывоза партнера-печатника)
  • delivery_address
  • city =
  • street =
  • building =
  • appt =
  • order_time - дата и время заказа, в формате ДД.ММ.ГГГГ ЧЧ:ММ:СС
  • status - статус заказа (как в API создания/изменения заказа)

API удаления/переименования проектов

Для удаления/переименования проекта необходимо сделать POST-запрос по адресу:

Параметры запроса:

  • project_id - ID проекта
  • project_new_name - новое название проекта (для удаления не нужно)
  • token - контрольная сумма

значение token вычисляется как MD5 от конкатенации секретного ключа и всех параметров запроса

  • md5( project_id + project_new_name + sekret) - для переименования
  • md5( project_id + sekret) - для удаления

Ответ:

  • OK - при успехе

либо

  • error - сообщение об ошибке (если есть)


API получения статуса выгрузки заказа

Параметры запроса:

  • order_id - ID заказа
  • token - контрольная сумма, считается как md5 от конкатенации order_id и секретного ключа

Результат вовзвращается в виде JSON, содержащего:

  • error - сообщение об ошибке при запросе (если оно есть)

либо

  • status - статус заказа:
    • 0 - не было выгрузки
    • 1 - идёт выгрузка
    • 2 - ошибка
    • 3 - выгружено
    • 4 - отменено

Уведомления (передача данных из PODS в систему партнёра )

URL для всех уведомлений указывается в разделе Настройки - Интеграция

Уведомление об успешной выгрузке заказа

Не вызывается в случае перезаливки заказа. Параметры передаваемые в API:

  • Общее для всех видов заказа*
    • albumix_order_id - номер заказа в PODS
    • partner_order_id - номер заказа у партнёра
    • price (double) = стоимость заказа (не книги, а всего заказа с учетом скидок, т.е. сколько клиент должен заплатить)
    • payment_method = способ оплаты (заказ оплачен/оплата при получении)
    • user_name = ФИО клиента
    • phone = телефон клиента
    • email = email клиента
    • delivery_point = 0 (на адрес клиента) 1 (на адреса самовывоза партнера-печатника)
    • city =
    • street =
    • building =
    • appt =

форматы и термины адреса должны быть совместимыми с EMS-POST

  • delivery_provider = 0 (партнер), 1 (EMS), 2 (еще кто-то) ...
  • sign = контрольная сумма. считается как md5 от конкатенации некоторых параметров и секретного ключа. набор полей для рассчёта контрольной суммы отличается для фотокниг и фотопечати


  • Фотокниги*
    • albumix_order_id (string(100)) = номер заказа в системе PODS
    • stamp (date time string dd.mm.yyyy hh:nn:ss) = дата приема заказа
    • book_type = тип книги
    • book_type_id = ID типа книги
    • book_format = формат книги
    • book_format_id = ID формата книги
    • paper_type = тип листа
    • paper_type_id = ID типа листа
    • sheets = количество разворотов
    • qty (integer) = количество экземпляров
    • printmatic = 0 выключен, 1 включен.
    • pic_token - token для формирования URL картинки

набор полей, участвующих в рассчёте контрольной суммы:

    • "albumix_order_id", "stamp", "action_id", "qty", "price", "price_internal", "delivery_point", "delivery_address", "delivery_provider", "payment_method"
  • Фотопечать*
    • order_detail - строка описания заказа

формат строки ТИППРОДУКТА\tТИПБУМАГИ\tФОРМАТ\tКОЛВО\tЦЕНАЕДИНИЦЫ\r\n .... ТИППРОДУКТА\tТИПБУМАГИ\tФОРМАТ\tКОЛВО\tЦЕНАЕДИНИЦЫ \t - табуляция \r\n - возврат каретки + новая стока

примеры 100 фото на глянце 10х15 

Фотопечать\tГлянцевая\t10x15\t100\t3.50

100 фото на глянце 10х15 + 5 исправлений красных глаз 

Фотопечать\tГлянцевая\t10x15\t100\t3.50
Прочее\t\tКрасные глаза\t5\t4

100 фото на глянце 10х15 + 10 фото на мат 15х20 

Фотопечать\tГлянцевая\t10x15\t100\t3.50
Фотопечать\tМатовая\t15x20\t10\t15

набор полей, участвующих в рассчёте контрольной суммы:

  • "albumix_order_id", "stamp", "user_name", "delivery_point", "delivery_address", "delivery_provider", "payment_method"
  • Возвращается от партнера*

В ответ на уведомление о выгрузке заказа партнёр имеет возможность передать присвоенный ID заказа. В этом случае ответ должен быть в виде:

  • albumix_ID = идентификатор PODS в системе партнера
  • partner_order_ID = внутренний номер заказа в системе партнера

Пример 

albumix_ID=123
partner_order_ID=12345

Если не требуется присваивать партнёрский ID после выгрузки заказа - можно вернуть просто строку "OK"

Источник — «https://wiki.printondemandsolution.ru/index.php?title=API&oldid=384»