API интеграция

Материал из SmartWIKI

Версия от 16:02, 29 февраля 2024; Radmir g (обсуждение | вклад)
(разн.) ← Предыдущая версия | Текущая версия (разн.) | Следующая версия → (разн.)

Общие положения

Контакты IT отдела: automatisation@smart-shop.pro

Наша компания не является поставщиком IT-услуг, и мы не можем выделить вам специалиста для создания Web API на вашей стороне.

В первую очередь мы заинтересованы в синхронизации следующих данных по Web API:

  1. Свободный остаток товаров на ваших складах;
  2. Ваш прайс-лист;
  3. Данные о товарах в вашем каталоге и данные об их ETIM характеристиках;
  4. Данные о товарах в пути;

В случае наличия готового решения на вашей стороне, просьба отправить обратным письмом информацию о том, как мы можем взаимодействовать с вашим Web API, логин/пароль/токен доступа и контакты IT специалиста, которому мы сможем задавать вопросы, касающиеся Web API.

Свободный остаток товаров на ваших складах

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

  • Артикул;
  • Свободный остаток (кол-во товара, которое мы можем заказать прямо сейчас);
  • Склад (в случае, если у вас несколько складов);
  • Ед. измерения.

Предпочтительный формат выдачи с вашей стороны – JSON или CSV.

В идеале, нам бы хотелось синхронизировать остатки раз в час. В случае, если данные в вашей API выдаче обновляются реже, то просьба сообщить об этом.

Прайс-листы

Для синхронизации прайс-листов по Web API нам нужны следующие данные:

  • Артикул;
  • Цена без НДС с учетом всех скидок (та цена, по который вы готовы отгрузить нам товар);
  • Дата изменения цены.

Предпочтительный формат выдачи с вашей стороны – JSON или CSV.

Синхронизацию прайс-листов мы выполняем один раз в день, в 17 часов вечера.

Данные о товарах в вашем каталоге и данные об их ETIM характеристиках

В нашей системе мы используем ETIM 7 версии.

Для синхронизации каталога нам необходимы следующие данные:

  • Артикул;
  • Дата обновления данных по артикулу;
  • Описание товара;
  • Ед. измерения;
  • Серия товара;
  • Ссылка на товар в вашем каталоге;
  • Ссылка на картинку (может быть несколько);
  • Ссылка на сертификат, дата актуальности сертификата и тип сертификатов (может быть несколько);
  • Гарантийный срок;
  • Ссылка на youtube (видео обзор товара, если имеется)

Для синхронизации данных по ETIM нам необходимы следующие данные:

  • Идентификатор класса, в системе ETIM (значение вида EC*)
  • Идентификатор свойства в системе ETIM (значение вида EF*)
  • Значение свойства в формате ETIM:
    • Numeric – числовое обозначение в едином формате без ед. изм.
    • Range – диапазон значений в едином формате (например, x…y) без ед. измерения.
    • Alphanumeric – значение вида EV*, соответствующее текстовому обозначению
    • Boolean – логическое значение в едином формате.

Для нас важно, чтобы API для синхронизации товаров предоставляло возможность получать информацию:

  • По всем товарам вашего каталога;
  • По товарам вашего каталога, информация по которым менялась за определенный период;
  • По определенному артикулу из вашего каталога.

Подобное решение необходимо, чтобы не нагружать вашу и нашу систему при синхронизации каталогов.

Предпочтительный формат выдачи с вашей стороны – JSON.

Данные о товарах в пути (Ожидаемый приход)

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

Для синхронизации данных о товарах в пути по Web API нам нужны следующие данные:

  • Артикул;
  • Кол-во товара, которое должно поступить к вам на склад на дату
  • Ожидаемая дата поступления товара
  • Склад (в случае, если у вас несколько складов);
  • Ед. измерения.

Предпочтительный формат выдачи с вашей стороны – JSON или CSV.

API должно предоставлять возможность осуществлять выгрузку по всему каталогу сразу. Пагинация допускается. Желательно, чтобы ответ содержал только те товары, по которым есть информация об ожидаемом приходе.

Best practice или как реализовано у других

Непосредственно бэкэнд-реализация полностью зависит от того, как работает ваша система и как устроены ваши бизнес-процессы.

В данном разделе будут приведены примеры ответов API с которыми нам, как клиенту, будет удобно работать.

Свободный остаток товаров на ваших складах

{

   "products_count": “4824”,

    "stocks": [

        {

            "vendor_code": "ZENL1121",

            "brand_name":"Dekraft",

           "location_name": "Лобня",

             "unit": "м",

            "quantity": "15.000"

        },

        {

            "vendor_code": "ZENL1121",

            "brand_name":"Dekraft",

           "location_name ": "Екатеринбург",

            "unit_code": "упак",

            "quantity": "1000.000"

        }

    ]

}

  • products_count – кол-во товаров в выдаче
  • stocks – массив с товарами
    • vendor_code – артикул
    • brand_name – бренд
    • location_name – склад
    • unit – ед. измерения товара
    • quantity – свободный остаток

Прайс-лист

{

    "products_count": “4824”,

    "prices": [

        {

            "vendor_code": "ZENL1121",

            "price_withvat":"240.00",

            "price_novat": "200.00",

            "vat": "40.00",

            "base_price": "450.00"

        },

        {

            "vendor_code": "ZENL1121",

            "price_withvat ":"174.00",

            "price_novat": "145.00",

            "vat": "29.00",

            "base_price": "356.00"

        }

    ]

}

  • products_count – кол-во товаров в выдаче
  • prices – массив с товарами
    • vendor_code – артикул
    • price_withvat – цена с НДС, с учетом всех скидок
    • price_novat – цена без НДС, с учетом всех скидок
    • vat – НДС
    • base_price – базовая цена

Данные о товарах в вашем каталоге и данные об их ETIM характеристиках

{

"products_count": “4824”,

"catalog": [

        {

   "vendor_сode": "ZENL1121",

   "item_description" : "Авт. выкл. NM8N-1600H EM 3P 1250А 100кА с электр. расцепителем, LCD, 230AC (R)",

   "unit_name": "шт",

   "weight": "13.5",

   "volume": "0.01",

   "updated_at" : "2021-10-05 17:50:39",

   "barcode" : "124125778231",

   "guarantee_period" : "1",

   "series" : "ZEN",

   "youtube_code" : "43aV67g6S5Q",

   "catalog_link" : "https://smart-shop.pro/itemcard/%D0%A0%D0%AD%D0%9C%D0%97%20%D0%A2%D0%9C/SQ0117-0076",

   "pictures" : [

    {

     "type" : "Front"

     "link" : "https://vendor-catalog.smart-shop.pro/storage/EG000001/EC003248/photos/d97290f0fc601d977d4835f254a93092.jpg"

    }

   ],

   "certificates" : [

    {

     "type" : "TRTS"

     "type_name" : "Сертификат соответствия ТР ТС",

     "expiration_date" : "2021-10-05 17:50:39",

     "link" : "https://vendor-catalog.smart-shop.pro/storage/EG000001/EC003248/photos/d97290f0fc601d977d4835f254a93092.jpg"

    }

   ],

   "etim7" :

    {

     "class" : "EC001681"

     "class_name" : "Коммутационный шнур (патч-корд)",

     "features" : [

      {

       "id" : "EF001841"

       "name" : "Система зажима/крепления",

       "unit" : "",

       "type" : "A",

       "value" : "EV004564 "

      },

      {

       "id" : "EF001897"

       "name" : "Длина резания",

       "unit" : "EU570448",

       "type" : "N",

       "value" : "11.1"

      }

      {

       "id" : "EF004593"

       "name" : "Диапазон герметизации",

       "unit" : "EU570448",

       "type" : "R",

       "value" : "11...15"

      }

      {

       "id" : "EF007385"

       "name" : "С блокировкой ",

       "unit" : "",

       "type" : "L",

       "value" : "1"

      }

    }

   ]

   }, ...

  • products_count – кол-во товаров в выдаче
  • catalog – массив с товарами
    • vendor_code – артикул
    • item_description – описание товара
    • unit_name – ед. измерения товара
    • weight – вес
    • volume – объем
    • updated_at – дата обновления информации по товару
    • barcode – штрих-код
    • guarantee_period – гарантийный период
    • series – серия
    • catalog_link – ссылка на товар в каталоге
    • youtube_code – код youtube видео с обзором товара
    • pictures – массив с картинками
      • Type – тип
      • Link – ссылка
    • Certificates – массив с сертификатами
      • Type – тип
      • Type_name – Название типа
      • expiration_date – дата актуальности до
      • link – ссылка на сертификат
    • etim7 – описание etim7 характеристик
      • class – класс ETIM
      • class_name – название класса
      • features – массив свойств
        • id – идентификатор свойства
        • name – название свойства
        • unit – ед. измерения свойства
        • type – тип свойства
        • value – значение свойства

Данные о товарах в пути (Ожидаемый приход)

{

  "items": [

    {

      "vendor_code": "ZENL1121",

      "brand_name": "Dekraft",

      "unit": "м",

      "planned_arrival": [

        {

          "location_name": "Лобня",

          "quantity": "25.000",

          "planned_date": "2022-07-24"

        },

        {

          "location_name": "Лобня",

          "quantity": "15.000",

          "planned_date": "2022-07-28"

        },

        {

          "location_name": "Екатеринбург",

          "quantity": "15.000",

          "planned_date": "2022-07-28"

        }

      ]

    },

    {

      "vendor_code": "ZENL1515",

      "brand_name": "MyBrand",

      "unit": "упак.",

      "planned_arrival": []

    }

  ]

}