98
правок
Изменения
→Response Examples
|-
|[[Файл:bitrix.png|center|x44px]]
|style="text-align: center;"|[httphttps://marketplace.1c-bitrix.ru/solutions/measoft.courier/ Install]
|Supports version 14.5 and higher.
|-
|[[Файл:prestashop.png|center|x60px]]
|style="text-align: center;"|[httphttps://courierexe.ru/download/api/prestashop.zip Download]
|Supports version 1.5.2.0 and higher (including 2.x)
|-
|[[Файл:OpencartOCStore.png|center|x60px]]
|style="text-align: center;"|[httphttps://courierexe.ru/download/api/opencart.zip For version 1.5.5.1]<br>[httphttps://courierexe.ru/download/api/measoft_oc2.ocmod.zip For version 2.0]<br>[httphttps://courierexe.ru/download/api/measoft_oc2.3.ocmod.zip For version 2.3]<br>[httphttps://courierexe.ru/download/api/measoft_ос3.ocmod.zip For version 3.0]
|Supports version 1.5.5.1 and higher.<br>Select a module for your OpenCart version.<br>[https://opencartforum.com/files/file/2906-avtomatizaciya-otpravki-i-otslezhivanie-dostavok-courierexe-dlya-opencart-15x/ Alternative third-party module]
|-
|The module is designed for sending orders to delivery service, while the plugin calculates delivery cost on creating an order.
|-
<!--|[[Файл:advantshop.png|center|x44px]]
|style="text-align: center;"|[https://promo-z.ru/ PROMO company site]
|The PROMO company has developed the module. Contact PROMO to set up integration between MeaSoft and ADVANTSHOP.
|--->
|[[Файл:insales.png|center|x80px]]
|style="text-align: center;"|Configure using MeaSoft [[Личный кабинет клиента|client account]]
|-
|[[Файл:Joomla2.jpg|center|x60px]]
|style="text-align: center;"|[httphttps://courierexe.ru/download/api/com_measoft.zip Download]
|Integration with Virtuemart is available only.
|-
|-
|[[Файл:wordpress.jpg|center|x80px]]
|style="text-align: center;"|[httphttps://courierexe.ru/download/api/wordpress.zip Download]
|
|-
|style="text-align: center;"|[https://marketplace.cs-cart.com/measoft-en.html Download]
|Supports versions 4.10 and higher.
|-
|style="height:100px; text-align: center;"|'''Webhook'''
|style="text-align: center;"|See [[Webhook|here]]
|Transfer of status and order info to your system
|-
|}
== Account for Integration ==
== General Terms ==
* 3000 queries from a single account per 1 hour.
* 200 MB text data downloaded per 3 hours.
* Number of non-existing order status queries must not exceed the number of queries of existing order statuses.
If a limit is exceeded, the IP address is blocked for up to 3 hours.
* Attacking our API with status queries with numbers of all you orders. Mind that the <code>tracking</code> queries are not intended for that, see [[API documentation#Order tracking by number|description]]. These queries are especially bad at the top of the hour.
* Sending queries like "Show statuses of all orders for the last 3 months" every 5 minutes.
* Sending a large amount of order numbers trying to guess which one is valid.
Correct actions:
* Queries are created for existing orders only.
* To check order statuses, use <code>statusreq</code> queries with parameter <code>changes=ONLY_LAST</code>.
* When requesting for changed statuses, you must confirm that the statuses were sucessfully received by query <code>commitlaststatus</code>.
</items>
<packages>
<package strbarcode="ORD0000001" mass="1" message="" quantity="3"></package>
<package strbarcode="ORD0000002" mass="2.5" message="" length="10" width="20" height="30"></package>
</packages>
</advprices>
<overall_volume>81</overall_volume>
<userid>123user123</userid> <groupid>456customer</groupid>
</order>
</neworder>
</source>
</spoiler>
'''Fields Description'''
*'''neworder''' — root container, required.
*'''phone''' is a phone number. You can specify several phone numbers and emails.
*'''town''' is the name of the town.
*'''pvz''' is the pickup point code from the '''Branches''' reference. Besides, you can specify the pickup point in the <code>address</code> parameter by one of the following:
** Pickup point code in our system.
** Pickup point code in service partner's system.
For the '''town''' tag, you can speify the value from the '''Regions ''' reference in the '''regioncode''' attribute. The town is searched for in the specified region.
In the '''country''' attribute, you can specify the recipient country according to the [https://en.wikipedia.org/wiki/ISO_3166-1#Current_codes ISO 3166-1] standard. For example: "AT", "AUT" or "040" for Austria.
*'''receiverpays''' — indicates whether recipient pays the delivery fee. If '''YES''', the recipient pays, if '''NO''', the sender pays.
*'''department''' — the order creator's department.
*'''pickup''' — indicates whether it is a pickup order. If '''YES''', the entire order is considered to be the assignment for pickup, not for delivery. It is used for calling a courier to the sender's place to pick up shipments. '''Note'''. If warehouse goods are added to the order, their type must be '''[7]Goods pickup'''. Any other type is automatically changed to type 7 on submitting the order.
* '''acceptpartially''' — indicates whether the recepient can partially accept order items.
*'''items''' — a container describing order items. It is an optional container. It has the following attributes:
:* '''''item''''' — item name.
:* '''''width''''' — package width in cm.
:* '''''height''''' — package height in cm.
:* '''''quantity''''' — number of packages with the specified dimensions and mass. Total number of packages in the order cannot be more than 1000.
* '''deliveryset''' — custom delivery rate setup. It has the following attributes:
*'''overall_volume''' — total volume, m3. An optional virtual field. It is used to calculate the package dimensions. The calculation works only if every package contains zero values of length, heigth, or width.
*'''userid''' — user ID, either string or integer type. Virual field, optional. The field is used in the custom delivery rate settings. It defines the rule priority. You can use the field for CMS and CRM to set delivery fee for each customer individually.
*'''groupid''' — user group ID, either string or integer type. Virual field, optional. The field is used in the custom delivery rate settings. It defines the rule priority. You can use the field for CMS and CRM to set delivery fee for each customer group individually.
<div style="color: #a94442; background-color: #f2dede; border: 1px solid #ebccd1; padding: 3px 10px 10px;">
<done>ONLY_NOT_DONE</done>
<changes>ONLY_LAST</changes>
<conditions>
<namecontains>1234</namecontains>
<namestarts>1234</namestarts>
</conditions>
</statusreq>
</source>
=== Fields Description ===
'''statusreq''' is a root container. Required. *'''auth''' — — authorization. Required. *'''client''' — — indicates whether it is a client or a delivery service partner. It is an optional element. Possible values: :* CLIENT — CLIENT — the default value.:* AGENT — AGENT — delivery service partner. Response contains information on the orders tendered for delivery. *'''orderno''' — — order number. It is an optional element.*'''ordercode''' — — internal order code. It is an optional element.*'''orderno2''' — — urgent order number. It is an optional element. *'''datefrom''' — — order creation date "from". It is an optional element. *'''dateto''' — — order creation date "'to". It is an optional element. *'''target''' — — a search text. You can specify a part of recipient company name or recipient address.*'''done''' — — possible values: :* ONLY_DONE — ONLY_DONE — delivered only. Success stauses like '''Delivered''', '''Partially delivered'''.:* ONLY_NOT_DONE — ONLY_NOT_DONE — undelivered only. Statuses like '''Not delivered''', '''Lost'''.:* ONLY_NEW — ONLY_NEW — new only.:*ONLY_DELIVERY — ONLY_DELIVERY — orders in process only. These are orders in any status except for final statuses '''Delivered''', '''Not delivered''', '''Canceled''' and the like.:* ''Empty'' — — for all shipments.*'''changes''' — — can take only ONLY_LAST value. If this parameter is specified, all other parameters are ignored. For more information, see [[#Get Latest Changed Statuses|Get Latest Changed Statuses]].* '''conditions''' — specify search conditions. The nested elements are joined by the logical AND operator.:* '''namecontains''' — search order numbers (external codes) that contain the specified text.:* '''namestarts''' — search order numbers (external codes) that start with the specified text.
<div style="color: #a94442; background-color: #f2dede; border: 1px solid #ebccd1; padding: 3px 10px 10px;">
# You can request statuses of orders created no earlier than 2 months before the '''to''' date (<code>datefrom</code> and <code>dateto</code> containers). # If no date is provided, <code>dateto</code> equals the current date. # Omitting <code>dateto</code> defaults to <code>datefrom</code> plus two months.
# Omitting <code>datefrom</code> defaults to <code>dateto</code> minus two months.
# You can search using '''conditions''' only by order numbers (external codes). 4 characters is the minimum search length.
</div>
<return_weight>5.1</return_weight>
<quantity>2</quantity>
<paytypecode="1">CASH</paytype>
<service>2</service>
<return_service>2</service>
<arrival>2021-05-02 23:21</arrival>
<outstrbarcode>EXT123456</outstrbarcode>
<partner>Western Branch</partner>
<return_message>Delivered undamaged</return_message>
<department>Accounting</department>
* '''arrival''' — scheduled delivery date formatted as YYYY-MM-DD HH:MM:SS.
* '''outstrbarcode''' — service partner system code (in an external system). It is used for integration with external systems.
* '''partner''' — current branch or service partner.
* '''return_message''' — return information.
* '''department''' — the order creator's department.
<auth extra="8" login="login" pass="pass"></auth>
<changes>ONLY_LAST</changes>
<streamid>1234</streamid>
</statusreq>
</source>
<auth extra="8" login="login" pass="pass"></auth>
<client>CLIENT</client>
<streamid>1234</streamid>
</commitlaststatus>
</source>
* '''auth''' — Authorization. Required.
* '''streamid''' - stream ID. If you get order statuses for multiple integrations, pass this parameter to divide getting statuses and sending confirmation. The value must be from 100 up to 10000. It is an optional element.
*'''client''' — indicates whether it is a client or a delivery service partner. It is an optional element. Possible values:
:*'''CLIENT''' — the default value.
# If an order is being edited via API and in MeaSoft desktop application at the same time, only the changes made in the desktop applications are applied.
</div>
Planned courier might be canceled utomatically once an order is edited. It depends on the value set in '''References''' > '''Variables''' > '''Shipments''' > '''Automatically assign courier by area''':
* '''No''' — courier is not changed on editing orders via API.
* '''Area''' — courier is canceled on changing delivery address.
* '''Area or delivery date''' — courier is canceled on changing delivery address or delivery date.
=== Edit Request Fields ===
* do not specify the <code>barcode</code> tag as it is assigned when creating an order.
* for <code>item</code> items, specify the item internal code in the <code>code</code> attribute. To receive the internal code, use the [[#Order Status|order status]] request.
You cannot change the '''orderno''' value using this method.
=== Edit Response Fields ===
<name>Moscow</name>
<fullname>Moscow city</fullname>
<country>1RU</country>
</conditions>
<limit>
== Getting Shipping Rates for Towns and Cities ==
<div style="color: #a94442; background-color: #f2dede; border: 1px solid #ebccd1; padding: 3px 10px 10px;">
If the <code>nofederal</code> parameter is missing in the request, Moscow is processed in the following way: the response contains Moscow and Moscow region towns and distance markup.
</div>
'''Request Example'''
*'''service''' — delivery mode. Required.
*'''mainonly''' — optional. If passed, the response contains data from the '''Inter-city''' > '''Zones''' table only.
* '''nofederal''' — optional. If passed, a city of federal importance is processed as an ordinary city.
"tariffs": [
{
"towntofias": "7339e8340c5b2444-2cb470a0-47344932-a4c7980c-1fca2c66e562b4dc0d3f02b5", "towntocode": 1, "towntoname": "482Moscow city", "towntonamedistance": 0, "Ufa citypricedistance": 0,
"pricesnew": {
"before": [
"mass": "1"
},
}
],
"after": [
{
}
]
},
"prices": { "before": { "mass": "3", "price": "202.5" }, "after": { "mass": "3", "everydeliveryPeriodMin": "1", "price": "18.75" } }, "deliveryPeriodMin": 4, "deliveryPeriodMax": 52
}
]
:* '''towntocode''' — recipient locality internal code.
:* '''towntoname''' — recipient locality name.
:* '''distance''' — distance in km from Moscow to Moscow Ring Road if <code>townfrom</code> is Moscow.
:* '''pricedistance''' — Moscow to Moscow Ring Road distance markup if <code>townfrom</code> is Moscow..
:* '''pricesnew''' — your shipping rates from the '''Inter-city''' > '''Rates by Zones''' table.
::* '''before/after — containers.:::* '''price''' — price. If the response is for the <code>before</code> container, <code>pricedistance</code> is also added to the amount.:::* '''every''' — for every specified number of pieces.:::* '''mass''' — weight.
:* '''prices''' — obsolete, do not use.
:* '''deliveryPeriodMin''' — minimum number of days in transit.
To show pickup points on the map, use the [https://home.courierexe.ru/js/measoft_map.js JavaScript module]. See help info in the file. See example [https://home.courierexe.ru/pvz_test.html here].
Unique pickup point requests are cached on the client account side and retained till 7 AM GMT+3 of the next day. For example, if a unique request with a mass of 2 kg was submitted today at 10 AM, tommorow at 7 AM it will be deleted. If you submit a mass of 2 kg in the same request today at 6 PM, you will get the same list of pickup points. If you submit a mass of 3 kg in the same request, you will probably get another list.
'''Request Example'''
<code>1234</code>
<client_code>7890</client_code>
<city>Sverdlovsk Oblast</city> <townregioncode="66" country="RU">Nizhniy Nizhny Tagil</town>
<parentcode>6</parentcode>
<acceptcash>YES</acceptcash>
*'''code''' — internal code.
*'''client_code''' — courier service client code.
*'''city''' - recipint region. You can specify a region code or a full region name from the '''Regions''' reference.
*'''town''' — recipient location.
:For the <code>town</code> tag, you can speify the value from the '''Regions''' reference in the <code>regioncode</code> attribute. The specified region is searched for the town.
:In the <code>country</code> attribute, you can specify the recipient country according to the ISO 3166-1 standard. For example: "AT", "AUT" or "040" for Austria.
*'''parentcode''' — parent [[#Branches List|branch]].
*'''acceptcash''' — indicates whether cash on delivery is accepted. Possible values: '''YES''', '''NO'''.
<inshprice>387.5</inshprice>
<packages>
<package mass="1" quantity="5"></package>
<package mass="2.5" length="10" width="20" height="30"></package>
</packages>
<userid>123user123</userid> <groupid>456customer</groupid>
</order>
</calculator>
</source>
Parameters are the same as described in [[#Creating Order|Creating Order]].
'''Fields Description'''
*'''inshprice''' — declared value amount.
*'''paytype''' — payment type.
*'''userid''' — user ID, either string or integer type. Virual field, optional. The field is used in the custom delivery rate settings. It defines the rule priority. You can use the field for CMS and CRM to set delivery fee for each customer individually.*'''groupid''' — user group ID, either string or integer type. Virual field, optional. The field is used in the custom delivery rate settings. It defines the rule priority. You can use the field for CMS and CRM to set delivery fee for each customer group individually.
Cash on delivery amount, declared value amount, and CARD payment type are used in service percent calculations set up in the delivery rate card, on the '''Other''' tab.
<service name="Express">1</service>
<zone>2</zone>
<price>11631113</price>
<mindeliverydays>1</mindeliverydays>
<maxdeliverydays>3</maxdeliverydays>
<advprice code="4" price="100">Amount percent</advprice>
<advprice code="5" price="63">Declared value percent</advprice>
<advprice code="6" price="-50">Discount on delivery</advprice>
</deliveryprice>
</calc>
