Вход для партнёров
Хочу стать партнёром
Стать партнёром
Не верный номер инн
Ваша заявка принята
Результаты поиска

Оптовое 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

Ссылка на основное изображение для категории.

МЫ РЕКОМЕНДУЕМ