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

Версия 14:53, 6 мая 2015

Содержание

1 Основной функционал API
2 Уведомления (передача данных из PODS в систему партнёра )
3 Внешняя авторизация
4 Оформление заказа на сайте партнера
5 Вход в конструктор
6 Витрина тематических макетов

Основной функционал API

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

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

https://yourdomain.printondemandsolution.ru/api/new - создание заказа
https://yourdomain.printondemandsolution.ru/api/edit - изменение заказа
https://yourdomain.printondemandsolution.ru/api/set_status - изменение статуса заказа (сохранено для совместимости с Avantnet)

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

albumix_ID (optional) - внутренний идентификатор партнёра в системе Avantnet
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 отправки заказа в печать

https://yourdomain.printondemandsolution.ru/api/send_to_print

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

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

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

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

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

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

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

https://yourdomain.printondemandsolution.ru/api/user_projects/{user_id}?token={token}
{user_id} - ID пользователя в БД WL
{token} - контрольная сумма, считается как md5 от конкатенации {user_id} и секретного ключа

Результат вовзвращается в виде 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 пользователя в БД WL
{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-запрос по адресу:

https://yourdomain.printondemandsolution.ru/api/edit_project_name - переименование проекта
https://yourdomain.printondemandsolution.ru/api/delete_project - удаление проекта

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

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

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

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

Ответ:

OK - при успехе

либо

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

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

https://yourdomain.printondemandsolution.ru/api/get_order_upload_status

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

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"

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

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

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

albumix_order_id = номер заказа в системе PODS
error = "1"
error_message = сообщение об ошибке
sign - контрольная сумма. считается как md5 от конкатенации всех параметров и секретного ключа

Уведомление о создании/редактировании проекта

Вызывается:

при создании проекта авторизованным пользоватлем
при авторизации в конструкторе если проект был создан гостём
при сохранении проекта (в том числе при автосохранении), если изменились параметры проекта, передаваемые в API (кол-во развортов, обложка, заголовок)

Параметры, передаваемые в API:

uid - ID пользователя (партнёрский при сквозной авторизации?)
pid - номер проекта PODs
title - заголовок проекта
formatid - ID формата
coverid - ID обложки
sheets - число разворотов
pic_token - token для формирования URL картинки
sign - контрольная сумма

Контрольная сумма считается как md5 от конкатенации всех параметров и секретного ключа ("Секретный ключ API (исходящие запросы)")

$s = '';
$keys = array('uid', 'pid', 'title', 'formatid', 'coverid', 'sheets');
foreach($keys as $key) {
	$s .= $_POST[$key];
}
$s .= $sekret;

if(md5($s) == $_POST['sign']) {
	echo 'id='.rand();
} else {
	echo 'CHECKSIGNFAILED';
}

В ответ возвращается

ID проекта у партнёра

id=3456

Сообщение об ошибке

CHECKSIGNFAILED

Кроме того в настройках WL можно укзазать URL, на который следует перебрасывать пользователя после нажатия кнопки "сохранить и выйти". Необходимо учесть, что конструктор может находится в IFRAME, при этом перенаправление должно происходить на уровне всей странице.

Внешняя авторизация

Поддерживается два режима авторизации:

сквозная авторизация. сессия пользователя хранится на сайте партнёра. если пользователь авторизован на сайте партнёра при переходе на сайт WL он автоматически авторизуется
IFrame авторизация. Сессия хранится на сайте WL, авторизация с сайта партнёра не подхватывается, но сам процесс авторизации происходит в IFrame партнёра

Возможно совместное исполтьзование сквозной и IFrame авторизации. В приложенном архиве auth.rar пример реализации API партнёра на PHP

После подключения внешней авторизации, войти в панель управления можно по ссылке yourdomain.printondemandsolution.ru/user/logincustom - после авторизации реакции интерфейса не последует. после этого можно заходить в панель управления yourdomain.printondemandsolution.ru/admin

Сквозная авторизация

Для проверки авторизации на площадке партнёра осуществляется JSONP-запрос на площадку партнёра по ссылке, указанной в "URL API сквозной авторизации" в системе администрирования. В ответ должен вернуться корректный Javascript-код, содержащий

вызов функции api_externalAuth параметрами ID пользователя и имя пользователя, если пользователь авторизован

window.api_externalAuth({id:157,name:'Иванов Иван',email:'email@mail.ru','hash':'hashcode'})

дополнительно может быть указан параметр pods_id - ID пользователя в системе PODS hash вычисляется как md5 от конкатенации id, name, pods_id (если есть) и секретного ключа сквозной авторизации, который задаётся в системе администрирования

вызов функции api_externalNoauth параметрами без параметров, если пользователь не авторизован (для отслеживания logout на сайте партнёра)

window.api_externalNoauth()

Пример скрипта API сквозной авторизации в auth.rar, файл pass-through.php

При использовании сквозной авторизации для выхода пользователя из системы нужно убить сесссию пользователя на сайте партнёра. Для этого в системе администрирования указывается URL для кнопки "Выход" на сайте WL. При нажатии "Выход" пользователь переходит на указанный URL, скрипт на сайте партнёра убивает сессию пользователя. Пример скрипта logout.php

IFrame-авторизация

Партнёр указывает ссылку на форму авторизации, которая отображается в IFRAME внутри лайтбокса авторизации. К ссылке добавляется GET-параметр "back", который содержит URL, на который необходимо сделать редирект после завершения авторизации со следующими параметрами (через GET):

id
name
email
pods_id (необязательно)
hash - вычисляется также как при сквозной авторизации

$redirectUrl = sprintf("%s?id=%d&name=%s&email=%s&hash=%s", $_GET['back'], $_SESSION['user_id'], urlencode($_SESSION['user_name']),  urlencode($_SESSION['user_email']),
        md5($_SESSION['user_id'].$_SESSION['user_name'].$_SESSION['pods_id'].$sekret));
header('Location: '. $redirectUrl);

Примеры кода

IFrame.php

<?php
header('Content-type: text/html; charset=urf-8');
header("Cache-Control: no-cache, must-revalidate");
header("Expires: Sat, 26 Jul 1997 05:00:00 GMT");
session_start();

$sekret = 'fLgjlGJlbkl';

if(isset($_POST['id'])) {
	$_SESSION['user_id'] = $_POST['id'];
	$_SESSION['user_name'] = $_POST['name'];
	
	$redirectUrl = sprintf("%s?id=%d&name=%s&hash=%s", $_GET['back'], $_SESSION['user_id'], urlencode($_SESSION['user_name']),
		md5($_SESSION['user_id'].$_SESSION['user_name'].$sekret));
	header('Location: '. $redirectUrl);
} else {
?>
	<form method="post">
		User ID: <input name="id" value="123"/><br>
		User Name: <input name="name" value="Иван Иванов"/><br>
		<input type="submit" value="Войти"/>
	</form>
<?php
}

Logout.php

<?php
session_start();

unset($_SESSION['user_id']);
unset($_SESSION['user_name']);
	
header('Location: '.$_SERVER['HTTP_REFERER']);

Pass-through.php


<?php
header('Content-type: application/javascript; charset=urf-8');
session_start();

$sekret = 'fLgjlGJlbkl';

if(isset($_SESSION['user_id'])) {
   printf("window.api_externalAuth(%s)", json_encode([
      'id' => $_SESSION['user_id'],
      'name' => $_SESSION['user_name'],
	  'hash' => md5($_SESSION['user_id'].$_SESSION['user_name'].$sekret),
   ]));
} else {
   echo "window.api_externalNoauth()";
}

Pass-through-form.php

<?php
header('Content-type: text/html; charset=urf-8');
header("Cache-Control: no-cache, must-revalidate");
header("Expires: Sat, 26 Jul 1997 05:00:00 GMT");
session_start();

if(isset($_POST['id'])) {
	$_SESSION['user_id'] = $_POST['id'];
	$_SESSION['user_name'] = $_POST['name'];
	header('Location: '.$_SERVER['REQUEST_URI']);
	exit;
}

if(isset($_GET['logout'])) {
	unset($_SESSION['user_id']);
	$url = $_SERVER['REQUEST_URI'];
	$pos = strpos($url, '?');
	header('Location: '. substr($url, 0, $pos));
	exit;
}

if(isset($_SESSION['user_id'])) {
	printf("User id: %d<br>", $_SESSION['user_id']);
	printf("User name: %s<br>", $_SESSION['user_name']);
	echo "<a href='?logout=1'>Выйти</a>";
} else {
?>
	<form method="post">
		User ID: <input name="id" value="123"/><br>
		User Name: <input name="name" value="Иван Иванов"/><br>
		<input type="submit" value="Войти"/>
	</form>
<?php
}

Оформление заказа на сайте партнера

В системе администрирования в разделе Настройки - Интеграция можно указать URL для оформления заказов. При оформлении заказа пользователь переходит на указанный URL с дополнительными параметрами:

uid - ID пользователя (партнёрский при сквозной авторизации)
pid - номер проекта PODs
ppid - ID проекта у партнёра, если есть
title - заголовок проекта
formatid - ID формата
coverid - ID обложки
sheets - число разворотов
pic_token - token для формирования URL картинки
sign - контрольная сумма, считается как md5 от конкатенации всех параметров и секретного ключа (Секретный ключ API (исходящие запросы))

sign = md5(uid + pid + ppid + title + formatid + coverid + sheets + pic_teken + sekret)

Вход в конструктор

Для входа в конструктор фотокниг используется ссылка

https://yourdomain.printondemandsolution.ru/books/create/[ID_темы]/[ID_формата]/[ID_обложки][?sheetCount=100]

[ID_темы] - 0, если проект создается без тематического макета
[ID_обложки] - не обязательный параметр
sheetCount - количество разворотов в создаваемой книге, должен находиться в диапазоне минимального/максимального количества разворотов, разрешенных для данного формата. Эти параметры задаются в разделе Настройки - Продукты

Для входа в конструктор сувенирной продукции используется ссылка

http://yourdomain.printondemandsolution.ru/souvenir/create/[разновидность_продукта]/[ID_продукта]/[ID_темы]

[ID_продукта] и [ID_темы] не обзательно

Витрина тематических макетов

ссылка для перехода на витрину тематических макетов книг

http://yourdomain.printondemandsolution.ru/books/create

Если при вызове витрины передаются GET-параметры, то:

- ссылки с темы ведут не на страницу выбора темы, а сразу в конструктор;
- отображаются только те темы, в которых есть макеты для заданного формата.

дополнительные необязательные GET-параметры:

bookFormatId - ID формата
coverId - ID обложки
sheetcount - кол-во разворотов

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

Версия 14:53, 6 мая 2015

Содержание

Основной функционал API

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

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

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

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

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

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

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

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

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

Уведомление о создании/редактировании проекта

Внешняя авторизация

Сквозная авторизация

IFrame-авторизация

Примеры кода

IFrame.php

Logout.php

Pass-through.php

Pass-through-form.php

Оформление заказа на сайте партнера

Вход в конструктор

Витрина тематических макетов

Навигация

Персональные инструменты

Пространства имён

Варианты

Просмотры

Ещё

Поиск

Навигация

Инструменты