Для работы с заказами и товарами Forcs.ru имеется API https://forcs.ru/api/v2/

API может возвращать результаты запросов в двух форматах: json и xml. Для того, чтобы получить ответ от сервера в определённом формате, к пути ресурса через точку необходимо добавить его формат [ресурс][.формат] (например, /references/brands.json). Если в пути ресурса формат не указан, ответ будет возвращён в формате по умолчанию — JSON.

Поддерживается два способа авторизации по ключу API_KEY:

• передача ключа в параметре "key" строки запроса, пример: /references/brands?key=API_KEY
• передача ключа в заголовке "Authorization: Bearer" запроса, пример: Authorization: Bearer API_KEY

Ключ запрашивается на сайте в личном кабинете https://forcs.ru/personal/api/.
Для каждой связки логин-договор генерируется отдельный ключ.

С течением времени могут измениться как перечень запросов, так их структура и структура ответов.
Для уверенности в том, что используется API желаемой версии, необходимо передавать версию в строке запроса.
Итого запрос должен выглядеть следующим образом: /[версия]/[ресурс]
Например: https://forcs.ru/api/v2/references/brands?key=123

Перечень версий:

Входные данные

Выходные данные

Возвращает массив объектов-брендов (brands), каждый из которых в виде:

Возвращает адреса доставки контрагента к которому прикреплен пользователь

Входные данные

Выходные данные

Возвращает массив объектов-адресов доставки (shipment_address_list), каждый из которых в виде:

Примеры

• https://forcs.ru/api/v2/references/shipment_address/active?key=123
• https://forcs.ru/api/v2/references/shipment_address/active.xml?key=123

Возвращает наличие товаров с ценами и сроками доставки.

Сравнение артикула производится в "нормализованном виде", т.е. сравниваются артикулы, из которых удалены все символы, кроме a-zA-Z0-9

Входные данные

Массив items

Каждый элемент массива items — это ассоциативный массив, который может содержать элементы со следующими ключами.

Поиск с аналогами (analogs=1) может быть произведён только по одному элементу входных данных (одному элементу массива items) за запрос. Поиск без аналогов (analogs=0) — до 50 элементов (items) в одном запросе (если передано больше items, остальные не обрабатываются)

В случае, если по входным данным невозможно однозначно определить искомый товар (такое может случиться, например, при поиске по артикулу, который встречается у разных брендов), то

• если осуществляется запрос с analogs=1, будет возвращён HTTP-код 300 (Multiple Choices), в теле ответа будет список товаров, подходящих под входные данные без цен-остатков по ним.
• если осуществляется запрос с analogs=0, будет возвращены результаты для каждого товара, подходящего под входные данные с ценами-остатками.

Выходные данные

Возвращает массив объектов-товаров (resources), а так же предупреждений (warnings), если такие есть.
Каждый элемент resource представляет собой ассоциативный массив:

Объект предложения (Offer)

Объект склада (Warehouse)

Примеры

• По внутреннему ID товара
  Единственный случай, когда в результатах поиска для каждого элемента из входных данных гарантированно будет только одна товарная позиция в результатах.
  • Без аналогов
    • Один элемент на входе
      • https://forcs.ru/api/v2/ordering/get_stock?key=123&items[0][resource_id]=214572
      • https://forcs.ru/api/v2/ordering/get_stock.xml?key=123&items[0][resource_id]=214572
    • Несколько элементов на входе
      • https://forcs.ru/api/v2/ordering/get_stock?key=123&items[0][resource_id]=213857&items[1][resource_id]=214572
      • https://forcs.ru/api/v2/ordering/get_stock.xml?key=123&items[0][resource_id]=213857&items[1][resource_id]=214572
  • С аналогами
    • https://forcs.ru/api/v2/ordering/get_stock?key=123&items[0][resource_id]=214572&analogs=1
    • https://forcs.ru/api/v2/ordering/get_stock.xml?key=123&items[0][resource_id]=214572&analogs=1
• По артикулу товара и ID бренда
  Для каждого из товара может быть более, чем один результат. Понять, к какому из входных данных относится результат можно по source_idx — он будет соответствовать ключу параметра items. (ключи могут быть как числовые, так и текстовые)
  • Без аналогов
    • Один элемент на входе
      https://forcs.ru/api/v2/ordering/get_stock?key=123&items[0][resource_article]=C103&items[0][brand_id]=217471
    • Несколько элементов на входе
      https://forcs.ru/api/v2/ordering/get_stock?key=123&items[0][resource_article]=C103&items[0][brand_id]=8190&items[1][resource_article]=C103&items[1][brand_id]=217471

Разместить заказ

Входные данные

Объект заказа order

Объект заказываемого товара (items):

Выходные данные

Возвращает объект заказа (см. описание - Объект заказа order) с заполненным полем id, либо массив ошибок (errors). В обоих случаях так же может быть возвращён массив предупреждений (warnings), если такие имеются.

Пример

application/json

    POST /ordering/place_order.json?key=123 HTTP/1.1
    Host: api.forcs.ru
    Content-Type: application/json
    Content-Length: 695

    {
        "order": {
            "is_test": 1,
            "dispatch_type": 3,
            "dispatch_time": 1,
            "dispatch_at": "2021-07-07",
            "person": "Иван Иванович",
            "comment": "запчасти для Ипполита",
            "shipment_address": "Москва, 3-я улица Строителей, дом 25, квартира 12",
            "items": [
                {"resource_id": 213857, "warehouse_id": 17, "quantity": 1},
                {"resource_id": 213858, "warehouse_id": 17, "quantity": 2}
            ]
        }
    }

Входные данные

Выходные данные

Возвращает массив объектов-статусов, каждый из которых в виде:

Примеры

• https://forcs.ru/api/v2/references/states?key=123
• https://forcs.ru/api/v2/references/states.xml?key=123

Возвращает список активных заказов и статусы по ним.

Входные данные

Выходные данные

Возвращает массив объектов заказов (Order):

Объект заказанного товара (items):

Примеры

• https://forcs.ru/api/v2/ordering/states/active?key=123
• https://forcs.ru/api/v2/ordering/states/active.xml?key=123

Возвращает список заказов с переданными идентификаторами и статусы по ним.

Входные данные

Выходные данные

Возвращает массив объектов заказов Order (см. /ordering/states/active)

Примеры

• https://forcs.ru/api/v2/ordering/states?key=123&orders[]=3434&orders[]=3433&orders[]=3432&orders[]=3431&orders[]=3401
• https://forcs.ru/api/v2/ordering/states.xml?key=123&orders[]=3434&orders[]=3433&orders[]=3432&orders[]=3431&orders[]=3401

Формат предупреждений json

{
    "resources": [{}]
    "warnings": [
        {
            "code": "WARN_ARTICLE_IS_AMBIGUOUS",
            "text": "Поиск не дает точных результатов. Пожалуйста уточните параметры поиска"
            [могут присутствовать дополнительные поля, в зависимости от предупреждений]
        }
    ]
}
                        

Список предупреждений

Формат ошибок json

{
    "errors": [
        {
            "code": "ERROR_GET_ORDER_STATUS_ACTIVE",
            "text": "Ошибка при получении списка статусов активных заказов"
            [могут присутствовать дополнительные поля, в зависимости от ошибок]
        }
    ]
}
                        

Список ошибок