Создание заказа покупателя через API
Данная статья посвящена обмену данными с системой Mr.Doc через REST API интерфейс на примере создания заказа покупателя.
Содержание
Доступ к API
Перед выполнением операций с системой через API необходимо настроить права доступа для учетной записи, от которой будут производиться запросы. Подробнее об этом можно прочитать в разделе Настройка доступа к API.
Структура запроса
Создание заказа осуществляется посредством PUT-запроса на один из адресов:
- https://company_name.mrdoc.org/api/1/DocSaleOrder.json
- https://company_name.mrdoc.org/api/1/DocSaleOrder.xml
в зависимости от того, в каком формате будет производиться обмен (JSON или XML соответственно). В теле запроса должна содержаться информация о новом документе в выбранном формате.
Пример JSON
<syntaxhighlight lang=javascript> {
"date_time": "2014-01-01 12:00:00",
"number": "SF-00001",
"status_id": "Черновик",
"organization_id": 1,
"contractor_id": 50,
"contract_id": 55,
"currency_id": 1,
"price_type_id": 2,
"is_price_include_vat": false,
"external_number": "SF-00001",
"products": [
{
"product_id": 113,
"sku_id": 145,
"unit_id": 113,
"factor": 1,
"quantity": 8,
"price": 250,
"sum": 2000,
"vat_rate_id": "БезНДС",
"vat_sum": 0
},
{
"product_id": 245,
"sku_id": 645,
"unit_id": 245,
"factor": 1,
"quantity": 1,
"price": 540,
"sum": 540,
"vat_rate_id": "БезНДС",
"vat_sum": 0
}
],
"services": [
{
"service_id": 5,
"sku_id": 5,
"unit_id": 5,
"factor": 1,
"quantity": 1,
"price": 550,
"sum": 550,
"vat_rate_id": "БезНДС",
"vat_sum": 0,
"execution_address_id": 198,
"execution_date_time": "2014-01-05 16:30:00"
}
]
} </syntaxhighlight>
Пример XML
<syntaxhighlight lang=xml> <?xml version="1.0" encoding="utf-8"?> <root>
<date_time>2014-01-01 12:00:00</date_time>
<number>SF-00001</number>
<status_id>Черновик</status_id>
<organization_id>1</organization_id>
<contractor_id>50</contractor_id>
<contract_id>55</contract_id>
<currency_id>1</currency_id>
<price_type_id>2</price_type_id>
<is_price_include_vat>0</is_price_include_vat>
<external_number>SF-00001</external_number>
<products list="true">
<item>
<product_id>113</product_id>
<sku_id>145</sku_id>
<unit_id>113</unit_id>
<factor>1</factor>
<quantity>8</quantity>
<price>250</price>
<sum>2000</sum>
<vat_rate_id>БезНДС</vat_rate_id>
<vat_sum>0</vat_sum>
</item>
<item>
<product_id>245</product_id>
<sku_id>645</sku_id>
<unit_id>245</unit_id>
<factor>1</factor>
<quantity>1</quantity>
<price>540</price>
<sum>540</sum>
<vat_rate_id>БезНДС</vat_rate_id>
<vat_sum>0</vat_sum>
</item>
</products>
<services list="true">
<item>
<service_id>5</service_id>
<sku_id>5</sku_id>
<unit_id>5</unit_id>
<factor>1</factor>
<quantity>1</quantity>
<price>550</price>
<sum>550</sum>
<vat_rate_id>БезНДС</vat_rate_id>
<vat_sum>0</vat_sum>
<execution_address_id>198</execution_address_id>
<execution_date_time>2014-01-05 16:30:00</execution_date_time>
</item>
</services>
</root> </syntaxhighlight>
Атрибуты
Следующие атрибуты являются обязательными к заполнению:
- contractor_id
- products.product_id
- products.quantity
- products.price
- products.vat_rate_id
- services.service_id
- services.quantity
- services.price
- services.vat_rate_id
Остальные атрибуты в случае их отсутствия будут вычислены автоматически заполнены значениями по умолчанию. Отсутствующим атрибутом считается тот, для которого отсутствует соответствующий ключ в переданных данных, а не только его значение. В примере ниже атрибут number является отсутствующим, а date_time просто с пустым значением.
{
"date_time": "",
"status_id": "Черновик",
"organization_id": 1
}
| Имя атрибута | Описание |
|---|---|
| date_time | Дата заказа покупателю в формате SQL. В случае отсутствия в переданных данных будет заполнена текущей датой. |
| number | Учетный номер документа. В случае отсутствия в переданных данных будет сгенерирован автоматически. |
| status_id | Статус заказа. Возможные значения: ПомеченНаУдаление, Черновик, Проведен. Значение по умолчанию - Черновик. |
| organization_id | Идентификатор собственной организации из справочника RefOrganization. В случае отсутствия в переданных данных будет заполнен идентификатором первой организации в системе. |
| contractor_id | Идентификатор покупателя из справочника RefContractor. |
| contract_id | Идентификатор договора с покупателем из справочника RefContract. В случае отсутствия в переданных данных будет заполнен идентификатором первого договора с указанным покупателем в системе. При отсутствии такового, будет автоматически создан новый договор. |
| currency_id | Идентификатор валюты из справочника RefCurrency. Значение по умолчанию - идентификатор валюты "Российский рубль". |
| price_type_id | Идентификатор типа цен из справочника RefPriceType - необязательный атрибут. |
| is_price_include_vat | Булево значение - признак включение НДС в стоимость товаров и услуг. |
| external_number | Номер заказа покупателя из внешней системы. |
| products.product_id | Идентификатор товара из справочника RefNomenclature. |
| products.sku_id | Идентификатор модификации товара из справочника RefSku. В случае отсутствия в переданных данных будет заполнен идентификатором основной модификации указанного товара. |
| products.unit_id | Идентификатор единицы измерения товара из справочника RefUnit. В случае отсутствия в переданных данных будет заполнен идентификатором базовой единицы измерения указанного товара. |
| products.factor | Коэффициент - кол-во базовых единиц измерения номенклатуры в текущей единице измерения. В случае отсутствия в переданных данных будет заполнен коэффициентом указанной единицы измерения. |
| products.quantity | Количество заказанного товара. |
| products.price | Цена заказанного товара. |
| products.sum | Сумма заказанного товара. В случае отсутствия в переданных данных будет рассчитана автоматически на основании количества, цены и ставки НДС. |
| products.vat_rate_id | Ставка НДС. Возможные значения: НДС18, НДС18_118, НДС10, НДС10_110, НДС0, БезНДС. |
| products.vat_sum | Сумма НДС заказанного товара. В случае отсутствия в переданных данных будет рассчитана автоматически на основании количества, цены и ставки НДС. |
| services.service_id | Идентификатор услуги из справочника RefNomenclature. |
| services.sku_id | Идентификатор модификации услуги из справочника RefSku. В случае отсутствия в переданных данных будет заполнен идентификатором основной модификации указанной услуги. |
| services.unit_id | Идентификатор единицы измерения услуги из справочника RefUnit. В случае отсутствия в переданных данных будет заполнен идентификатором базовой единицы измерения указанной услуги. |
| services.factor | Коэффициент - кол-во базовых единиц измерения номенклатуры в текущей единице измерения. В случае отсутствия в переданных данных будет заполнен коэффициентом указанной единицы измерения. |
| services.quantity | Количество заказанных услуг. |
| services.price | Цена заказанной услуги. |
| services.sum | Сумма заказанных услуг. В случае отсутствия в переданных данных будет рассчитана автоматически на основании количества, цены и ставки НДС. |
| services.vat_rate_id | Ставка НДС. Возможные значения: НДС18, НДС18_118, НДС10, НДС10_110, НДС0, БезНДС. |
| services.vat_sum | Сумма НДС заказанных услуг. В случае отсутствия в переданных данных будет рассчитана автоматически на основании количества, цены и ставки НДС. |
| services.execution_address_id | Идентификатор адреса из справочника RefAddress, по которому будет оказана услуга. Например, адрес доставки. |
| services.execution_date_time | Планируемая дата и время оказания услуги в SQL формате. |
Получение идентификаторов атрибутов-ссылок
Так как в качестве большинства атрибутов используются идентификаторы, целесообразно предварительно получить эти идентификаторы. Рассмотрим получение идентификатора на примере атрибута "Покупатель".
Поиск элемента в справочнике
Получение списка покупателей осуществляется посредством GET-запроса на один из адресов:
- https://company_name.mrdoc.org/api/1/RefContractor.json
- https://company_name.mrdoc.org/api/1/RefContractor.xml
в зависимости от того, в каком формате будет производится обмен (JSON или XML соответственно). В качестве GET-параметров стоит указать набор полей, который необходимо вернуть и фильтр, по которому необходимо найти требуемого покупателя.
Пример JSON
URL: https://company_name.mrdoc.org/api/1/RefContractor.json?fields[]=id&fields[]=type_id&filters[email][]="sale@askona.ru"
Ответ:
{
"result": [
{
"id": "2",
"type_id": "ЮрЛицо"
}
]
}
Пример XML
URL: https://company_name.mrdoc.org/api/1/RefContractor.xml?fields[]=id&fields[]=type_id&filters[email][]="sale@askona.ru"
Ответ:
<?xml version="1.0" encoding="utf-8"?>
<root>
<result list="true">
<item>
<id><![CDATA[2]]></id>
<type_id><![CDATA[ЮрЛицо]]></type_id>
</item>
</result>
</root>
Создание элемента справочника
В случае отсутствия необходимого покупателя в справочнике, его можно создать посредством PUT-запроса на эти же адреса, аналогично созданию заказа покупателя, описанного в данной статье. Ответом на PUT-запрос будет идентификатор вновь созданной записи.
Пример JSON
{
"result": {
"id": 583
}
}
Пример XML
<?xml version="1.0" encoding="utf-8"?>
<root>
<result>
<id><![CDATA[583]]></id>
</result>
</root>
Более подробно о атрибутах объектов системы можно прочитать в статье Описание объектов API
