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

Версия 17:52, 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
}

Получение идентификаторов атрибутов-ссылок

Так как в качестве большинства атрибутов используются идентификаторы, целесообразно предварительно получить эти идентификаторы. Рассмотрим получение идентификатора на примере атрибута "Покупатель".

Поиск элемента в справочнике

Получение списка покупателей осуществляется посредством 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