Создание заказа покупателя через API — различия между версиями

Материал из Mr.Doc
Перейти к: навигация, поиск
 
(не показано 36 промежуточных версий 2 участников)
Строка 1: Строка 1:
 
[[Category:API]]
 
[[Category:API]]
 
Данная статья посвящена обмену данными с системой Mr.Doc через REST API интерфейс на примере создания заказа покупателя.
 
Данная статья посвящена обмену данными с системой Mr.Doc через REST API интерфейс на примере создания заказа покупателя.
 +
 +
== Доступ к API ==
 +
Перед выполнением операций с системой через API необходимо настроить права доступа для учетной записи, от которой будут производиться запросы. Подробнее об этом можно прочитать в разделе [[Настройка доступа к API]].
 +
 +
== Структура запроса ==
 +
Создание заказа осуществляется посредством POST-запроса на один из адресов:
 +
* ''https://<span style="color:red;">company_name</span>.mrdoc.org/api/1/DocSaleOrder.<span style="color:red;">json</span>''
 +
* ''https://<span style="color:red;">company_name</span>.mrdoc.org/api/1/DocSaleOrder.<span style="color:red;">xml</span>''
 +
в зависимости от того, в каком формате будет производиться обмен (JSON или XML соответственно).
 +
В теле запроса должна содержаться информация о новом документе в выбранном формате.
 +
=== Пример JSON  ===
 +
<pre>
 +
{
 +
    "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"
 +
        }
 +
    ]
 +
}
 +
</pre>
 +
 +
=== Пример XML ===
 +
<pre>
 +
<?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>
 +
</pre>
 +
 +
=== Атрибуты  ===
 +
Следующие атрибуты являются обязательными к заполнению:
 +
* 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''' просто с пустым значением.
 +
<pre>
 +
{
 +
    "date_time": "",
 +
    "status_id": "Черновик",
 +
    "organization_id": 1
 +
}
 +
</pre>
 +
 +
{| class="wikitable"
 +
|-
 +
!Имя атрибута
 +
!Описание
 +
 +
|-
 +
!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://<span style="color:red;">company_name</span>.mrdoc.org/api/1/RefContractor.<span style="color:red;">json</span>''
 +
* ''https://<span style="color:red;">company_name</span>.mrdoc.org/api/1/RefContractor.<span style="color:red;">xml</span>''
 +
в зависимости от того, в каком формате будет производится обмен (JSON или XML соответственно).
 +
В качестве GET-параметров стоит указать набор полей, который необходимо вернуть и фильтр, по которому необходимо найти требуемого покупателя.
 +
==== Пример JSON ====
 +
URL: ''https://<span style="color:red;">company_name</span>.mrdoc.org/api/1/RefContractor.<span style="color:red;">json</span>?fields[]=id&fields[]=type_id&filters[email][]="sale@askona.ru"''
 +
 +
Ответ:
 +
<pre>
 +
{
 +
    "result": [
 +
        {
 +
            "id": "2",
 +
            "type_id": "ЮрЛицо"
 +
        }
 +
    ]
 +
}
 +
</pre>
 +
 +
==== Пример XML ====
 +
URL: ''https://<span style="color:red;">company_name</span>.mrdoc.org/api/1/RefContractor.<span style="color:red;">xml</span>?fields[]=id&fields[]=type_id&filters[email][]="sale@askona.ru"''
 +
 +
Ответ:
 +
<pre>
 +
<?xml version="1.0" encoding="utf-8"?>
 +
<root>
 +
    <result list="true">
 +
        <item>
 +
            <id><![CDATA[2]]></id>
 +
            <type_id><![CDATA[ЮрЛицо]]></type_id>
 +
        </item>
 +
    </result>
 +
</root>
 +
</pre>
 +
 +
=== Создание элемента справочника ===
 +
В случае отсутствия необходимого покупателя в справочнике, его можно создать посредством POST-запроса на эти же адреса, аналогично созданию заказа покупателя, описанного в данной статье.
 +
Ответом на POST-запрос будет идентификатор вновь созданной записи.
 +
==== Пример JSON ====
 +
<pre>
 +
{
 +
    "result": {
 +
        "id": 583
 +
    }
 +
}
 +
</pre>
 +
==== Пример XML ====
 +
<pre>
 +
<?xml version="1.0" encoding="utf-8"?>
 +
<root>
 +
    <result>
 +
        <id><![CDATA[583]]></id>
 +
    </result>
 +
</root>
 +
</pre>
 +
Более подробно о атрибутах объектов системы можно прочитать в статье [[Описание объектов API]]

Текущая версия на 12:35, 20 октября 2016

Данная статья посвящена обмену данными с системой Mr.Doc через REST API интерфейс на примере создания заказа покупателя.

Доступ к API

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

Структура запроса

Создание заказа осуществляется посредством POST-запроса на один из адресов:

  • https://company_name.mrdoc.org/api/1/DocSaleOrder.json
  • https://company_name.mrdoc.org/api/1/DocSaleOrder.xml

в зависимости от того, в каком формате будет производиться обмен (JSON или XML соответственно). В теле запроса должна содержаться информация о новом документе в выбранном формате.

Пример JSON

{
    "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"
        }
    ]
}

Пример 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>

Атрибуты

Следующие атрибуты являются обязательными к заполнению:

  • 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>

Создание элемента справочника

В случае отсутствия необходимого покупателя в справочнике, его можно создать посредством POST-запроса на эти же адреса, аналогично созданию заказа покупателя, описанного в данной статье. Ответом на POST-запрос будет идентификатор вновь созданной записи.

Пример JSON

{
    "result": {
        "id": 583
    }
}

Пример XML

<?xml version="1.0" encoding="utf-8"?>
<root>
    <result>
        <id><![CDATA[583]]></id>
    </result>
</root>

Более подробно о атрибутах объектов системы можно прочитать в статье Описание объектов API

Источник — «http://wiki.mrdoc.org/index.php?title=Создание_заказа_покупателя_через_API&oldid=434»