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

Материал из Mr.Doc
Перейти к: навигация, поиск
(Получение идентификаторов атрибутов-ссылок)
(Получение идентификаторов атрибутов-ссылок)
Строка 272: Строка 272:
 
Так как в качестве большинства атрибутов используются идентификаторы, целесообразно предварительно получить эти идентификаторы.
 
Так как в качестве большинства атрибутов используются идентификаторы, целесообразно предварительно получить эти идентификаторы.
 
Рассмотрим получение идентификатора на примере атрибута '''"Покупатель"'''.
 
Рассмотрим получение идентификатора на примере атрибута '''"Покупатель"'''.
Получение списка покупателей осуществляется посредством GET запроса на один из адресов:
+
=== Поиск элемента в справочнике ===
 +
Получение списка покупателей осуществляется посредством 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;">json</span>''
 
* ''https://<span style="color:red;">company_name</span>.mrdoc.org/api/1/RefContractor.<span style="color:red;">xml</span>''
 
* ''https://<span style="color:red;">company_name</span>.mrdoc.org/api/1/RefContractor.<span style="color:red;">xml</span>''
 
в зависимости от того в каком формате будет производится обмен (JSON или XML соответственно).
 
в зависимости от того в каком формате будет производится обмен (JSON или XML соответственно).
 
В качестве GET-параметров стоит указать набор полей, который необходимо вернуть и фильтр, по которому необходимо найти требуемого покупателя.
 
В качестве GET-параметров стоит указать набор полей, который необходимо вернуть и фильтр, по которому необходимо найти требуемого покупателя.
=== Пример JSON ===
+
==== Пример 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"''
 
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"''
  
Строка 292: Строка 293:
 
</pre>
 
</pre>
  
=== Пример XML ===
+
==== Пример 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"''
 
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"''
  
Строка 307: Строка 308:
 
</root>
 
</root>
 
</pre>
 
</pre>
 +
 +
=== Создание элемента справочника ===
 +
В случае отсутствия необходимого покупателя в справочнике, его можно создать посредством PUT-запроса, аналогично созданию заказа покупателя, описанного в данной статье.
 +
Ответом на PUT-запрос будет идентификатор вновь созданной записи.
 +
==== Пример JSON ====
 +
==== Пример XML ====

Версия 17:25, 4 марта 2014

Данная статья посвящена обмену данными с системой 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

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

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

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

Пример JSON

Пример XML