B2B API для наших оптовых клиентов (XML / JSON

Вход для партнёров

Хочу стать партнёром

Оптовое API
XML файлы
REST JSON
- коды ошибок
- status
- auth
- check
- element
- elements
- prices
- quantity
- category

Оптовое API для клиентов

API представляет набор правил и функций, позволяющих двум разным приложениям взаимодействовать друг с другом (например между 1С и сайтом). API выступает посредником между приложениями, отправляя запросы и ответы.

Для чего это нужно? Автоматизация. Не нужно вручную вносить информацию о товарах (в 1С, на сайт или CRM). Вы можете попросить программиста, который обслуживает Вашу компанию, и он используя наше API автоматизирует этот процесс. Это же касается своевременного обновления цен и остатков.

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

XML-RPC — позволяет выполнять обмен функциями между двумя или более сетями. XML-RPC использует XML для описания запросов и ответов, и при помощи протоколов HTTP передает информацию от клиента к серверу.
REST API — репрезентативная передача состояния (REST) — это архитектурный стиль, который осуществляет реализацию клиента и сервера независимо друг от друга. Сервисы в REST API взаимодействуют по протоколу HTTP.

XML файлы

Нашим клиентам доступны 3 файла XML, в которых хранятся различные данные. Каждый из файлов обновляется с разной переодичностью.

elements.xml

Файл elements.xml — содержит основную информацию о товарах (название, код товара, описание, фотографии и т.п.). Ещё он содержит информацию о структуре каталога, название категорий и какие товары в них входят. Обновляется он один раз в сутки. Давайте рассмотрим структуру файла elements.xml

Элемент	Описание
`xml`	Стандартный XML-заголовок. Должен начинаться с первой строки, с нулевого символа.
`xml_catalog`	Мы используем в качестве корневого xml элементa: `<xml_catalog>` с атрибутом `date`. Этот атрибут сообщает дату и время момента, на который актуальны данные в файле.
`categories`	Cодержит список категорий. Каждая категория описывается отдельным элементом `category`.
`category`	Название категории. Атрибут `id` - идентификатор категории. Атрибут `parentId` - это идентификатор категории более высокого уровня (если категория является дочерней). Если `parentId` не указан, категория считается корневой.
`offers`	Список товаров. Каждый товар описывается в отдельном элементе `offer`.
`offer`	Содержит узел информации о конкретном товаре. Атрибут `id` - это уникальный код товара.
`name`	Наименование номенклатуры. Не содержит спецсимволов.
`categoryId`	Идентификатор категории товара (целое число).
`barcode`	Штрихкод товара от производителя в формате: EAN-13.
`unit`	Единица измерения, формат и стандарт данных не регламентирован, обрабатывайте как строковые данные.
`images`	Родительский узел содержащий информацию о фотографиям к товару. Этот узел содержит дополнительную избыточную информацию, его можно игнорировать. Структура введена для удобства.
`count`	Содержит информацию о количестве фотографий у товара на текущий момент.
`hash`	Это расчитанное значение crc32, от последоательной (от 1 до n) конкатенации строковых значений атрибутов `hash` у элементов `picture` в узле элемента `pictures`. Пример конкатенации: crc32("aaaaaabbbbbbcccccc"). Используя это значение, можно оптимизировать проверку о необходимости обновления изображений, чтобы не выкачивать их каждый раз и своевременно удалять и обновлять устаревшие.
`pictures`	Родительский узел содержащий информацию о ссылках на фотографии к товару.
`picture`	Ссылка на фотографию к товару. Атрибут `hash` - содержит crc32 значение хэш-функции файла изображения. Используя этот атрибут, можно оптимизировать обновление только изменившихся фотографий.
`description`	Текстовое описание товара. Формат не регламентирован. Не содержит спецсимволов.
`params`	Родительский узел содержащий информацию о свойствах товара. Каждое свойство описывается в отдельном элементе `param`.
`param`	Текущее значение свойства. Атрибут `name` - содержит название свойства. Атрибут `type` - может принимать четыре значения: список, строка, число, логическое (boolean). Атрибут `code` - уникальный строковый идентификатор свойства.

price.xml

Файл price.xml — содержит информацию о стоимости товара, по которой вы можете его купить, а также о рекомендуемой розничной цене. Обновляется каждые 6 часов. Давайте рассмотрим структуру файла.

Элемент	Описание
`xml`	Стандартный XML-заголовок. Должен начинаться с первой строки, с нулевого символа.
`xml_catalog`	Мы используем в качестве корневого xml элементa: `<xml_catalog>` с атрибутом `date`. Этот атрибут сообщает дату и время момента, на который актуальны данные в файле.
`elements`	Cодержит список товаров. Каждый товар описывается отдельным элементом `element`.
`element`	Текущая стоимость товара в Российских рублях. Атрибут `id` - уникальный идентификатор товара.

quantity.xml

Файл quantity.xml — содержит информацию о текущих остатках товара на нашем складе. Обновляется каждые 30 минут. Рассмотрим структуру файла:

Элемент	Описание
`xml`	Стандартный XML-заголовок. Должен начинаться с первой строки, с нулевого символа.
`xml_catalog`	Мы используем в качестве корневого xml элементa: `<xml_catalog>` с атрибутом `date`. Этот атрибут сообщает дату и время момента, на который актуальны данные в файле.
`elements`	Cодержит список товаров. Каждый товар описывается отдельным элементом `element`.
`element`	Текущие остатки товара на нашем складе. Атрибут `id` - уникальный идентификатор товара.

REST JSON

Пример простейшего класса и работа с ним.

Для предоставления доступа к REST JSON, вы должны отправить заявку к нам на почту opt@alma.su. В заявке укажите: инн и ip адрес (с которого будете делать запросы). В целях безопасности у нас доступ только по white list ip.

Что дальше? Мы присвоим вашей организации базовый токен доступа и внесём ваш ip адрес в список исключений. После этого оповестим Вас ответным письмом или звонком. Используя базовый токен доступа, вы сможете авторизоваться в нашей системе и получить временный токен доступа, через который и происходят все дальнейшие запросы. Временный токен доступа нужен для того, чтобы снизить риск утечки базового токена для вашей организации.

Простейший пример запроса к нашему API на языке PHP вы можете посмотреть ниже:

$post — одномерный массив (ключ => значение). Например может содержать временный токен ($post['token'] = 'xxx') и код товара ($post['code']=32225). Рекомендуем ознакомиться с примерами ниже.
$point — точка входа в API. Например check - точка входа для проверки, что временный токен действующий. А elements - это точка входа о получении перечня всех доступных товаров с их описанием и свойствами.

Распространённые коды ошибок

Коды ошибок мы отдаём через функцию php http_response_code(). Можете более подробно изучить её в документации.

INFO HTTP CODE	Описание
`500`	Прервано. Высокая нагрузка на сервер, попробуйте позже.
`503`	Сервис временно недоступен. API отключено в ручном режиме.
`400`	Недопустимые входные данные в запросе. Неверные значения или не все ожидаемые параметры были переданы в запросе.
`404`	Неверно указан инн или базовый токен. Товар не найден. Не установлен вид цены. Товары не найдены.
`403`	Недостаточно разрешений на выполнение этой операции. Нет прав на получение цен.

Для получения кода ответа сервера используйте curl_getinfo($curl,CURLINFO_HTTP_CODE);

Запрос к /status

Проверка доступности API (пример на PHP).

Возвращаемое значение	Описание
`status`	`true` - API доступно. `false` - недоступно.
`message`	Информационное поясняющее сообщение. Содержит описание ошибки или наоборот удачного выполнения запроса.

Запрос к /auth

Получение временного рабочего токена для API, через авторизацию базовый токен + инн (пример на PHP). Базовый токен мы выдаём вам при подключении к нашему API.

Возвращаемое значение	Описание
`status`	`true` - авторизовались, временный токен выпущен. `false` - авторизация не удалась.
`token`	Временный зарегистрированный токен, который вы можете использовать в других запросах.
`life`	время жизни этого токена в секундах с момента выдачи.

Запрос к /check

Проверка актуальности временного токена. Если токен не актуален, то требуется перевыпуск нового через запрос auth.

Возвращаемое значение	Описание
`status`	`true` - временный токен актуален. `false` - нужен перевыпуск временного токена.

Запрос к /element

Позволяет получить подробную информацию о наименовании товара по его коду.

Возвращаемое значение	Описание
`status`	`true` - данные получены. `false` - товар по коду не найден (вывели с продажи).
`element`	Массив который содержит подробную информацию о товаре.
`element.id`	Код товара.
`element.name`	Наименование товара (текстовая строка).
`element.category`	Идентификатор родительской категории, к которой привязан товар.
`element.quantity`	Текущий доступный для продажи остаток.
`element.unit`	Единица измерения остатка.
`element.images`	Количество фотографий у данного товара. Путь до самих изображений формируется так: `https://cdn.alma.su/elements/YY/XXXXX/XXXXX_Z_240x240.webp` . Формат всегда `webp` - другие не возвращаются. `XXXXX` - это код товара. `Z` - это порядковый номер фотографии (нумерация с 0). Например в данном примере у товара две фотографии, значит `Z` может принимать два значения [0 и 1]. `YY` - это последние две цифры кода товара, поменянные местами, получить это можно используя следующий код`$yy = substr(strrev($code), 0, 2)` . Приносим извинения, так исторически сложилось. Доступные разрешения изображений: `64x64, 240x240, 480x480, 1024x1024, orig`. Вы можете использовать любое из них в нужных вам местах или использовать оригинальное изображение `orig` (в том числе выкачать на свой сервер).
`element.desc`	Подробное описание товара. Может содержать в себе экранированный html тег `<br>` и управляющий символ переноса строки `\n`. Не доверяйте приходящим данным в целях безопасности, обрабатывайте как сырые данные, чтобы в случае компроментации нашего сервера, нельзя было внедрить вредоносный код к вам через нас.
`element.price`	Стоимость единицы остатка товара.

Запрос к /elements

Позволяет получить подробную информацию сразу о всех товарах в нашем ассортименте.

Возвращаемое значение	Описание
`status`	`true` - данные получены. `false` - ошибка, смотрите в `message` описание ошибки.
`elements`	Массив с информацией о всех товарах в ассортименте.
`elements.[].id`	Код товара.
`elements.[].name`	Наименование товара (текстовая строка).
`elements.[].category`	Идентификатор родительской категории, к которой привязан товар.
`elements.[].unit`	Единица измерения остатка.
`elements.[].images`	Количество фотографий у данного товара. Путь до самих изображений формируется так: `https://cdn.alma.su/elements/YY/XXXXX/XXXXX_Z_240x240.webp` . Формат всегда `webp` - другие не возвращаются. `XXXXX` - это код товара. `Z` - это порядковый номер фотографии (нумерация с 0). Например в данном примере у товара две фотографии, значит `Z` может принимать два значения [0 и 1]. `YY` - это последние две цифры кода товара, поменянные местами, получить это можно используя следующий код`$yy = substr(strrev($code), 0, 2)` . Приносим извинения, так исторически сложилось. Доступные разрешения изображений: `64x64, 240x240, 480x480, 1024x1024, orig`. Вы можете использовать любое из них в нужных вам местах или использовать оригинальное изображение `orig` (в том числе выкачать на свой сервер).
`elements.[].desc`	Подробное описание товара. Может содержать в себе экранированный html тег `<br>` и управляющий символ переноса строки `\n`. Не доверяйте приходящим данным в целях безопасности, обрабатывайте как сырые данные, чтобы в случае компроментации нашего сервера, нельзя было внедрить вредоносный код к вам через нас.

Запрос к /prices

Позволяет получить подробную информацию сразу о ценах для всех товаров в нашем ассортименте.

Возвращаемое значение	Описание
`status`	`true` - данные получены. `false` - ошибка, смотрите в `message` описание ошибки.
`elements`	Массив с информацией о всех ценах для всех товаров в ассортименте.
`elements.[].id`	Код товара.
`elements.[].price`	Стоимость товара в рублях.

Запрос к /quantity

Позволяет получить подробную информацию сразу об остатках для всех товаров в нашем ассортименте.

Возвращаемое значение	Описание
`status`	`true` - данные получены. `false` - ошибка, смотрите в `message` описание ошибки.
`elements`	Массив с информацией о всех ценах для всех товаров в ассортименте.
`elements.[].id`	Код товара.
`elements.[].quantity`	Текущий остаток доступный для продажи.

Запрос к /category

Позволяет получить подробную информацию о всех категориях.

Возвращаемое значение	Описание
`status`	`true` - данные получены. `false` - ошибка, смотрите в `message` описание ошибки.
`category`	Массив с информацией о всех категориях товара.
`category.[].id`	Идентификатор категории.
`category.[].name`	Наименование категории
`category.[].code`	Символьный код, если вы применяете у себя ЧПУ.
`category.[].parent`	Идентификатор родительского узла (древовидная структура данных).
`category.[].depth`	Глубина вложения узла (нумерация с 1 и далее).
`category.[].picture`	Ссылка на основное изображение для категории.