Веб-сервис

Веб-сервис — встроенный API магазина. Через него внешние программы — складская система, мобильное приложение, скрипт выгрузки — читают и изменяют товары, заказы и покупателей запросами HTTP, без доступа к базе данных. Писать для этого код в магазине не нужно: API уже есть, его достаточно включить.

Включение

Откройте в панели «Расширенные параметры → Веб-сервис».
Включите переключатель «Включить веб-службу PrestaShop» и сохраните.
Нажмите «Добавить новый ключ веб-службы».
Нажмите «Сгенерировать» — получится ключ из 32 символов.
В таблице прав отметьте, что ключу разрешено: например, GET для products и orders.
Сохраните.

Ключ — это пароль от данных магазина. Выдавайте каждой программе свой ключ и только те права, которые ей нужны.

Первый запрос

API доступен по адресу /api. Ключ передают как имя пользователя в обычной авторизации HTTP, пароль оставляют пустым:

curl -u YOUR_KEY: "http://shop.test/api/products?output_format=JSON"

Ответ — список номеров товаров:

{
    "products": [
        { "id": 1 },
        { "id": 2 }
    ]
}

Без параметра output_format=JSON ответ придёт в XML — это формат по умолчанию.

Ресурсы

Каждый вид данных — ресурс со своим адресом. Список ресурсов, доступных ключу, показывает запрос к самому /api.

Ресурс	Что это
`products`	Товары
`categories`	Категории
`customers`	Покупатели
`addresses`	Адреса
`carts`	Корзины
`orders`	Заказы
`order_states`	Состояния заказов
`stock_availables`	Остатки

Одна запись

curl -u YOUR_KEY: "http://shop.test/api/products/1?output_format=JSON"

Запрос вернёт все поля товара с номером 1: цену, артикул, названия на всех языках, номера связанных категорий и картинок.

Отбор и поля

Список настраивают параметрами запроса.

Параметр	Что делает
`display=[id,name,price]`	Какие поля вернуть; `display=full` — все
`filter[active]=[1]`	Только записи с этим значением поля
`filter[name]=%[shirt]%`	Поиск по части строки
`sort=[id_DESC]`	Сортировка
`limit=10` или `limit=20,10`	Количество; смещение и количество

curl -g -u YOUR_KEY: "http://shop.test/api/products?output_format=JSON&display=[id,name,price]&filter[active]=[1]&limit=5"

Запрос вернёт пять включённых товаров с тремя полями у каждого. Ключ -g нужен, чтобы curl не толковал квадратные скобки по-своему.

Методы HTTP

Метод	Действие	Право в ключе
`GET`	Чтение	Просмотр
`POST`	Создание	Добавление
`PUT`	Изменение	Изменение
`DELETE`	Удаление	Удаление

Создание и изменение

Данные для записи отправляют в XML. Пустую заготовку со всеми полями ресурса даёт параметр schema=blank:

curl -u YOUR_KEY: "http://shop.test/api/customers?schema=blank"

Заготовку заполняют и отправляют методом POST на адрес ресурса:

curl -u YOUR_KEY: -X POST -H "Content-Type: text/xml" \
    --data-binary @customer.xml "http://shop.test/api/customers"

В ответ придёт созданная запись с её номером. Для изменения отправляют полную запись методом PUT на адрес с номером, например /api/customers/5.

Смена состояния заказа

Частая задача складской системы — отметить заказ отправленным. Для этого не меняют сам заказ, а создают запись в ресурсе order_histories с номером заказа и номером нового состояния. Магазин при этом ведёт себя так же, как при смене состояния в панели: вызывает хуки и отправляет письмо покупателю.

Свои данные

Таблицы модуля в API сами не появляются. Модуль может добавить свой ресурс хуком addWebserviceResources и описанием webserviceParameters в классе модели. Если нужен один-два простых адреса, проще написать контроллер витрины, который отвечает JSON, как в уроке о формах и AJAX.

Частая ошибка

Запрос возвращает 401, хотя ключ верный. На многих серверах Apache с PHP в режиме CGI или FPM заголовок авторизации не доходит до PHP. Проверьте, что в файле .htaccess магазина есть правило, передающее HTTP_AUTHORIZATION, — оно создаётся при включении дружественных адресов, — или на время проверки передайте ключ параметром ws_key в адресе.

Спасибо, что читаете!