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

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

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

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

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

XML файл

Для клиентов доступен 1 XML файл, который хранит в себе всю необходимую информацию.

output_all.xml

Файл output_all.xml содержит всю необходимую информацию о каталогах (название, id, parent), а также информацию о товарах (название, код товара, описание, фотографии и т.п.). Обновляется он один раз в сутки. Давайте рассмотрим структуру файла output_all.xml

                
<?xml version="1.0" encoding="UTF-8"?>
<yml_catalog date="2024-11-11 10:10">
    <shop>
        <name>АЛМА (в Бийске)</name>
        <company>ООО "АЛМА"</company>
        <url>https://alma.su</url>
        <currencies>
            <currency id="RUR" rate="1"/>
        </currencies>
        <categories>
            <category id="579">Трубопровод</category>
            <category id="623" parentId="579">Полипропилен</category>
            ...
        </categories>

        <offers>
            <offer id="207701" available="true">
                <url>https://alma.su</url>
                <name>Водонагреватель накопительный 6л, эмаль, белый, под раковиной OASIS KP-6</name>
                <price>7600</price>
                <oldprice>10032</oldprice>
                <categoryId>359</categoryId>
                <picture>https://alma.su/upload/iblock/f92/f92bb26e612a93f4bac46e8b7d683b5d.jpg</picture>
                <vat>6</vat>
                <shipment-options>
                    <option days="1" order-before="23"/>
                </shipment-options>
                <vendor>Oasis</vendor>
                <vendorCode>УТ-00029489</vendorCode>
                <description>Электрический накопительный водонагреватель.</description>
                <outlets>
                    <outlet id="36723243728567823" instock="0" price="7600" oldprice="10032"/>
                </outlets>
            </offer>
            ...
        </offers>
    </shop>
</yml_catalog>
                
            

REST JSON

Пример простейшей функции и работа с ней.

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

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

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

                
/**
 * Выполняем запрос к API
 * 
 * @param array $post - ожидает обязательные параметры: 
 *     $post['token'] - API токен,
 *     $post['inn'] - ИНН
 * @param string $point - точка входа
 *
 * @return array $result
 */
function makeRequest($post, $point)
{
    $agent = 'ALMA API v2.0';
    $curl = curl_init();
    curl_setopt($curl, CURLOPT_URL, 'https://alma.su'.$point);
    curl_setopt($curl, CURLOPT_SSL_VERIFYPEER, false);
    curl_setopt($curl, CURLOPT_RETURNTRANSFER, true);
    curl_setopt($curl, CURLOPT_HEADER, false);
    curl_setopt($curl, CURLOPT_POST, true);
    curl_setopt($curl, CURLOPT_USERAGENT, $agent);
    curl_setopt($curl, CURLOPT_POSTFIELDS, $post);
    $result = curl_exec($curl);
    curl_close($curl);
    return $result;
}
                
            

• $post — одномерный массив (ключ => значение). Обязательно должен содержать:
  $post['token'] - Ваш API TOKEN,
  $post['inn'] - Ваш ИНН
• $point — точка входа в API. Например '/api/status/' - точка входа для проверки доступности API.

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

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

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

Запрос к /status

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

                
# заполняем данные
$post['token'] = 'b3mC..dF'; # Ваш TOKEN
$post['inn']   = '113..742'; # Ваш INN
$agent = 'ALMA API v2.0';

# формируем запрос
$curl = curl_init();
curl_setopt($curl, CURLOPT_URL, 'https://alma.su/api/status/');
curl_setopt($curl, CURLOPT_SSL_VERIFYPEER, false);
curl_setopt($curl, CURLOPT_RETURNTRANSFER, true);
curl_setopt($curl, CURLOPT_HEADER, false);
curl_setopt($curl, CURLOPT_USERAGENT, $agent);
curl_setopt($curl, CURLOPT_POST, true);
curl_setopt($curl, CURLOPT_POSTFIELDS, $post);
$result = curl_exec($curl);
$http = curl_getinfo($curl, CURLINFO_HTTP_CODE);
curl_close($curl);
                
            

Примеры ответа

                    
Content-type: application-json
{
    "status":true,
    "message":"API доступен"
}
                    
                

Запрос к /element

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

                
# заполняем данные
$post['token'] = 'b3mC..dF'; # Ваш TOKEN
$post['inn']   = '113..742'; # Ваш INN
$agent = 'ALMA API v2.0';

$post['code']  = 'УТ-00007526'; # УТ-код товара (так же подойдет 7526)

# формируем запрос
$curl = curl_init();
curl_setopt($curl, CURLOPT_URL, 'https://alma.su/api/element/');
curl_setopt($curl, CURLOPT_SSL_VERIFYPEER, false);
curl_setopt($curl, CURLOPT_RETURNTRANSFER, true);
curl_setopt($curl, CURLOPT_HEADER, false);
curl_setopt($curl, CURLOPT_USERAGENT, $agent);
curl_setopt($curl, CURLOPT_POST, true);
curl_setopt($curl, CURLOPT_POSTFIELDS, $post);
$result = curl_exec($curl);
$http = curl_getinfo($curl, CURLINFO_HTTP_CODE);
curl_close($curl);
                
            

Примеры ответа

                    
Content-type: application-json
{
    "status":true,
    "element":
        {
            "id"       : 40394,
            "name"     : "Душевая кабина PROFLINE 8900 B (90*90), средний поддон ...",
            "category" : 482,
            "quantity" : 0,
            "unit"     : "шт",
            "images_count": 9,
            "images": [
                {
                    "240": "https://cdn.ret.su/elements/88/20888/20888_0_240x240.webp",
                    "1024": "https://cdn.ret.su/elements/88/20888/20888_0_1024x1024.webp",
                    "orig": "https://cdn.ret.su/elements/88/20888/20888_0_orig.webp"
                },
                {
                    "240": "https://cdn.ret.su/elements/88/20888/20888_1_240x240.webp",
                    "1024": "https://cdn.ret.su/elements/88/20888/20888_1_1024x1024.webp",
                    "orig": "https://cdn.ret.su/elements/88/20888/20888_1_orig.webp"
                },
                ...
            ],
            "desc"     : "Угловая душевая кабина. <br \/>\nДлина: 90 см. </br \/>\nШирина: ...",
            "price"    : "22728.57"
        }
}
                    
                

Запрос к /elements

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

                
# заполняем данные
$post['token'] = 'b3mC..dF'; # Ваш TOKEN
$post['inn']   = '113..742'; # Ваш INN
$agent = 'ALMA API v2.0';

# формируем запрос
$curl = curl_init();
curl_setopt($curl, CURLOPT_URL, 'https://alma.su/api/elements/');
curl_setopt($curl, CURLOPT_SSL_VERIFYPEER, false);
curl_setopt($curl, CURLOPT_RETURNTRANSFER, true);
curl_setopt($curl, CURLOPT_HEADER, false);
curl_setopt($curl, CURLOPT_USERAGENT, $agent);
curl_setopt($curl, CURLOPT_POST, true);
curl_setopt($curl, CURLOPT_POSTFIELDS, $post);
$result = curl_exec($curl);
$http = curl_getinfo($curl, CURLINFO_HTTP_CODE);
curl_close($curl);
                
            

Примеры ответа

                    
Content-type: application-json
{
    "status": true,
    "elements": [
        {
            "id": 17816,
            "name": "Пена профессиональная Ultima Gun 65л 820мл (летняя)",
            "category": 385,
            "unit": "шт",
            "images_count": 1,
            "images": [
                {
                    "240": "https://cdn.ret.su/elements/61/17816/17816_0_240x240.webp",
                    "1024": "https://cdn.ret.su/elements/61/17816/17816_0_1024x1024.webp",
                    "orig": "https://cdn.ret.su/elements/61/17816/17816_0_orig.webp"
                }
            ],
            "desc": "Ultima Gun – зимняя монтажная пена, предназначена для ..."
        },
        {
            "id": 7526,
            "name": "Болт DIN 933 16х75 оцинкованный",
            "category": 800,
            "unit": "шт",
            "images_count": 2,
            "images": [
                {
                    "240": "https://cdn.ret.su/elements/62/7526/7526_0_240x240.webp",
                    "1024": "https://cdn.ret.su/elements/62/7526/7526_0_1024x1024.webp",
                    "orig": "https://cdn.ret.su/elements/62/7526/7526_0_orig.webp"
                },
                {
                    "240": "https://cdn.ret.su/elements/62/7526/7526_1_240x240.webp",
                    "1024": "https://cdn.ret.su/elements/62/7526/7526_1_1024x1024.webp",
                    "orig": "https://cdn.ret.su/elements/62/7526/7526_1_orig.webp"
                }
            ],
            "desc": "Шестигранная головка делает возможной затяжку с максимальным ..."
        },
        ...
    ]
}
                    
                

Запрос к /prices

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

                
# заполняем данные
$post['token'] = 'Ваш токен';
$post['inn']   = 'Ваш ИНН';
$agent = 'ALMA API v2.0';

# формируем запрос
$curl = curl_init();
curl_setopt($curl, CURLOPT_URL, 'https://alma.su/api/prices/');
curl_setopt($curl, CURLOPT_SSL_VERIFYPEER, false);
curl_setopt($curl, CURLOPT_RETURNTRANSFER, true);
curl_setopt($curl, CURLOPT_HEADER, false);
curl_setopt($curl, CURLOPT_USERAGENT, $agent);
curl_setopt($curl, CURLOPT_POST, true);
curl_setopt($curl, CURLOPT_POSTFIELDS, $post);
$result = curl_exec($curl);
$http = curl_getinfo($curl, CURLINFO_HTTP_CODE);
curl_close($curl);
                
            

Примеры ответа

                    
Content-type: application-json
{
    "status":true,
    "elements":
    [
        {
            "id": 10917,
            "price": "2037.52",
            "rrp": "2489.00"
        },
        {
            "id": 16782,
            "price": "155.02",
            "rrp": "219.00"
        },
        {
            "id": 16783,
            "price": "170.17",
            "rrp": "239.00"
        },
    ]
}
                    
                

Запрос к /properties

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

                
# заполняем данные
$post['token'] = 'Ваш токен';
$post['inn']   = 'Ваш ИНН';
$agent = 'ALMA API v2.0';

# формируем запрос
$curl = curl_init();
curl_setopt($curl, CURLOPT_URL, 'https://alma.su/api/props/');
curl_setopt($curl, CURLOPT_SSL_VERIFYPEER, false);
curl_setopt($curl, CURLOPT_RETURNTRANSFER, true);
curl_setopt($curl, CURLOPT_HEADER, false);
curl_setopt($curl, CURLOPT_USERAGENT, $agent);
curl_setopt($curl, CURLOPT_POST, true);
curl_setopt($curl, CURLOPT_POSTFIELDS, $post);
$result = curl_exec($curl);
$http = curl_getinfo($curl, CURLINFO_HTTP_CODE);
curl_close($curl);
                
            

Примеры ответа

                    
Content-type: application-json
{
    "status": true,
    "17816":"[{\"name\":\"\К\о\д \",\"value\":\"\У\Т-00017816\"},{\"name\":\"\О\б\ъ\е\м \",\"value\":\"750\"},{\"name\":\"\Г\а\р\а\н\т\и\я  (\м\е\с)\",\"value\":\"12\"},{\"name\":\"\Б\р\е\н\д\",\"value\":\"Makroflex\"},{\"name\":\"\С\т\р\а\н\а \",\"value\":\"\Ф\и\н\л\я\н\д\и\я\"},{\"name\":\"\П\р\о\и\з\в\о\д\и\т\е\л\ь \",\"value\":\"Makroflex\"}]",
    "1011":"[{\"name\":\"\К\о\д \",\"value\":\"\У\Т-00001011\"},{\"name\":\"\О\б\ъ\е\м \",\"value\":\"2\"},{\"name\":\"\Г\а\р\а\н\т\и\я  (\м\е\с)\",\"value\":\"12\"},{\"name\":\"\Б\р\е\н\д\",\"value\":\"\н\е \у\к\а\з\а\н\о\"},{\"name\":\"\С\т\р\а\н\а \",\"value\":\"\Р\о\с\с\и\я\"},{\"name\":\"\П\р\о\и\з\в\о\д\и\т\е\л\ь \",\"value\":\"\н\е \у\к\а\з\а\н\о\"}]",
    ...
}
                    
                

Запрос к /quantity

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

                
# заполняем данные
$post['token'] = 'Ваш токен';
$post['inn']   = 'Ваш ИНН';
$agent = 'ALMA API v2.0';

# формируем запрос
$curl = curl_init();
curl_setopt($curl, CURLOPT_URL, 'https://alma.su/api/quantity/');
curl_setopt($curl, CURLOPT_SSL_VERIFYPEER, false);
curl_setopt($curl, CURLOPT_RETURNTRANSFER, true);
curl_setopt($curl, CURLOPT_HEADER, false);
curl_setopt($curl, CURLOPT_USERAGENT, $agent);
curl_setopt($curl, CURLOPT_POST, true);
curl_setopt($curl, CURLOPT_POSTFIELDS, $post);
$result = curl_exec($curl);
$http = curl_getinfo($curl, CURLINFO_HTTP_CODE);
curl_close($curl);
                
            

Примеры ответа

                    
Content-type: application-json
{
    "status":true,
    "elements":
    [
        {
            "id"    : 40394,
            "quantity" : 0
        },
        {
            "id"    : 1011,
            "quantity" : 129
        },
        {
            "id"    : 7526,
            "quantity" : 111
        },
        ...
    ]
}
                    
                

Запрос к /category

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

                
# заполняем данные
$post['token'] = 'Ваш токен';
$post['inn']   = 'Ваш ИНН';
$agent = 'ALMA API v2.0';

# формируем запрос
$curl = curl_init();
curl_setopt($curl, CURLOPT_URL, 'https://alma.su/api/category/');
curl_setopt($curl, CURLOPT_SSL_VERIFYPEER, false);
curl_setopt($curl, CURLOPT_RETURNTRANSFER, true);
curl_setopt($curl, CURLOPT_HEADER, false);
curl_setopt($curl, CURLOPT_USERAGENT, $agent);
curl_setopt($curl, CURLOPT_POST, true);
curl_setopt($curl, CURLOPT_POSTFIELDS, $post);
$result = curl_exec($curl);
$http = curl_getinfo($curl, CURLINFO_HTTP_CODE);
curl_close($curl);

# ответ сервера
var_dump($result);
                
            

Примеры ответа

                    
Content-type: application-json
{
        "status":true,
        "category":
        [
            {
                "id"       : 579,
                "name"     : "Трубопровод",
                "code"     : "truboprovod",
                "parent"   : null,
                "depth"    : "1",
                "picture"  : "https://cdn.alma.su/category/9/579/579_200x200.webp"
            },
            {
                "id"       : 623,
                "name"     : "Полипропилен",
                "code"     : "polipropilen_belyy",
                "parent"   : "579",
                "depth"    : "2",
                "picture"  : "https://cdn.alma.su/category/3/623/623_200x200.webp"
            }
            ...
        ]
    }
                    
                

PHP Библиотека

Если вы используете PHP на задней стороне вашего приложения - использование нашей библиотеки будет отличным решением

Наша готовая PHP библиотека с открытым исходным кодом позволяет подключиться к API и выполнять все вышеперечисленные запросы из документации в одну строчку.

Начало работы

Для начала работы склонируйте в свой проект наши файлы из публичного репозитория на гитхабе

Определите параметры ТОКЕН и ИНН как константы const TOKEN = "3vc...21c"; и const INN = "123...789";

Подключите библиотеку alma.class.php и создайте её экземпляр класса, передав в него констаты с параметрами

$api = new Alma\Api(TOKEN, INN);

Примеры запросов

                
<?php

# подключим класс АПИ
require_once '/alma.class.php';

# определим параметры
const TOKEN = "3v5...43v";
const INN   = "123...789"; 

# создаем экземпляр класса
$api = new Alma\Api(TOKEN, INN);


# Проверка доступности API
# /status
$api->getStatus();


# Получить информацию о товаре по УТ
# /element
$element = 20888;
$api->getElement( $element );


# Получить информацию о всех товарах
# /elements
$api->getElements();


# Получить информацию о всех ценах
# /prices
$api->getPrices();


# Получить информацию о всех props
# /properties
$api->getProperties();


# Получить информацию о всех остатках
# /quantity
$api->getQuantity();


# Получить информацию о всех категориях
# /category
$api->getCategory();