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

Материал из Mr.Doc
Перейти к: навигация, поиск
 
(не показана 1 промежуточная версия 1 участника)
Строка 6: Строка 6:
  
 
== Структура запроса ==
 
== Структура запроса ==
−
Создание заказа осуществляется посредством PUT-запроса на один из адресов:
+
Создание заказа осуществляется посредством 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;">json</span>''
 
* ''https://<span style="color:red;">company_name</span>.mrdoc.org/api/1/DocSaleOrder.<span style="color:red;">xml</span>''
 
* ''https://<span style="color:red;">company_name</span>.mrdoc.org/api/1/DocSaleOrder.<span style="color:red;">xml</span>''
Строка 12: Строка 12:
 
В теле запроса должна содержаться информация о новом документе в выбранном формате.
 
В теле запроса должна содержаться информация о новом документе в выбранном формате.
 
=== Пример JSON  ===
 
=== Пример JSON  ===
−
<syntaxhighlight lang=javascript>
+
<pre>
 
{
 
{
 
     "date_time": "2014-01-01 12:00:00",
 
     "date_time": "2014-01-01 12:00:00",
Строка 64: Строка 64:
 
     ]
 
     ]
 
}
 
}
−
</syntaxhighlight>
+
</pre>
  
 
=== Пример XML ===
 
=== Пример XML ===
−
<syntaxhighlight lang=xml>
+
<pre>
 
<?xml version="1.0" encoding="utf-8"?>
 
<?xml version="1.0" encoding="utf-8"?>
 
<root>
 
<root>
Строка 120: Строка 120:
 
     </services>
 
     </services>
 
</root>
 
</root>
−
</syntaxhighlight>
+
</pre>
  
 
=== Атрибуты  ===
 
=== Атрибуты  ===
Строка 311: Строка 311:
  
 
=== Создание элемента справочника ===
 
=== Создание элемента справочника ===
−
В случае отсутствия необходимого покупателя в справочнике, его можно создать посредством PUT-запроса на эти же адреса, аналогично созданию заказа покупателя, описанного в данной статье.
+
В случае отсутствия необходимого покупателя в справочнике, его можно создать посредством POST-запроса на эти же адреса, аналогично созданию заказа покупателя, описанного в данной статье.
−
Ответом на PUT-запрос будет идентификатор вновь созданной записи.
+
Ответом на POST-запрос будет идентификатор вновь созданной записи.
 
==== Пример JSON ====
 
==== Пример JSON ====
 
<pre>
 
<pre>

Текущая версия на 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»