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

Версия 13:45, 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

<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 формате.

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

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