Все операции, производимые на сайте интернет-магазина «ТоргПрод» (далее — ИМ), можно производить программным способом через HTTP-запросы. Данный документ описывает формат таких запросов и ответов.

1. Общее

Все объекты и атрибуты объектов, используемые в ИМ имеют два способа наименования. Их можно рассматривать, как одно и то же название одной сущности, используемое в разных ситуациях.

Далее в документации термины атрибут и поле считаются взаимозаменяемыми и означают одно и то же.

Забегая вперед можно сказать, что одно название используется при операциях чтения и поиска по базе ИМ — read-название, а второе — при операциях записи (создания и редактирования сущностей) — write-название. В каждой конкретной операции будут описаны оба названия.

В качестве примера приведем атрибут, отвечающий за название в карточке продукции:

Атрибуты объектов продукции (общее название объектов продукции — t_2)
Атрибут Write-название Read-название

Название продукции

f_1002110000

name

1.1. Авторизация

Для всех участников ИМ — и покупателей, и поставщиков — единой точкой входа является сайт https://www.bgoperator.ru/bgmarket/. Далее личные кабинеты предоставляют разные функции в зависимости от типа логина. Через свой логин можно делать все операции с товарами, прайсом и заказами, как вручную (через веб-браузер), так и программно, посылая HTTP-запросы на определнные URL-ы.

При программном HTTP-запросе к ИМ необходимо указывать ваши логин и пароль в HTTP-заголовке Authorization. Значение заголовка можно сформировать, например, так:

$ echo -n 'ВАШ_ЛОГИН:ВАШ_ПАРОЛЬ' | base64 -

На выходе должна получиться строка вида Z3B0YXNoa286cGFzc3dvcmQ=. Далее заголовок используется в таком виде:

Authorization:Basic Z3B0YXNoa286cGFzc3dvcmQ=

1.2. Общие принципы запросов

1.2.1. Write-запросы

Write-запросы используются для создания и редактирования объектов в базе ИМ. Write-запросы — это обычные GET- или POST-запросы. На вход такие запросы принимают параметры либо через query string, либо через указание param=value в теле POST-запроса. Ответ на такие запросы - это JSON, содержащий либо общие ошибки, либо объект данных с указанием ошибок в конкретных полях, либо объект данных.

При write-запросах необходимо указывать все обязательные поля, а также все заполненные изменяемые поля. Иначе поле, для которого не было указано значение, но оно заполнено в базе ИМ будет затерто пустым значением.
Также при write-запросах в ответ всегда возвращается наиболее полная информация о редактируемом объекте. То есть, если редактируется объект без указания необязательных полей, то в ответе все равно будут содержаться эти поля, но с пустыми значениями.
Общие параметры

При каждом программном HTTP-запросе необходимо всегда указывать 3 обязательных параметры и один параметр, обязательный при определенных запросах.

  1. fid — значение этого параметра зависит от конкретного запроса, например, fid=101713762162;

  2. __api — значение этого параметра всегда должно быть равным 2: __api=2;

  3. __act — значение этого параметра всегда должно быть равным send или q, например, __act=send;

  4. __task — значение этого параметра зависит от конкретного запроса, например, __task=add. Этот параметр не всегда обязательный.

Заполнение полей

Следует обратить внимание, что при посыле программных HTTP-запросов необходимо кодировать значения полей в URI encoding. Например, при запросе на создание карточки товара с использованием curl значение параметров нужно указывать с использованием ключа --data-urlencode, а не -d. Пример, смотреть в Создание карточки продукции.

Ошибки при write-запросах

При создании или редактировании объектов могут возникнуть ошибки. Например, поле, указанное, как обязательное не будет передано в write-запросе.

Общие ошибки

Общие ошибки могут возникнуть до проверки указанных в write-запросе полей. Поэтому ответный JSON будет содержать только код общей ошибки и текстовый комментарий.

Пример общей ошибки:

{
  "errors": [
    {
      "1107": [
        "100212209492"
      ]
    }
  ]
}

Здесь 1107 — код ошибки, а 100212209492 — комментарий к ошибке. Если комментария к ошибке не предполагается, то вместо объекта в массиве errors будет содердаться числовой код ошибки.

Коды общих ошибок можно посмотреть в Коды и описания общих ошибок
Ошибки валидации полей

При ошибке валидации поля в ответном JSON для данного поля будет возвращено указанное значение и текст ошибки валидации.

Пример ошибки валидации поля:

...

  "f_1002110007": {
    "e": "Книга с таким штрихкодом уже существует. ",
    "v": "9785950095704"
  },

...

Здесь видно, что при создании товара указанный штрихкод уже существует в базе ИМ. В данном случае для поля f_1002110007 в поле e содержится текст ошибки валидации, а в в поле v указано значение, которое было отправлено при запросе.

1.2.2. Read-запросы

Чтение объекта из базы ИМ может осуществляеться при помощи простого GET-запроса по id объекта. Ответ на такой запрос - это JSON с полями объекта. Обязательными параметрами такого запроса являются следующие:

  1. fid — значение этого параметра зависит от конкретного запроса, например, fid=101713762162;

  2. __act — значение этого параметра всегда должно быть равным send: __act=send;

  3. __api — значение этого параметра всегда должно быть равным 2: __api=2.

Пример read-запроса:

$ curl -s -X GET \
-H 'Authorization:Basic AuthString' \
'https://www.bgoperator.ru/bgmarket/forms?fid=101713597138&act=send&__api=2'

Ответ:

{
  "f_ci_row_num_100610024200": {
    "v": "1"
  },
  "f_1006210028_100610024200": {
    "v": "2"
  },
  "f_1006110005_100610024200": {
    "v": "00005"
  },
  "f_1006910006_100610024200": {
    "v": "100212662269"
  },
  "f_1006210013_100610024200": {
    "v": "333"
  },
  "f_1006210008_100610024200": {
    "v": "10"
  },
  "f_ci_row_num_100610024100": {
    "v": "2"
  },
  "f_1006210028_100610024100": {
    "v": "2"
  },
  "f_1006110005_100610024100": {
    "v": "00004"
  },
  "f_1006910006_100610024100": {
    "v": "100212662267"
  },
  "f_1006210013_100610024100": {
    "v": "222"
  },

...

}

1.2.3. Read-запросы на основе GraphQL

Поиск и чтение объектов из базы ИМ может осуществляеться при помощи языка запросов GraphQL. Это обычный POST-запрос с заголовком запроса:

Content-Type:application/json

Тело такого запроса — это JSON с двумя полями: query и variables. Ответ на такой запрос - это опять же JSON. Конкретные запросы и ответы описаны ниже.

Пример запроса получения некоторых атрибутов товара по заданному id товара:

query {
  meta {
    t_2(id:100212209241) {
      name
      author
      isbn_
    }
  }
}

И ответ на такой запрос:

{
  "data": {
    "meta": {
      "t_2": {
        "name": "Основные загрязнители и здоровье человека",
        "author": "Надежкина Е.В., Надежкина Е.С., Тушавина О.В., Хуснетдинова К.А., Молодова О.В.",
        "isbn_": [
          "978-5-4316-0369-3"
        ]
      }
    }
  }
}

2. Поставщику

2.1. Создание карточки продукции

Write-запрос.

Общее название объектов продукции в базе ИМ — t_2.

После создания карточки продукции, она появится в списке Ваш кабинет  Карточки продукции.

Поля продукции ISBN и EAN13 (штрихкод) могут содержать несколько значений. Однако текущая версия Shop API не позволяет добавлять несколько значений к существующемим значениям поля за один вызов API. Добавить несколько значений возможно лишь передавая одно значение за один вызов API. Пример добавления новых ISBN и EAN13 в существуюшую карточку продукции смотреть в Редактирование карточки продукции.

2.1.1. Обязательные поля

Атрибут Требования к заполнению Write-название Read-название

Название (основное заглавие)

f_1002110000

name

Автор

f_1002410001

author

ISBN

Корректный ISBN. Уникальный ISBN. Если в базе будет найдена книга с указанным ISBN, то новый объект не будет создан и запрос вернет ошибку валидации.

Поле может содержать несколько значений. В этом случае в ответном JSON значение будет массивом строк.

f_1002110006

isbn_

Штрихкод

Штрихкод должен состоять из 13 цифр. Уникальный штрихкод. Если в базе будет найдена книга с указанным штрихкодом, то новый объект не будет создан и запрос вернет ошибку валидации.

Поле может содержать несколько значений. В этом случае в ответном JSON значение будет массивом строк.

f_1002110007

ean_13

Тираж

Целое число больше нуля.

f_1002110011

edition

Количество страниц

Целое число больше нуля.

f_1002410018

pages

Год издания

Целое число больше нуля.

f_1002410019

publishyear

Вид переплета

Одна из двух строк: "в обл." или "в пер."

f_1002410004

cover

Возрастная категория

Одна из строк "0", "6", "12", "16", "18".

f_1002410015

age_category

Место издания

f_1002110013

city

Вес в гр.

Целое число больше нуля.

f_1002210000

weight

Описание полное (аннотация)

f_1002110018

text_full

2.1.2. Остальные необязательные поля

Атрибут Требования к заполнению Write-название Read-название

УДК

f_1002110016

udc

Серия

f_1002410003

series

Ширина в см.

Дробное число, разделитель точка ".". Максимум 4 разряда после точки.

f_1002210002

width

Толщина в см.

Дробное число, разделитель точка ".". Максимум 4 разряда после точки.

f_1002210004

thickness

Высота в см.

Дробное число, разделитель точка ".". Максимум 4 разряда после точки.

f_1002210001

height

Первые сведения об ответственности

f_1002110010

contributorstatement

Редактор

f_1002410010

editor

Составитель

f_1002410012

compiler

Переводчик

f_1002410011

translator

Художник

f_1002410013

illustrator

Сведения об издании

f_1002110017

text

2.1.3. Запрос

$ curl -s -X POST \
-H 'Authorization:Basic AuthString' \
--data-urlencode 'f_1002410001=Автор' \
--data-urlencode 'f_1002110000=Название' \
--data-urlencode 'f_1002110006=978-5-9500957-0-4' \
--data-urlencode 'f_1002110007=9785950095704' \
--data-urlencode 'f_1002110011=1000' \
--data-urlencode 'f_1002410018=100' \
--data-urlencode 'f_1002410019=2017' \
--data-urlencode 'f_1002410004=в обл.' \
--data-urlencode 'f_1002410015=0' \
--data-urlencode 'f_1002110013=Москва' \
--data-urlencode 'f_1002210000=500' \
--data-urlencode 'f_1002110018=<p>Описание <b>полное</b></p>' \
-d 'fid=101713762162' \
-d '__act=send' \
-d '__task=add' \
-d '__api=2' \
'https://www.bgoperator.ru/bgmarket/forms'

2.1.4. Ответ

{
  "f_id": {
    "v": "100212662274"
  },
  "f_1002410001": {
    "v": "Автор"
  },
  "f_1002110000": {
    "v": "Название"
  },
  "f_1002110006": {
    "v": "978-5-9500957-0-4"
  },
  "f_1002110016": {
    "v": ""
  },
  "f_1002110007": {
    "v": "9785950095704"
  },
  "f_1002110011": {
    "v": "1000"
  },
  "f_1002410018": {
    "v": "100"
  },
  "f_1002410019": {
    "v": "2017"
  },
  "f_1002410004": {
    "v": "в обл."
  },
  "f_1002410003": {
    "v": ""
  },
  "f_1002410015": {
    "v": "0"
  },
  "f_1002110013": {
    "v": "Москва"
  },
  "f_1002210000": {
    "v": "500"
  },
  "f_1002210002": {
    "v": ""
  },
  "f_1002210004": {
    "v": ""
  },
  "f_1002210001": {
    "v": ""
  },
  "f_1002110010": {
    "v": ""
  },
  "f_1002410010": {
    "v": ""
  },
  "f_1002410012": {
    "v": ""
  },
  "f_1002410011": {
    "v": ""
  },
  "f_1002410013": {
    "v": ""
  },
  "f_1002110017": {
    "v": ""
  },
  "f_1002110018": {
    "v": "<p>Описание <b>полное<\\/b><\\/p>"
  }
}

2.2. Поиск товаров в базе ИМ

Read-запрос на основе GraphQL.

Продукцию можно искать по разным атрибутам. Далее приводится пример поиска по ISBN.

2.2.1. GraphQL Запрос

query ($cond: [Condition]!) {
  meta {
    getSrcObs(typeName: t_2, first: 10, conditions:$cond) {
      edges {
        node {
          ... on t_2 {
            id
            name
            author
            isbn_
            ean_13
            edition
            publishyear
            cover
            age_category
            city
            weight
            text
            subtitle
            text_full
            udc
            series
            width
            thickness
            height
            contributorstatement
            editor
            compiler
            translator
            illustrator
            coverimage
          }
        }
      }
    }
  }
}

Переменные запроса:

{
  "cond": [{
    "attr": "isbn_",
    "ct": "EQ",
    "val": "978-5-9500957-0-1"
  }]
}

2.2.2. curl запрос

$ curl -s -XPOST \
-H 'Content-Type:application/json' \
-H 'Authorization:Basic AuthString' \
'https://www.bgoperator.ru/bgmarket/forms?fid=101713843141&__act=q' -s -d '
{
  "query": "query ($cond: [Condition]!) { meta { getSrcObs(typeName: t_2, first: 10 conditions:$cond) { edges { node { ... on t_2 { id name author isbn_ ean_13 edition publishyear cover age_category city weight text subtitle text_full udc series width thickness height contributorstatement editor compiler translator illustrator } } } } } }",
  "variables": {
    "cond": [{
      "attr": "isbn_",
      "ct": "EQ",
      "val": "978-5-9500957-0-1"
    }]
  }
}'

2.2.3. Ответ

{
  "data": {
    "meta": {
      "getSrcObs": {
        "edges": [
          {
            "node": {
              "id": "100212662267",
              "name": "Такое-то название",
              "author": "Автор изменение",
              "isbn_": [
                "978-5-9500957-0-1"
              ],
              "ean_13": [
                "9785950095701"
              ],
              "edition": "1000",
              "publishyear": "2017",
              "cover": "в обл.",
              "age_category": "0",
              "city": "Москва",
              "weight": 500,
              "text": null,
              "subtitle": null,
              "text_full": "<p>Описание <b>ПОЛНОЕ</b></p>",
              "udc": null,
              "series": null,
              "width": null,
              "thickness": null,
              "height": null,
              "contributorstatement": null,
              "editor": null,
              "compiler": null,
              "translator": null,
              "illustrator": null,
              "coverimage": [
                "1002110015/20180205/44855806/noun_63037_cc-3.png"
              ]
            }
          }
        ]
      }
    }
  }
}

2.3. Редактирование карточки продукции

Write-запрос.

В данном запросе необходимо указать id продукции в базе ИМ. Данный запрос отличается от запроса на создание карточки товара как раз тем, что дополнительными параметрами здесь являются id и __task.

2.3.1. Запрос

$ curl -s -X POST \
-H 'Authorization:Basic AuthString' \
--data-urlencode 'f_1002410001=Отредатированнй автор' \
--data-urlencode 'f_1002110000=Оредактированное название' \
--data-urlencode 'f_1002110006=978-5-9500957-0-3' \
--data-urlencode 'f_1002110007=9785950095703' \
--data-urlencode 'f_1002110011=1000' \
--data-urlencode 'f_1002410018=100' \
--data-urlencode 'f_1002410019=2017' \
--data-urlencode 'f_1002410004=в обл.' \
--data-urlencode 'f_1002410015=0' \
--data-urlencode 'f_1002110013=Москва' \
--data-urlencode 'f_1002210000=500' \
--data-urlencode 'f_1002110018=<p>Описание <b>полное</b></p>' \
-d 'id=100212662274' \
-d 'fid=101713762162' \
-d '__act=send' \
-d '__task=edit' \
-d '__api=2' \
'https://www.bgoperator.ru/bgmarket/forms'

2.3.2. Ответ

{
  "f_id": {
    "v": "100212662274"
  },
  "f_1002410001": {
    "v": "Отредатированнй автор"
  },
  "f_1002110000": {
    "v": "Оредактированное название"
  },
  "f_1002110006": {
    "v": [
      "978-5-9500957-0-4",
      "978-5-9500957-0-3"
    ]
  },
  "f_1002110016": {
    "v": ""
  },
  "f_1002110007": {
    "v": [
      "9785950095704",
      "9785950095703"
    ]
  },
  "f_1002110011": {
    "v": "1000"
  },
  "f_1002410018": {
    "v": "100"
  },
  "f_1002410019": {
    "v": "2017"
  },
  "f_1002410004": {
    "v": "в обл."
  },
  "f_1002410003": {
    "v": ""
  },
  "f_1002410015": {
    "v": "0"
  },
  "f_1002110013": {
    "v": "Москва"
  },
  "f_1002210000": {
    "v": "500"
  },
  "f_1002210002": {
    "v": ""
  },
  "f_1002210004": {
    "v": ""
  },
  "f_1002210001": {
    "v": ""
  },
  "f_1002110010": {
    "v": ""
  },
  "f_1002410010": {
    "v": ""
  },
  "f_1002410012": {
    "v": ""
  },
  "f_1002410011": {
    "v": ""
  },
  "f_1002410013": {
    "v": ""
  },
  "f_1002110017": {
    "v": ""
  },
  "f_1002110018": {
    "v": "<p>Описание <b>полное<\\/b><\\/p>"
  }
}

2.4. Загрузка изображения к карточке продукции

Данный запрос является отдельным запросом из-за загрузки файла. Однако, запрос все равно возвращает JSON. В качестве параметра здесь выступает параметр idOb в query string URL-а запроса. Его значением должен быть id продукции.

2.4.1. Запрос

$ curl -s -X POST \
-H 'Authorization:Basic AuthString' \
-F 'fl=@/full/path/to/image.png' \
'https://www.bgoperator.ru/bgmarket/uploadutil?idOb=100212662267&idAt=1002110015&gmode=4&add=0&translit=1'

2.4.2. Ответ

{
  "success": true,
  "file": "1002110015/20180207/05522627/image.png#0#0#0"
}

2.5. Создание записей в прайсе

Write-запрос.

Прайс - это набор записей, каждая из которых содержит продукцию, цену поставщика за единицу продукции и ставку НДС. На сайте поставщик может просматривать и редактирвоать свое предложение на странице Ваш кабинет  Ваше предложение (загрузка прайса). Если запись активная, то ИМ может заказать у поставщика данную позицию. В прайсе можно менять все атрибуты: цену, ставку НДС, активность. Позиии прайса также можно удалять совсем.

В прайсе можно создавать несколько записей за один запрос. Но во избежание долгих ответов следует ограничиться максимум 100 записей на один запрос.

При создании записей в прайсе наименования параметров для каждой записи формируются из постоянной и переменной частей. Переменная часть - это строка вида $id<номер позиции прайса в запросе>. Далее в таблице для простоты чтения приводится описание параметров с переменной частью $id1.

Атрибут Требования к заполнению Write-название Read-название

Признак активности записи

"2" - запись активна. "1" - запись неактивна.

f_1006210028_$id1

is_active_record

Артикул поставщика

Обязательное для заполнение поле. Должно быть уникально в пределах всего прайса поставщика.

Данное поле не может быть изменено у существующей записи. Задать значение записи можно только при создании записи.

f_1006110005_$id1

recordreference_

id продукции в базе ИМ

Обязательное поле. Должен быть указан id существующей в базе ИМ продукции

Данное поле не может быть изменено у существующей записи. Задать значение записи можно только при создании записи.

f_1006910006_$id1

item

Цена поставщика

Дробное число, разделитель точка ".". Максимум 2 разряда после точки.

f_1006210013_$id1

buy_price

Ставка НДС

Если поствщик применяет ОСН, то одна из строк "0", "10" или "18". Если поставщик применяет УСН, то пусто.

f_1006210008_$id1

vat

Признак добаления записи

Всегда "1".

f_companyitem_$id1_add

Поле указания параметров для всех добавляемых в прайс записей нужно добавить еще один параметр значение которого - это строка из всех переменных частей записей, разделенных символом ";". Например, для двух записей это будет так: f_companyitem=$id1;$id2.

В ответе переменная часть заменяется на id созданной записи в прайсе.

Стоит также обратить внимание на два параметра запроса: f_companyitem_m и f_companyitem_entr. При запросе на создание записей в прайсе значение параметра f_companyitem_m следует всегда указывать 0. А значение параметра f_companyitem_entr должно быть равно количеству создаваемых записей.

Далее приводится запрос на создание двух записей в прайсе.

2.5.1. Запрос

$ curl -s -X POST \
-H 'Authorization:Basic AuthString' \
--data-urlencode 'f_1006210028_$id1=2' \
--data-urlencode 'f_1006110005_$id1=00004' \
--data-urlencode 'f_1006910006_$id1=100212662267' \
--data-urlencode 'f_1006210013_$id1=222' \
--data-urlencode 'f_1006210008_$id1=10' \
--data-urlencode 'f_companyitem_$id1_add=1' \
--data-urlencode 'f_1006210028_$id2=2' \
--data-urlencode 'f_1006110005_$id2=00005' \
--data-urlencode 'f_1006910006_$id2=100212662269' \
--data-urlencode 'f_1006210013_$id2=333' \
--data-urlencode 'f_1006210008_$id2=10' \
--data-urlencode 'f_companyitem_$id2_add=1' \
--data-urlencode 'f_companyitem=$id1;$id2' \
--data-urlencode 'f_companyitem_m=0' \
--data-urlencode 'f_companyitem_entr=2' \
-d 'fid=101713597138' \
-d '__act=send' \
-d '__task=edit' \
-d '__api=2' \
'https://www.bgoperator.ru/bgmarket/forms'

2.5.2. Ответ

{
  "f_ci_row_num_100610024200": {
    "v": "1"
  },
  "f_1006210028_100610024200": {
    "v": "2"
  },
  "f_1006110005_100610024200": {
    "v": "00005"
  },
  "f_1006910006_100610024200": {
    "v": "100212662269"
  },
  "f_1006210013_100610024200": {
    "v": "333"
  },
  "f_1006210008_100610024200": {
    "v": "10"
  },
  "f_ci_row_num_100610024100": {
    "v": "2"
  },
  "f_1006210028_100610024100": {
    "v": "2"
  },
  "f_1006110005_100610024100": {
    "v": "00004"
  },
  "f_1006910006_100610024100": {
    "v": "100212662267"
  },
  "f_1006210013_100610024100": {
    "v": "222"
  },
  "f_1006210008_100610024100": {
    "v": "10"
  },
  "f_ci_row_num_$id": {
    "v": "3"
  },
  "f_1006210028_$id": {
    "v": ""
  },
  "f_1006110005_$id": {
    "v": ""
  },
  "f_1006910006_$id": {
    "v": ""
  },
  "f_1006210013_$id": {
    "v": ""
  },
  "f_1006210008_$id": {
    "v": ""
  },
  "f_companyitem": {
    "v": "100610024200;100610024100;$id"
  }
}

2.6. Редактирование записей в прайсе

Write-запрос. Для подготовки данных используется read-запрос.

Чтобы отредактировать записи в прайс-листе необходимо сначала узнать их порядковые номера. Для этого сначала нужно прочитать прайс обычным read-запросом, найти нужные позиции, запомнить их id и порядковые номера.

Далее приводим запрос, редактирующий две позиции прайса, находящиеся на 10 и 11 позиции.

2.6.1. Read-запрос для чтения полного прайса

$ curl -s -X GET \
-H 'Authorization:Basic AuthString' \
'https://www.bgoperator.ru/bgmarket/forms?fid=101713597138&act=send&__api=2'

Ответ

...

  "f_ci_row_num_100610010000": {
    "v": "10"
  },
  "f_1006210028_100610010000": {
    "v": "2"
  },
  "f_1006110005_100610010000": {
    "v": "000011170"
  },
  "f_1006910006_100610010000": {
    "v": "100212208545"
  },
  "f_1006210013_100610010000": {
    "v": "1222"
  },
  "f_1006210008_100610010000": {
    "v": "10"
  },
  "f_ci_row_num_100610008000": {
    "v": "11"
  },
  "f_1006210028_100610008000": {
    "v": "2"
  },
  "f_1006110005_100610008000": {
    "v": "00002"
  },
  "f_1006910006_100610008000": {
    "v": "100212194663"
  },
  "f_1006210013_100610008000": {
    "v": "200"
  },
  "f_1006210008_100610008000": {
    "v": "18"
  },

...

Здесь видно, что в ответном JSON записи прайса идут последовательно. Каждая запись начинается с объекта вида f_ci_row_num_100610010000. Здесь 100610010000 — это id записи прайса. А поле v внутри объекта f_ci_row_num_100610010000 — порядковый номер записи в прайсе. Теперь можно переходить к редактированию выбранных записей.

2.6.2. Write-запрос редактирования записей прайса

$ curl -s -X POST \
-H 'Authorization:Basic AuthString' \
--data-urlencode 'f_1006210028_100610010000=2' \
--data-urlencode 'f_1006210013_100610010000=2000' \
--data-urlencode 'f_1006210008_100610010000=18' \
--data-urlencode 'f_1006210028_100610008000=2' \
--data-urlencode 'f_1006210013_100610008000=3000' \
--data-urlencode 'f_1006210008_100610008000=18' \
--data-urlencode 'f_companyitem=100610010000;100610008000' \
--data-urlencode 'f_companyitem_m=9' \
--data-urlencode 'f_companyitem_entr=2' \
-d 'fid=101713597138' \
-d '__act=send' \
-d '__task=edit' \
-d '__api=2' \
'https://www.bgoperator.ru/bgmarket/forms'

Заполнение параметров здесь осуществляется по тем же правилам, что описаны в Редактирование записей в прайсе.

Интерес запроса представляют параметры f_companyitem_m=9 и f_companyitem_entr=2. Их значения задаются следующим образом:

  1. Значение f_companyitem_m должно равняться минимальному порядковому номеру редактируемых записей минус 1;

  2. Значение f_companyitem_entr должно равняться количеству редактируемых записей в прайсе.

2.6.3. Ответ

{
  "f_ci_row_num_100610008000": {
    "v": "1"
  },
  "f_1006210028_100610008000": {
    "v": "2"
  },
  "f_1006110005_100610008000": {
    "v": "00002"
  },
  "f_1006910006_100610008000": {
    "v": "100212194663"
  },
  "f_1006210013_100610008000": {
    "v": "3000"
  },
  "f_1006210008_100610008000": {
    "v": "18"
  },
  "f_ci_row_num_100612209288": {
    "v": "2"
  },
  "f_1006210028_100612209288": {
    "v": "2"
  },
  "f_1006110005_100612209288": {
    "v": "5005"
  },
  "f_1006910006_100612209288": {
    "v": "100210392677"
  },
  "f_1006210013_100612209288": {
    "v": "100"
  },
  "f_1006210008_100612209288": {
    "v": "0"
  },
  "f_ci_row_num_$id": {
    "v": "3"
  },
  "f_1006210028_$id": {
    "v": ""
  },
  "f_1006110005_$id": {
    "v": ""
  },
  "f_1006910006_$id": {
    "v": ""
  },
  "f_1006210013_$id": {
    "v": ""
  },
  "f_1006210008_$id": {
    "v": ""
  },
  "f_companyitem": {
    "v": "100610008000;100612209288;$id"
  }
}

В ответе можно не обращать внимание на объекты вида f_ci_row_num_*. Они содержут порядковые номера отредактированных записей в пределах этого ответа.

2.7. Выгрузка заказа поставщику

Заказ поставщику формируется в базе ИМ. Уведомление об этом рассылается на почту, выданную при регистрации поставщика. У каждого заказа есть id. Имея такой id заказ можно читать и изменять программно, используя логин и пароль поставщика. Читать заказ можно двумя способами. Через read-запрос на основе GraphQL и через обычный read-запрос. Запрос на основе GraphQL отличается от обычного read-запроса помимо формата ответа тем, что в GraphQL запросе можно указать только требуемые для ситуации поля заказа. И еще одно отличие состоит в том, что GraphQL запрос и ответ представляют более удобную для чтения человеком структуру. Так же, как и с прайсом write-запрос на изменение заказа подгтавливается при помощи данных, полученных из обычного read-запроса.

Заказ поставщику состоит из шапки и позиций заказа. Общее название объектов заказов в базе ИМ -- t_8. Общее название объектов позиций заказов в базе ИМ -- t_9.

2.7.1. Поля шапки заказа

Атрибут Требования к заполнению Write-название Read-название

Статус заказа

Обязательное для заполнение поле. Значение — число 1, 2, 4, 6 или 9.

  • "1" - Подбор,

  • "2" - Отправлен поставщику,

  • "4" - Уточнен поставщиком,

  • "6" - Согласован,

  • "9" - Принят на склад.

f_1008210044

order_starus

Сумма заказа

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

f_1008210023

amount

id поставщика в базе ИМ

Значение данного поля не может быть изменено. В шапке заказа данное поле приводится для информации.

f_1008910018

supplier.id

id покупателя в базе ИМ

Значение данного поля не может быть изменено. В шапке заказа данное поле приводится для информации.

f_1008910031

buyer_org.id

Список id позиций заказа (см. Поля позиции заказа)

Значение данного поля — это строка, состоящая из id позиций заказа, разделенных через симво ";". Значение данного поля не стоит менять, если редактируется заказ, состав позиций которого не нужно менять. Другими словами при write-запросе это поле нужно передавать как есть, без изменений.

f_orderitem

2.7.2. Поля позиции заказа

Названия полей позиции заказа формируются из постоянной и переменной частей. Переменная часть - это строка вида <id позиции заказа в заказе>. Далее в таблице для простоты чтения приводится описание параметров с переменной частью $id1 (в рабочем режиме переменная часть может выглядеть, например так: 100918030111826101).

Атрибут Требования к заполнению Write-название Read-название

id продукции в базе ИМ

Значение данного поля не может быть изменено. В позиции заказа данное поле приводится для информации.

f_1009910006_$id1

item.id

Цена продукции

Значение данного поля не может быть изменено. В позиции заказа данное поле приводится для информации.

f_1009210015_$id1

price

Количество

Обязательное для заполнение поле. Целое число больше нуля.

Количество может быть изменено только в меньшую стороны. При попытке изменения количества в большую сторону будет выдана ошибка с кодом 1125.

f_1009210025_$id1

quantity

Сумма позиции заказа

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

f_1009210023_$id1

amount

2.7.3. GraphQL Запрос

В GraphQL запросе позиции заказа объединяются в поле bind_t_9_order, которое содержит поле edges, которое в свою очередь содержит массив объектов. Каждый объект в этом массиве содержит поля конкретной позиции заказа.

query ($orderId:ID!) {
  meta {
    t_8(id:$orderId) {
      dataN
      supplier {
        id
        inn
      }
      buyer_org {
        id
        inn
      }
      order_starus
      amount
      bind_t_9_order(first:1000) {
        edges {
          node {
            ... on t_9 {
              id
              item {
                id
              }
              price
              quantity
              order_item_status
            }
          }
        }
      }
    }
  }
}

Переменные запроса:

{
  "orderId": "100818030111790008"
}
curl запрос
$ curl -s -XPOST \
-H 'Content-Type:application/json' \
-H 'Authorization:Basic AuthString' \
'https://www.bgoperator.ru/bgmarket/forms?fid=101713704459&__act=q' -s -d '
{
  "query": "query ($orderId:ID!) { meta { t_8(id:$orderId) { dataN supplier {
  id inn } buyer_org { id inn } order_starus amount bind_t_9_order(first:1000) {
  edges { node { id ... on t_9 { item { id } price quantity order_item_status } } } } } } }",
  "variables": {
    "orderId": "100818030111790008"
  }
}'
Ответ
{
  "data": {
    "meta": {
      "t_8": {
        "dataN": "20.03.2018 10:52:13",
        "supplier": {
          "id": "100112114676",
          "inn": "7707353941"
        },
        "buyer_org": {
          "id": "100110735986",
          "inn": "7701023055"
        },
        "order_starus": 1,
        "amount": 3080,
        "bind_t_9_order": {
          "edges": [
            {
              "node": {
                "id": "100918030111790108",
                "item": {
                  "id": "100213751958"
                },
                "price": 440,
                "quantity": 7,
                "order_item_status": 1
              }
            }
          ]
        }
      }
    }
  }
}

2.8. Read-запрос

Здесь в параметрах query string в качестве значения обоих параметров — prx и id — нужно указать id заказа.

$ curl -s -X GET \
-H 'Authorization:Basic AuthString' \
'https://www.bgoperator.ru/bgmarket/forms?prx=100818030111826001&id=100818030111826001&fid=101713704459&act=send&__api=2'

2.8.1. Ответ

{
  "f_1008210044": {
    "v": "2"
  },
  "f_1008910018": {
    "v": "100113752451"
  },
  "f_1008910031": {
    "v": "100112114676"
  },
  "f_1009910006_100918030111826101": {
    "v": "100213751958"
  },
  "f_1009210015_100918030111826101": {
    "v": "472"
  },
  "f_1009210025_100918030111826101": {
    "v": "19"
  },
  "f_1009210023_100918030111826101": {
    "v": "8968.0"
  },
  "f_orderitem": {
    "v": "100918030111826101"
  },
  "f_1008210023": {
    "v": "8968"
  }
}

2.9. Редактирование заказа поставщику

Write-запрос.

В write-запросе на изменение заказа поставщику можно указывать только те поля, которые можно изменять (см. Поля шапки заказа и Поля позиции заказа). На данный момент это только количество позиции заказа и статус заказа. Статус можно менять только с 2 на 4.

Также, параметром данного write-запроса является id заказа, который указывается в двух местах: поле id тела запроса и поле prx в query string URL-а запроса.

2.9.1. Запрос

$ curl -s -X POST \
-H 'Authorization:Basic AuthString' \
--data-urlencode 'f_1008210044=2' \
--data-urlencode 'f_1009210025_100918030111826101=17' \
--data-urlencode 'f_orderitem=100918030111826101' \
-d 'id=100818030111826001' \
-d 'fid=101713704459' \
-d '__act=send' \
-d '__task=edit' \
-d '__api=2' \
'https://www.bgoperator.ru/bgmarket/forms?prx=100818030111826001'

2.9.2. Ответ

Как и описано в Write-запросы в ответ приходит наиболее полная информация о заказе, не смотря на то, что в запросе были указаны не все поля.

{
  "f_1008210044": {
    "v": "2"
  },
  "f_1008910018": {
    "v": "100113752451"
  },
  "f_1008910031": {
    "v": "100112114676"
  },
  "f_1009910006_100918030111826101": {
    "v": "100213751958"
  },
  "f_1009210015_100918030111826101": {
    "v": "472"
  },
  "f_1009210025_100918030111826101": {
    "v": "17"
  },
  "f_1009210023_100918030111826101": {
    "v": "8024.0"
  },
  "f_orderitem": {
    "v": "100918030111826101"
  },
  "f_1008210023": {
    "v": "8024.0"
  }
}

3. Покупателю

3.1. Чтение оптового прайса

Read-запрос на основе GraphQL.

3.1.1. GraphQL Запрос

query {
  meta {
    getSrcObs(typeName: t_6, first: 100) {
      edges {
        node {
          ... on t_6 {
            item {
              id
              name
              author
              isbn_
              ean_13
              edition
              publishyear
              cover
              age_category
              city
              weight
              text
              subtitle
              text_full
              udc
              series
              width
              thickness
              height
              contributorstatement
              editor
              compiler
              translator
              illustrator
              coverimage
              storage_rest
            }
            wholesale_price
            vat
          }
        }
      }
    }
  }
}

Переменные запроса:

{}

3.1.2. curl запрос

$ curl -s -XPOST \
-H 'Content-Type:application/json' \
-H 'Authorization:Basic AuthString' \
'https://www.bgoperator.ru/bgmarket/forms?fid=101713757195&__act=q' -s -d '
{
  "query": "query { meta { getSrcObs(typeName: t_6, first: 100) { edges { node { ... on t_6 { item { id name author isbn_ ean_13 edition publishyear cover age_category city weight text subtitle text_full udc series width thickness height contributorstatement editor compiler translator illustrator coverimage storage_rest} wholesale_price vat} } } } } }",
  "variables": {}
}'

3.1.3. Ответ

{
  "data": {
    "meta": {
      "getSrcObs": {
        "edges": [
          {
            "node": {
              "item": {
                "id": "100213751958",
                "name": "Роботы работают",
                "author": "Антонов И. К., Зарудняк М. С.",
                "isbn_": [
                  "978-5-9500957-0-2"
                ],
                "ean_13": [
                  "9785950095702"
                ],
                "edition": "500",
                "publishyear": "2017",
                "cover": null,
                "age_category": "в обл.",
                "city": "Москва",
                "weight": 300,
                "text": "<p></p>",
                "subtitle": null,
                "text_full": "<p><span>В этой книге описана история автоматизации туристического оператора \"Библио-Глобус\". Сформулированы принципы, которые позволили стать компании крупнейшей на конкурентном рынке и удерживать позиции при всех перипетиях последних лет. Не предлагая универсальных решений, авторы описывают проверенные собственной практикой подходы к организации работы ИТ-отдела максимально эффективным образом.</span></p>",
                "udc": "004.9:379.85",
                "series": null,
                "width": 16,
                "thickness": 1,
                "height": 22,
                "contributorstatement": null,
                "editor": null,
                "compiler": null,
                "translator": null,
                "illustrator": null,
                "coverimage": [
                  "1002110015/20180110/74291065/978-5-9500957-0-2.png"
                ],
                "storage_rest": 16.0,
              },
              "wholesale_price": 400,
              "vat": null
            }
          }
        ]
      }
    }
  }
}

3.2. Создание заказа

Секция в работе

3.3. Чтение заказа

Секция в работе

4. Коды и описания общих ошибок

Секция в работе