API представляет набор правил и функций, позволяющих двум разным приложениям взаимодействовать друг с другом (например между 1С и сайтом). API выступает посредником между приложениями, отправляя запросы и ответы.
Для чего это нужно? Автоматизация. Не нужно вручную вносить информацию о товарах (в 1С, на сайт или CRM). Вы можете попросить программиста, который обслуживает Вашу компанию, и он используя наше API автоматизирует этот процесс. Это же касается своевременного обновления цен и остатков.
Для отправки и получения тех самых запросов мы предоставляем следующие типы протоколов и архитектур:
Нашим клиентам доступны 3 файла XML, в которых хранятся различные данные. Каждый из файлов обновляется с разной переодичностью.
Файл elements.xml
— содержит основную информацию о товарах (название, код товара, описание, фотографии и т.п.). Ещё он содержит информацию о структуре каталога, название категорий и какие товары в них входят. Обновляется он один раз в сутки. Давайте рассмотрим структуру файла elements.xml
Элемент | Описание |
---|---|
xml |
Стандартный XML-заголовок. Должен начинаться с первой строки, с нулевого символа. |
xml_catalog |
Мы используем в качестве корневого xml элементa: |
categories |
Cодержит список категорий. Каждая категория описывается отдельным элементом |
category |
Название категории. Атрибут |
offers |
Список товаров. Каждый товар описывается в отдельном элементе |
offer |
Содержит узел информации о конкретном товаре. Атрибут |
name |
Наименование номенклатуры. Не содержит спецсимволов. |
categoryId |
Идентификатор категории товара (целое число). |
barcode |
Штрихкод товара от производителя в формате: EAN-13. |
unit |
Единица измерения, формат и стандарт данных не регламентирован, обрабатывайте как строковые данные. |
images |
Родительский узел содержащий информацию о фотографиям к товару. Этот узел содержит дополнительную избыточную информацию, его можно игнорировать. Структура введена для удобства. |
count |
Содержит информацию о количестве фотографий у товара на текущий момент. |
hash |
Это расчитанное значение crc32, от последоательной (от 1 до n) конкатенации строковых значений атрибутов |
pictures |
Родительский узел содержащий информацию о ссылках на фотографии к товару. |
picture |
Ссылка на фотографию к товару. Атрибут |
description |
Текстовое описание товара. Формат не регламентирован. Не содержит спецсимволов. |
params |
Родительский узел содержащий информацию о свойствах товара. Каждое свойство описывается в отдельном элементе |
param |
Текущее значение свойства. Атрибут |
Файл price.xml
— содержит информацию о стоимости товара, по которой вы можете его купить, а также о рекомендуемой розничной цене. Обновляется каждые 6 часов. Давайте рассмотрим структуру файла.
Элемент | Описание |
---|---|
xml |
Стандартный XML-заголовок. Должен начинаться с первой строки, с нулевого символа. |
xml_catalog |
Мы используем в качестве корневого xml элементa: |
elements |
Cодержит список товаров. Каждый товар описывается отдельным элементом |
element |
Текущая стоимость товара в Российских рублях. Атрибут |
Файл quantity.xml
— содержит информацию о текущих остатках товара на нашем складе. Обновляется каждые 30 минут. Рассмотрим структуру файла:
Элемент | Описание |
---|---|
xml |
Стандартный XML-заголовок. Должен начинаться с первой строки, с нулевого символа. |
xml_catalog |
Мы используем в качестве корневого xml элементa: |
elements |
Cодержит список товаров. Каждый товар описывается отдельным элементом |
element |
Текущие остатки товара на нашем складе. Атрибут |
Пример простейшего класса и работа с ним.
Для предоставления доступа к REST JSON, вы должны отправить заявку к нам на почту opt@alma.su
. В заявке укажите: инн и ip адрес (с которого будете делать запросы). В целях безопасности у нас доступ только по white list ip.
Что дальше? Мы присвоим вашей организации базовый токен доступа и внесём ваш ip адрес в список исключений. После этого оповестим Вас ответным письмом или звонком. Используя базовый токен доступа, вы сможете авторизоваться в нашей системе и получить временный токен доступа, через который и происходят все дальнейшие запросы. Временный токен доступа нужен для того, чтобы снизить риск утечки базового токена для вашей организации.
Простейший пример запроса к нашему API на языке PHP вы можете посмотреть ниже:
Коды ошибок мы отдаём через функцию php http_response_code()
. Можете более подробно изучить её в документации.
INFO HTTP CODE | Описание |
---|---|
500 |
Прервано. Высокая нагрузка на сервер, попробуйте позже. |
503 |
Сервис временно недоступен. API отключено в ручном режиме. |
400 |
Недопустимые входные данные в запросе. Неверные значения или не все ожидаемые параметры были переданы в запросе. |
404 |
Неверно указан инн или базовый токен. Товар не найден. Не установлен вид цены. Товары не найдены. |
403 |
Недостаточно разрешений на выполнение этой операции. Нет прав на получение цен. |
Для получения кода ответа сервера используйте curl_getinfo($curl,CURLINFO_HTTP_CODE);
Проверка доступности API (пример на PHP).
Возвращаемое значение | Описание |
---|---|
status |
|
message |
Информационное поясняющее сообщение. Содержит описание ошибки или наоборот удачного выполнения запроса. |
Получение временного рабочего токена для API, через авторизацию базовый токен + инн (пример на PHP). Базовый токен мы выдаём вам при подключении к нашему API.
Возвращаемое значение | Описание |
---|---|
status |
|
token |
Временный зарегистрированный токен, который вы можете использовать в других запросах. |
life |
время жизни этого токена в секундах с момента выдачи. |
Проверка актуальности временного токена. Если токен не актуален, то требуется перевыпуск нового через запрос auth
.
Возвращаемое значение | Описание |
---|---|
status |
|
Позволяет получить подробную информацию о наименовании товара по его коду.
Возвращаемое значение | Описание |
---|---|
status |
|
element |
Массив который содержит подробную информацию о товаре. |
element.id |
Код товара. |
element.name |
Наименование товара (текстовая строка). |
element.category |
Идентификатор родительской категории, к которой привязан товар. |
element.quantity |
Текущий доступный для продажи остаток. |
element.unit |
Единица измерения остатка. |
element.images |
Количество фотографий у данного товара. Путь до самих изображений формируется так: |
element.desc |
Подробное описание товара. Может содержать в себе экранированный html тег |
element.price |
Стоимость единицы остатка товара. |
Позволяет получить подробную информацию сразу о всех товарах в нашем ассортименте.
Возвращаемое значение | Описание |
---|---|
status |
|
elements |
Массив с информацией о всех товарах в ассортименте. |
elements.[].id |
Код товара. |
elements.[].name |
Наименование товара (текстовая строка). |
elements.[].category |
Идентификатор родительской категории, к которой привязан товар. |
elements.[].unit |
Единица измерения остатка. |
elements.[].images |
Количество фотографий у данного товара. Путь до самих изображений формируется так: |
elements.[].desc |
Подробное описание товара. Может содержать в себе экранированный html тег |
Позволяет получить подробную информацию сразу о ценах для всех товаров в нашем ассортименте.
Возвращаемое значение | Описание |
---|---|
status |
|
elements |
Массив с информацией о всех ценах для всех товаров в ассортименте. |
elements.[].id |
Код товара. |
elements.[].price |
Стоимость товара в рублях. |
Позволяет получить подробную информацию сразу об остатках для всех товаров в нашем ассортименте.
Возвращаемое значение | Описание |
---|---|
status |
|
elements |
Массив с информацией о всех ценах для всех товаров в ассортименте. |
elements.[].id |
Код товара. |
elements.[].quantity |
Текущий остаток доступный для продажи. |
Позволяет получить подробную информацию о всех категориях.
Возвращаемое значение | Описание |
---|---|
status |
|
category |
Массив с информацией о всех категориях товара. |
category.[].id |
Идентификатор категории. |
category.[].name |
Наименование категории |
category.[].code |
Символьный код, если вы применяете у себя ЧПУ. |
category.[].parent |
Идентификатор родительского узла (древовидная структура данных). |
category.[].depth |
Глубина вложения узла (нумерация с 1 и далее). |
category.[].picture |
Ссылка на основное изображение для категории. |