Интеграция магазина с PODS

Справочник всех методов, параметров и уведомлений — в разделе API.

Вход покупателя в PODS

Покупатель магазина может работать в конструкторах PODS под своей учётной записью магазина, не регистрируясь в PODS отдельно. Магазин сообщает PODS, кто вошёл, подписанным набором данных; PODS находит покупателя по его ID в магазине или создаёт нового.

Поддерживаются два режима, их можно использовать вместе:

• сквозная авторизация — сессия покупателя хранится на сайте магазина; если покупатель вошёл на сайте магазина, при переходе на сайт PODS он авторизуется автоматически;
• авторизация во фрейме — сессия хранится на сайте PODS, но форма входа — форма магазина: PODS показывает её во фрейме в своём окне входа.

Адреса скриптов магазина, ключ авторизации и адрес кнопки «Выход» задаются в настройках интеграции PODS.

После подключения внешней авторизации войти в панель управления PODS можно по адресу https://<домен PODS>/user/logincustom: после входа страница ничего не покажет, затем откройте https://<домен PODS>/admin.

Подпись данных покупателя

Данные покупателя подписываются параметром hash:

hash = md5( id + name + pods_id + ключ авторизации )

• id — целочисленный ID покупателя в магазине;
• name — имя покупателя ровно в том виде, в каком оно передаётся в PODS;
• pods_id — ID покупателя в PODS, если магазин его знает; если pods_id не передаётся или равен 0, в строку подписи он не входит (не подставляйте 0);
• ключ авторизации — отдельный секретный ключ из настроек интеграции PODS, не совпадающий с секретным ключом API;
• строка подписи всегда кодируется в UTF-8, даже если для API задана другая кодировка;
• email и phone в подпись не входят.

function pods_auth_hash($id, $name, $podsId, $authKey)
{
    // $name должен быть в UTF-8; если сайт работает в windows-1251:
    // $name = mb_convert_encoding($name, 'UTF-8', 'Windows-1251');
    return md5($id . $name . ($podsId > 0 ? $podsId : '') . $authKey);
}

Пример: id=4321, name=Иван Петров, pods_id не передан, ключ авторизации demo-auth-key — подписывается строка 4321Иван Петровdemo-auth-key.

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

На страницах PODS выполняется JSONP-запрос к адресу «URL API сквозной авторизации» из настроек интеграции. Скрипт магазина должен вернуть JavaScript-код:

• если покупатель вошёл — вызов window.api_externalAuth({...}) с полями id, name, email, hash и, при наличии, pods_id:

  window.api_externalAuth({"id":4321,"name":"Иван Петров","email":"client@example.com","hash":"<hash>"})

• если покупатель не вошёл — вызов без параметров (так PODS узнаёт о выходе покупателя на сайте магазина):

  window.api_externalNoauth()

Cookie. Запрос к скрипту магазина выполняется со страницы PODS, то есть в стороннем контексте. Чтобы браузеры на основе Chromium (Chrome, Opera, Яндекс Браузер, Edge) передавали cookie сессии магазина, устанавливайте её с атрибутами SameSite=None; Secure и отдавайте скрипт по HTTPS.

Выход. При сквозной авторизации сессия живёт на сайте магазина, поэтому для выхода её нужно завершить на стороне магазина. В настройках интеграции PODS укажите адрес для кнопки «Выход»: покупатель переходит на этот адрес, скрипт магазина завершает сессию и возвращает покупателя обратно.

Пример скрипта сквозной авторизации (pass-through.php):

<?php
header('Content-Type: application/javascript; charset=utf-8');
header('Cache-Control: no-cache, must-revalidate');
session_start();

// cookie сессии должна передаваться в стороннем контексте
$sessId = session_id();
if ($sessId !== '') {
    header("Set-Cookie: PHPSESSID=$sessId; path=/; HttpOnly; SameSite=None; Secure");
}

$authKey = 'demo-auth-key'; // ключ авторизации из настроек интеграции PODS (пример)

if (isset($_SESSION['user_id'])) {
    $id     = (int)$_SESSION['user_id'];
    $name   = $_SESSION['user_name'];
    $podsId = isset($_SESSION['pods_id']) ? (int)$_SESSION['pods_id'] : 0;

    $data = [
        'id'    => $id,
        'name'  => $name,
        'email' => isset($_SESSION['user_email']) ? $_SESSION['user_email'] : '',
        'hash'  => md5($id . $name . ($podsId > 0 ? $podsId : '') . $authKey),
    ];
    if ($podsId > 0) {
        $data['pods_id'] = $podsId;
    }
    printf('window.api_externalAuth(%s)', json_encode($data, JSON_UNESCAPED_UNICODE));
} else {
    echo 'window.api_externalNoauth()';
}

Пример скрипта выхода (logout.php):

<?php
session_start();
unset($_SESSION['user_id'], $_SESSION['user_name'], $_SESSION['user_email'], $_SESSION['user_phone'], $_SESSION['pods_id']);

$back = isset($_SERVER['HTTP_REFERER']) ? $_SERVER['HTTP_REFERER'] : '/';
header('Location: ' . $back);

Авторизация во фрейме

В настройках интеграции указывается адрес формы входа магазина. PODS открывает её во фрейме своего окна входа и добавляет к адресу GET-параметр back — адрес PODS, на который нужно перенаправить фрейм после успешного входа. В адресе формы можно использовать подстановку {LANG_CODE}: PODS заменит её кодом языка интерфейса, например ru-RU.

После входа скрипт магазина перенаправляет фрейм на адрес из back, добавив GET-параметры:

Параметр	Обязательный	Описание
id	да	ID покупателя в магазине (целое число)
name	нет	Имя покупателя; входит в подпись
email	нет	E-mail покупателя
phone	нет	Телефон покупателя. Передавайте всегда (см. ниже)
pods_id	нет	ID покупателя в PODS, если известен
hash	да	Подпись (см. выше)

Передавайте phone всегда — значение перезаписывает телефон покупателя в PODS при каждом входе.

Пример формы входа (iframe.php):

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

$authKey = 'demo-auth-key'; // ключ авторизации из настроек интеграции PODS (пример)

if (isset($_POST['id'])) {
    // здесь — ваша проверка логина и пароля; ниже данные просто берутся из формы
    $_SESSION['user_id']    = (int)$_POST['id'];
    $_SESSION['user_name']  = $_POST['name'];
    $_SESSION['user_email'] = $_POST['email'];
    $_SESSION['user_phone'] = $_POST['phone'];

    $id     = $_SESSION['user_id'];
    $name   = $_SESSION['user_name'];
    $podsId = isset($_SESSION['pods_id']) ? (int)$_SESSION['pods_id'] : 0;

    $params = [
        'id'    => $id,
        'name'  => $name,
        'email' => $_SESSION['user_email'],
        'phone' => $_SESSION['user_phone'], // передавайте всегда
        'hash'  => md5($id . $name . ($podsId > 0 ? $podsId : '') . $authKey),
    ];
    if ($podsId > 0) {
        $params['pods_id'] = $podsId;
    }

    $back = $_GET['back'];
    $separator = (strpos($back, '?') === false) ? '?' : '&';
    header('Location: ' . $back . $separator . http_build_query($params));
    exit;
}
?>
<form method="post">
    ID покупателя: <input name="id" value="4321"><br>
    Имя: <input name="name" value="Иван Петров"><br>
    E-mail: <input name="email" value="client@example.com"><br>
    Телефон: <input name="phone" value="+79000000000"><br>
    <input type="submit" value="Войти">
</form>

При успешном входе PODS показывает во фрейме страницу подтверждения и авторизует покупателя.

Вход по ссылке с возвратом

Если покупатель уже вошёл на сайте магазина, магазин может авторизовать его в PODS прямой ссылкой и вернуть на нужную страницу:

https://<домен PODS>/api/auth?id=4321&name=Иван%20Петров&email=client%40example.com&phone=%2B79000000000&hash=<hash>&back=https%3A%2F%2F<домен PODS>%2Fbooks%2Fcreate

Параметры — те же, что при авторизации во фрейме, плюс back — адрес, на который PODS перенаправит покупателя после входа. Если back не передан, PODS ответит текстом OK (param 'back' is empty).

Ошибки входа

PODS отвечает текстом:

Ответ	Причина
checksum failed	Подпись не совпала
pods_id failed	Передан pods_id, но такой покупатель в PODS не найден
user is blocked	Покупатель заблокирован в PODS

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

Если заказы оформляются в корзине магазина, в настройках интеграции PODS указывается адрес оформления заказа. Когда покупатель нажимает «Заказать» в конструкторе, PODS перенаправляет его на этот адрес с GET-параметрами:

Параметр	Описание
uid	ID покупателя в магазине
pid	Номер проекта в PODS
ppid	ID проекта в магазине, если магазин вернул его в ответ на уведомление о проекте
title	Название проекта
quantity	Количество экземпляров
formatid	ID формата
coverid	ID обложки
partner_cover_description	Описание обложки, переданное в одноимённом параметре при входе в конструктор
sheets	Число разворотов
pic_token	Токен проекта для формирования адреса картинки-превью
theme_id	ID темы
souvenir_class_id	ID вида сувенирной продукции
souvenir_product_id	ID товара сувенирной продукции
paper_id	ID бумаги фотокниги, указанной при входе в конструктор
type	Тип продукта: book, photo, wideformat, souvenir
price	Цена
sign	Подпись

Подпись:

sign = md5( uid + pid + ppid + title + formatid + coverid + sheets + pic_token + секретный ключ API для исходящих запросов )

$secret = 'demo-outgoing-secret'; // пример
$s = '';
foreach (['uid', 'pid', 'ppid', 'title', 'formatid', 'coverid', 'sheets', 'pic_token'] as $key) {
    $s .= isset($_GET[$key]) ? $_GET[$key] : '';
}
if (md5($s . $secret) !== (isset($_GET['sign']) ? $_GET['sign'] : '')) {
    http_response_code(400);
    exit('Неверная подпись');
}

Состав и цена проекта. Чтобы положить проект в корзину с актуальными позициями и ценами, запросите его методом /api/user_projects с параметрами pid и type (подпись — md5(pid + секретный ключ API)). В ответе — части проекта (project_parts) с ценами, доплата за материал и опции обложки (cover_options_total) и признаки их доступности (cover_material_available, cover_options_available). Если материал или опция обложки стали недоступны, в ответе есть ссылка cover_change_url — направьте по ней покупателя, чтобы он выбрал другой вариант до оплаты.

Затем создайте заказ методом /api/new.

Кнопка «Сохранить и выйти». В настройках интеграции можно указать адрес, на который PODS переводит покупателя после нажатия «Сохранить и выйти» в конструкторе. Конструктор может быть открыт во фрейме — переход выполняется в окне верхнего уровня.

GET-параметры для входа в конструкторы

Все адреса — на домене PODS партнёра.

Фотокниги

https://<домен PODS>/books/create/{ID темы}/{ID формата}
https://<домен PODS>/books/create/{ID темы}/{ID формата}/{ID обложки}
https://<домен PODS>/books/create/{ID темы}/{ID формата}/{ID обложки}/{код купона}
https://<домен PODS>/books/create/{ID темы}/{ID формата}/{код купона}

• ID темы — 0, если проект создаётся без тематического макета;
• ID обложки — необязательный сегмент;
• код купона — необязательный последний сегмент; код из одних цифр передавайте параметром couponCode, иначе он будет принят за ID обложки.

Адрес https://<домен PODS>/books/create/{ID темы} открывает выбор формата для заданной темы.

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

Параметр	Описание
SheetCount	Число разворотов создаваемой книги; должно быть в пределах минимума и максимума, заданных для формата в настройках продуктов
PaperId	ID бумаги
couponCode	Код купона, заведённого в PODS. Имеет приоритет над купоном по умолчанию, подставляется в поле купона в заказе и в выборе формата. Работает во всех конструкторах: фотопечать, фотокниги, сувениры, широкоформатная печать
activeTab	Вкладка, открытая по умолчанию: Templates — шаблоны, Photos — снимки, Decors — декоры, Background — фон, Collages — коллажи

Дополнительные параметры для обложки, которую задаёт магазин:

Параметр	Описание
textures	ID текстур через запятую
partner_cover_code	Код обложки в магазине
partner_cover_price	Цена обложки (в конструкторе не меняется)
partner_cover_description	Текстовое описание обложки; возвращается в одноимённом параметре при переходе к оформлению заказа
customCoverUrl	Адрес внешнего изображения текстуры обложки

Параметры выбора вида книги на адресе https://<домен PODS>/books/create:

• booktypeID=0 — список всех видов и форматов; после выбора формата и обложки — список тем для формата, затем конструктор;
• booktypeID=<ID вида> — тот же список с фокусом на заданном виде книг;
• bookFormatID — ID формата, coverID — ID обложки.

Сувениры

https://<домен PODS>/souvenir/create/{ID вида сувенира}
https://<домен PODS>/souvenir/create/{ID вида сувенира}/{ID товара}
https://<домен PODS>/souvenir/create/{ID вида сувенира}/{ID товара}/{ID темы}

ID товара и ID темы необязательны; ID темы передаётся только вместе с ID товара. Например, /souvenir/create/1 открывает конструктор кружек, /souvenir/create/1/23 — конструктор конкретной кружки.

GET-параметр activeTab — вкладка, открытая по умолчанию: Templates — шаблоны, Photos — фото, Decors — декоры.

Широкоформатная печать

https://<домен PODS>/wideformat?size=20x30&materialId=1&uploader=photo&options=3,5&multi=true

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

Параметр	Описание
size	Размер печати <ширина>x<высота> в сантиметрах, например 20x30 (латинская x). По умолчанию подбирается оптимальный размер
materialId	ID материала печати. По умолчанию — первый материал в списке
uploader	Сразу открыть окно загрузки: photo — загрузка фото с диска, picture — выбор картины
options	ID предустановленных опций через запятую
multi	Открыть в режиме модульной картины: true или ID конкретной модульной картины
showMaterialIds	Показывать в интерфейсе только указанные ID материалов (через запятую)
showOptionIds	Показывать в интерфейсе только указанные ID опций (через запятую)
hideIncompatible	true — скрывать опции, несовместимые с выбранным материалом

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

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

https://<домен PODS>/books/create

Если витрина вызывается с GET-параметрами, ссылки с тем ведут сразу в конструктор (минуя выбор формата), а на витрине показываются только темы, в которых есть макеты для заданного формата.

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

Параметр	Описание
bookFormatID	ID формата
coverID	ID обложки
sheetcount	Число разворотов
preview	ID темы: при открытии витрины сразу показывается превью этой темы
booktypeID	0 — список всех видов и форматов; <ID вида> — список с фокусом на заданном виде книг

Витрина на сайте магазина. Чтобы построить витрину тем у себя, используйте метод /Api/GetThemeList (type=book — темы фотокниг, type=souvenir-<ID вида> — темы сувениров): он отдаёт темы в порядке, заданном в панели управления PODS, с адресом превью, совместимыми форматами (для сувениров — размерами) и тегами. Темы, отключённые в панели управления, в ответ не попадают.

Список миниатюр изображений темы (XML):

https://<домен PODS>/Book/PreviewXml/{ID темы}

Число разворотов с миниатюрами и версия набора превью приходят в полях PreviewCount и PreviewVersion ответа /Api/GetThemeList: перезагружайте миниатюры темы только при смене PreviewVersion.

Переход с витрины магазина в конструктор по выбранной теме — по адресу /books/create/{ID темы}/{ID формата}[/{ID обложки}] (см. «GET-параметры для входа в конструкторы»).