1b.app
Link copied -
We use cookies to optimize content and website performance. By continuing your visit, you agree to our use of cookies.
ru ua de
RU UA DE
Sign in / Sign up
  1. OneBox
    2. ›
  2. OneBox Rest API
    3. ›
  3. API Orders (Orders)

API Orders (Orders)

Why do customers need it? As a rule, these are just a few things - transfer an order, product, categories, brands to BOX. Several methods are used for this. More details below



Add order, method: /api/orders/add/

Parameters

Example:

http://myboxurl/api/orders/add/?login=LOGIN&password=PASSWORD&clientnamefirst=Vasiliy&clientnamelast=Ivanov&clientemail=vasyas33@test.ru&clientphone=+380639370442&clientcode=31333&clientaddress=Kiev&managername=Inna Leonova&ordercode=1333&sum=320&comments=made an advance payment&source=my store&payed=1&productArray[0][id]=100500&productArray[0][name]=Test GOODS1&productArray[0][price]=102&productArray[0][count]=1&productArray[1][id]=123131&productArray[1][name]=New% 20testoviy% 20produkt2&productArray[1][price]=122&productArray[1][count]=2

There is no need to create a contact before creating an order, the BOX system will create it itself if necessary.
Adding a project or task using the REST API is the same as adding an order. For this, a mandatory parameter when sending a request is the workflowname parameter, which is used to pass the name of the Business process in which you want to create a project / order / task. If you specify the name of the Business Process - be sure to check that it was created in your OneBox. If you do not specify a Business Process, the default Business Process for orders will be selected.


№ Field Type Description Required or not Comment
1 login string Login in BOX system Required field.  
2 password string Password in md5 format Required field. Contact tech support and we will give you a hash for the API
3 ordercode string id order from your system Required field. This is a unique order ID from your system (from your store). If an order with this id exists, the API will throw an error
4 workflowname string Business process name for orders Optional field. Please enter the name of the BP you want to add the order to. If you specify a power supply unit, then make sure it was created in your BOX. If not specified, the default BP will be selected for orders.
5 statusname string order status Optional field. Enter the status from the BP you want to add the order to. If you do not specify the status, the default will be the start one.
6 source string Order channel Optional field.  
7 cdate datetime order date Optional field. Order creation date, must be in the format (Ymd H: i: s) Example: 2015-12-15 23:11:00
8 name string Order name Optional field.  
9 clientcode string id customer from order Optional field. In this field you can write the user id from the order from your system.
10 clientnamefirst string Customer name from order Optional field.  
11 clientnamelast string Customer surname from order Optional field.  
12 clientnamemiddle string Optional field.  
13 clientphone integer Customer phone number from order Either the customer's email or phone is required Preferably in 380XXXXXXXXX format
14 clientemail string Email customer from order  
15 clientaddress string Customer address from order Optional field.  
16 managercode string id order manager Optional field. In this field you can write the id of the manager from the order from your system.
17 managername string The name of the manager from the order Optional field.  
18 managerphone integer Phone of the manager from the order Optional field. Preferably in 380XXXXXXXXX format
19 manageremail string Email order manager Optional field.  
20 comments string Comment to order Optional field. In this field you can write any order information you need
21 deliveryid integer id order delivery method Optional field. If your WebProduction BOX system has added shipping methods, then enter the desired shipping method id
22 deliverynote string Comment for order delivery Optional field.  
23 sum float order amount Optional field.  
24 payed true / false Has the order been paid? Optional field. If the order is paid, then pass true to this field and the payment for this order and the finance section and in the order itself will be added to the BOX.
25 productArray array (id, name, price, count) Array of products from order Optional field.
id - id product from BOX, if there is one, the system will link it to the order
code1c - id goods from your system, if there is one, the system will link it to the order
articul - the article of the product from the system, if there is one, the system will link it to the order
name - product name
price - product price per unit
count - quantity of this product in the order
currency - currency of the item in the order (UAH, RUB, USD, EUR, etc.)..)
discount_percent - Process product discount percentage
supplierid - ID provider in the system
suppliercode1c - External vendor ID in the system
custom_{key} - Custom-e field. Instead of {key} you need to substitute the additional field key from the order product
26 workflowid integer ID Business Process Optional field. Enter the BP id where you want to add an order / task / project. If you specify a power supply, make sure it is created in your OneBox.
27 statusid integer ID Order status Optional field. Enter the ID of the status you want to transfer the BP to. If you do not specify the status, the default will be the start one.
28 type string BP type Optional field. If you do not specify BP, then indicate the type of BP to add
29 utm_date string UTL utm_date label Optional field.  
30 utm_campaign string UTL utm_campaign label Optional field.  
31 utm_source string UTL utm_source label Optional field.  
32 utm_content string UTL utm_content label Optional field.  
33 utm_referrer string UTL utm_referrer label Optional field.  
34 utm_medium string UTL utm_medium label Optional field.  
35 utm_term string UTL utm_term label Optional field.  
36 custom_{key} string Custom-e field Instead of {key} you need to substitute the additional field key from the order When transferring a file link for an additional field with type" File" - it will be uploaded to the system and the ID is written in the additional field
37 customuser_{key} string Custom-e field of the client Instead of {key} you need to substitute the key of the additional field from the contact card When transferring a file link for an additional field with type" File" - it will be uploaded to the system and the ID is written in the additional field
38 dateto datetime Order (task) scheduled date Optional field. Order planning date, must be in the format (Ymd H: i: s) Example: 2015-12-15 23:11:00
39 deliveryprice float shipping cost Optional field.  
40 discountid integer ID OneBox discounts Optional field.  
41 discountname string Discount name from OneBox system Optional field.  
42 discountsum float Discount Amount Optional field.  
43 contractorid integer The legal entity of the order Optional field.  
44 paymentid integer ID payment method Optional field. id OneBox payment method
45 paymentname string Payment method name Optional field. If you specify this parameter, the system will try to find this payment method in OneBox and raise it
46 country string Country Optional field.  
47 region string Region (area) Optional field.  
48 district string District Optional field.  
49 city string Name of the settlement Optional field.  
50 street string Street Optional field.  
51 street_number string House number Optional field.  
52 apartment string Apartment Optional field.  
53 currencyrate_{key} string Currency rate for ordering Instead of {key} you need to substitute the name of the currency  
54 documenttemplateid int ID document template Optional field. After the process is created, an attempt will be made to generate a document according to the specified document template.
55 documentpdf base64 encoded string Content of the generated PDF document in base64 encoding. Optional field. After the document is generated by documenttemplateid, the content of the PDF document will be decoded and added as a scanned copy to the created document.
56 dataFromBody boolean Take data not from arguments, but from body Optional field. If dataFromBody = 1 is passed, then data will be taken not from arguments, but from the request body. Json must be passed to the body, in which the keys must be the parameters described above. login and password should be sent as usual
57 typesex string Process client type Optional field. You can transfer the name or key of the contact type from the system settings" Contact types"
58 parentid integer id parent process Optional field. id process to be parent, the current process will become a subprocess of it
59 company string Client's company name Optional field. If a company with this name is not found, it will be created
60 files string|array Files for process description Optional field. Link or array of links to files that need to be downloaded and added to the process description
61 restoreSource boolean Restore Remote Source Optional field. If the transferred source is deleted, it will be restored. The source creation date will be updated to the current one.

Delete order, method: /api/orders/delete/

Parameters

Example:

http://myboxurl/api/orders/delete/?login=LOGIN&password=PASSWORD&orderid=660

№ Field Type Description Required or not Comment
1 login string Login in BOX system Required field.  
2 password string Password in md5 format Required field. Contact tech support and we will give you a hash for the API
3 orderid string Order ID Required field. In this field you can pass either the order id that our API returned to you when it was created. Or send an external order identifier (field ordercode when creating an order . The system will try to find an order with this external ID and delete it.

Editing order, method: /api/orders/update/

Parameters

Example:

http://myboxurl/api/orders/update/?login=LOGIN&password=PASSWORD&orderid=660&&name=Changing the order name&workflowname=Order&statusname=Delivered&payed=1

№ Field Type Description Required or not Comment
1 login string Login in BOX system Required field.  
2 password string Password in md5 format Required field. Contact tech support and we will give you a hash for the API
3 orderid string Order ID Required field. In this field you can pass either the order id that our API returned to you when it was created. Or send an external order identifier (field ordercode when creating an order). The system will try to find an order with this external ID.
4 name string Order name Optional field.  
5 comments string Order comment Optional field.  
6 sum float order amount Optional field.  
7 deliverynote string Delivery Comments Optional field.  
8 workflowname string Business order process Optional field. You can change the order BP to another via the API
9 statusname string Order status for this BP Optional field. Set a different order status
10 payed boolean Whether to pay for the order Optional field. Is the order paid?
11 productArray array Add Items to Order Optional field. You can add items to an existing order. The amount will be automatically recalculated
id - id product from BOX, if there is one, the system will link it to the order
code1c - id goods from your system, if there is one, the system will link it to the order
articul - the article of the product from the system, if there is one, the system will link it to the order
name - product name
price - product price per unit
count - quantity of this product in the order
currency - currency of the item in the order (UAH, RUB, USD, EUR, etc.)..)
storagecode1c - The external ID of the warehouse where the BOX will try to reserve the item if it is not already reserved
storagefromcode1c - external warehouse ID. If you pass this parameter, then only those goods that are currently in storagefromcode1c will be reserved in storagecode1c
suplierid - ID provider in the system
supliercode1c - External vendor ID
custom_{key} - Custom-e field. Instead of {key} you need to substitute the additional field key from the order product
12 workflowid integer Id Business order process Optional field. You can change the order BP to another via the API
13 statusid integer Id status for this BP Optional field. Set different status by id
14 deleteproducts 0/1 Remove items from order Optional field. If 1 - deletes all products in the edited order
15 dataFromBody boolean Take data not from arguments, but from body Optional field. If dataFromBody = 1 is passed, then data will be taken not from arguments, but from the request body. Json must be passed to the body, in which the keys must be the parameters described above. login and password should be sent as usual
16 paymentid integer ID payment method for the process Optional field.  
17 customuser_[key] optional Optional Process Client Field Optional field. Instead of [key] you must substitute the client extra field ID
17 customorder_[key] optional Additional Process Field Optional field. Instead of [key] process extra field identifier must be substituted
When transferring a file link for an additional field with type" File" - it will be uploaded to the system and the ID is written in the additional field.
18 clientemail string Email process client Optional field. Logged into the process and added to the client of the process. If there is no client, the process is used to find (and create) a client.
19 clientphone string Process client phone Optional field. Logged into the process and added to the client of the process. If there is no client, the process is used to find (and create) a client.
20 clientname string Customer name from order Optional field. Used to update the process client (and create it if not present)
21 clientnamelast string Customer surname from order Optional field. Used to update the process client (and create it if not present)
22 clientnamemiddle string Optional field. Used to update the process client (and create it if not present)
23 clienttypesex string Client's typesex from order Optional field. Used to update the process client (and create it if not present)
24 clientexternalid string Client's external ID from order Optional field. Used to update the process client (and create it if not present)
25 clientcode string Client's code from order Optional field. Used to update the process client (and create it if not present)
26 clientcompany string Client's company from order Optional field. Used to update the process client (and create it if not present)
27 searchclient boolean Search customer by contact details, even if there is a customer in the order Optional field.
28 country string Country Optional field. Used to update the client address of the process
29 region string Region (area) Optional field. Used to update the client address of the process
30 district string District Optional field. Used to update the client address of the process
31 city string Name of the settlement Optional field. Used to update the client address of the process
32 street string Street Optional field. Used to update the client address of the process
33 street_number string House number Optional field. Used to update the client address of the process
34 apartment string Apartment Optional field. Used to update the client address of the process
35 deliveryid integer id order delivery method Optional field. If your WebProduction BOX system has added shipping methods, then enter the desired shipping method id
36 novaposhtadeliverynote string TTN number of new mail Optional field.
37 novaposhtaredeliverynote string New mail return shipping number Optional field.
38 novaposhtaServiceType string Delivery method New Mail Optional field. Available Values:
WarehouseWarehouse - Choard-Warehouse WarehouseDoors - CHoard-Doors DoorsWarehouse - Doors-Warehouse DoorsDoors - Doors-Doors
39 utm_XXX (where, instead of XXX, put the label you need, for example utm_source, utm_date) string UTM process labels Optional field.
40 files string|array Files for process description Optional field. Link or array of links to files that need to be downloaded and added to the process description

Receive one order and receive all orders, method: /api/orders/get/

Parameters
Parameters for receiving one order:

Example:

http://myboxurl/api/orders/get/?login=LOGIN&password=PASSWORD&orderid=7927

№ Field Type Description Required or not Comment
1 login string Login in BOX system Required field.  
2 password string Password in md5 format Required field. Contact tech support and we will give you a hash for the API
3 supplierhash string Vendor key Optional field. Available in the customer card, which is the supplier's contact.
Available with system login and password and access level" client".
Allows to restrict access to receiving processes according to the connection of the additional process field with the vendor key (see. Settings" Checks and uniqueness") or only where this contact is a provider customer.
4 orderid string Order ID Required field. If you need a specific order, then you pass in this field either the order id that was returned to you by our API when it was created. Or send an external order identifier (field ordercode when creating an order). The system will try to find an order with this external ID.
Also, there is a possibility to receive an order by additional order fields. To do this, you need to transfer an additional ID. fields (displayed in settings) with prefix' customorder_' and specify the desired value, for example customorder_idKeydoppolya = value

Return field values
orderid - id Ordering
ordercode - external order id,
ordername - Order name,
clientId - id client on BOX system,
clientcode - external client id in the BOX system,
clientname - customer name,
clientemail - email client,
clientphone - customer phone,
clientaddress - customer address,
managerid - id order manager,
managername - Name order manager,
managerrole - Role order manager,
cdate - order date,
dateto - order planning date,
deliveriID - id delivery method,
deliverinote - shipping comments,
deliveriprice - shipping cost,
sum - order amount,
sumbase - base order amount,
currency - order currency,
statusname - order status,
workflowname - BP order name,
contractorid - id the legal entity of the order,
contractorname - name of the legal entity of the order,
weight - total order weight,
gabarite - total order quantity,
products - Array of products from order, consists of:
  • id - product id
  • name - Product name
  • count - product quantity
  • price - product price
  • discountsum - amount discount
  • discountpercent - percent discount
  • pricewithdiscount - Discount product price
  • storageId - product warehouse id
  • storageExternalId - external product warehouse id
  • productsource - product type (returns product or service)
  • pricewithvat - Price with VAT
  • pricewithoutvat - Price without VAT
  • productpricewithvat - Cost with VAT
  • productpricewithoutvat - Cost without VAT
  • producttaxvalue - VAT (%)
  • supplierid - ID provider in the system
  • suppliercode1c - External vendor ID in the system
  • suppliername - Vendor name in the system
  • customfields - additional order product fields that consist of:
    • key - additional_field_key_
    • name - custom field name
    • value - additional field value
customfields - an array of additional fields in the order, which consist of:
  • key - additional_field_key_
  • name - custom field name
  • value - additional field value
5 sumoutbonuse bool Amount of bonuses written off in progress Optional field.  
6 suminbonuse bool Amount of bonuses awarded in progress Optional field.  
7 getcomments bool Get process comments Optional field. Returns an array with all process comments

Each element of the array will contain
id - id comments,
cdate - date the comment was created,
type - comment type,
content - comment text,
showtoclient - Is the comment shown to the client,
userid - id the contact who left the comment,
usercode - external contact id,
username - contact name,
useremail - email contact,
userphone - Contact phone number,
8 unescapedunicode bool Don't encode Unicode characters Optional field. If you pass 1 of this parameter in the resulting JSON, Unicode characters will not be encoded, for example, Cyrillic" а" will be passed as" а", not how" \u0430"
9 getnovaposhtastatus bool Get New Mail TTN statuses Optional field. When the value of 1 of this parameter is passed, the list of fields will additionally contain the status of the ttn and the status of the reverse ttn of New mail


Parameters for receiving all orders:

Example:

http://myboxurl/api/orders/get/?login=LOGIN&password=PASSWORD&part=1
http://myboxurl/api/orders/get/?login=LOGIN&password=PASSWORD&part=2

№ Field Type Description Required or not Comment
1 login string Login in BOX system Required field.  
2 password string Password in md5 format Required field. Contact tech support and we will give you a hash for the API
3 supplierhash string Vendor key Optional field. Available in the customer card, which is the supplier's contact.
Available with system login and password and access level" client".
Allows to restrict access to receiving processes according to the connection of the additional process field with the vendor key (see. Settings" Checks and uniqueness") or only where this contact is a provider customer.
4 workflowname string Business process name for orders Optional field. Please enter the name of the Business process by which you want to filter orders / tasks / projects
5 workflowid string ID Business Process Optional field. Enter the id of the Business process by which you want to filter orders / tasks / projects. If you specify a power supply, make sure it is created in your OneBox.
6 type string BP type Optional field. Specify the type of Business process to filter orders / tasks / projects with a given type
7 statusname string order status Optional field. Enter the name of the BP status by which you want to filter orders / tasks / projects.
8 statusid string ID Order status Optional field. Enter the BP status ID by which you want to filter orders / tasks / projects.
9 cdate date Order creation date Optional field. Specify the creation date and the final selection will include only those orders whose creation date is greater than or equal to the specified one
10 udate date Date and time of the last order update Optional field. Please specify the date of the last update and the final selection will include only those orders in which the date of the last modification is greater than or equal to the specified one
11 clientId string ID client on BOX system Optional field. Please enter the client ID by which you want to filter processes.
12 clientcode string external client id in the BOX system Optional field. Please enter the external client ID by which you want to filter processes.
13 sumoutbonuse bool Amount of bonuses written off in progress Optional field.  
14 suminbonuse bool Amount of bonuses awarded in progress Optional field.  
15 typesex string Process client contact type Optional field. To filter processes by the contact type of the process client, you must pass the contact type key (for example company)
16 customorder_[key] optional Filtering processes by additional process fields Optional field. For additional fields of the "Integer", "Float", "Datetime", "Date", "Time" types, filtering by the range of values FROM and TO is available by passing the parameters customorder_[key]_from and customorder_[key]_to
17 customuser_[key] optional Process filtering by additional process client fields Optional field. For additional fields of the "Integer", "Float", "Datetime", "Date", "Time" types, filtering by the range of values FROM and TO is available by passing the parameters customuser_[key]_from and customuser_[key]_to
18 part integer Part of orders Required field. API gives up to 1000 orders in the 1st part, to get the next 1000 orders send 2 there (it turns out part 2) and so on.

Return field values
orderid - id Ordering
ordernumber - order number
ordercode - external order id,
ordername - Order name,
clientId - id client on BOX system,
clientcode - external client id in the BOX system,
clientname - customer name,
clientemail - email client,
clientphone - customer phone,
clientaddress - customer address,
managerid - id order manager,
managername - Name order manager,
managerrole - Role order manager,
cdate - order date,
deliveriID - id delivery method,
deliverinote - shipping comments,
deliveriprice - shipping cost,
sum - order amount,
sumbase - base order amount,
currency - order currency,
statusname - order status,
workflowname - BP order name,
contractorid - id the legal entity of the order,
contractorname - name of the legal entity of the order,
products - Array of products from order, consists of:
  • id - product id
  • name - Product name
  • count - product quantity
  • price - product price
  • storageId - product warehouse id
  • storageExternalId - external product warehouse id
  • productsource - product type (returns product or service)
  • pricewithvat - Price with VAT
  • pricewithoutvat - Price without VAT
  • productpricewithvat - Cost with VAT
  • productpricewithoutvat - Cost without VAT
  • producttaxvalue - VAT (%)
  • supplierid - ID provider in the system
  • suppliercode1c - External vendor ID in the system
  • suppliername - Vendor name in the system
  • customfields - additional order product fields that consist of:
    • key - additional_field_key_
    • name - custom field name
    • value - additional field value
customfields - an array of additional fields in the order, which consist of:
  • key - additional_field_key_
  • name - custom field name
  • value - additional field value


Process filtering is also available by returned fields, as well as client process fields.
You must pass a parameter equal to the name of the returned variable and a value to filter by the variable field.
For example, when passing the contactCountry = Ukraine parameter, processes will be filtered if their clients have" Ukraine".
Or when passing the parameter contractorid = 1 - processes will be filtered with a legal entity with id = 1
19 getcomments bool Get process comments Optional field. Returns an array with all process comments

Each element of the array will contain
id - id comments,
cdate - date the comment was created,
type - comment type,
content - comment text,
showtoclient - Is the comment shown to the client,
userid - id the contact who left the comment,
usercode - external contact id,
username - contact name,
useremail - email contact,
userphone - Contact phone number,
20 unescapedunicode bool Don't encode Unicode characters Optional field. If you pass 1 of this parameter in the resulting JSON, Unicode characters will not be encoded, for example, Cyrillic" а" will be passed as" а", not how" \u0430"
21 getnovaposhtastatus bool Get New Mail TTN statuses Optional field. When the value of 1 of this parameter is passed, the list of fields will additionally contain the status of the ttn and the status of the reverse ttn of New mail

Get process comments, method: /api/order/comments/get/

Parameters
Parameters for receiving one order:

Example:

http://myboxurl/api/order/comments/get/?login=LOGIN&password=PASSWORD&id=7927

JSON will be returned in response with an array of data on the comment and the author of the comment.


№ Field Type Description Required or not Comment
1 login string Login in BOX system Required field.  
2 password string Password in md5 format Required field. Contact tech support and we will give you a hash for the API
3 id string Process id Required field. ID process in OneBox. It will be used to try to find a process.
3 code string External Process ID Optional field. External process ID in OneBox. It will be used to try to find a process.
3 type array Array of comment types Optional field. Available types:
comment - Comment:
commentresult - result:
change - change:
email - letter
call - call
notify - notification

Possible responses to the request

More details
№ Status Message Message Description
1 ok orderid Returns the id of the added order
2 fail login_empty Login missing
3 fail password_empty Missing password
4 fail clientnamefirst_empty Missing customer surname
5 fail Bad user level! Low user level to perform this action (requires level 2 or higher)
6 fail Login or password not correct! Login or password entered incorrectly
7 fail orderId_empty Missing order id
8 fail Order is already! Order already exists
9 fail Not workflow status by name There is no BP status with this name
10 fail Not workflow by name There is no business process with this name
11 fail Please create Finance Account Create a financial account
12 fail Order with this Code does not found! No order found with this code
13 fail clientphone_and_clientemail_empty The customer's phone and email are missing

Errors may also occur:

502 Bad Gateway - If this error occurs it is necessary:
1. Check if you have internet access (go to any other site).
2. If there are no problems with access — cookies can be deleted.
If the above doesn't work — server side problem. Please contact your site system administrator.

503 (Service Temporarily Unavailable) - this error may occur as a result of too many server requests. If you see this error, you should wait a couple of minutes and try again.

504 Gateway Timeout - cmost likely the reason is the increased load on the site, in which Apache is not has time to send HTTP responses and new requests are queued. You can add resources to the server, in particular RAM, and increase the number of httpd (Apache) processes.
Another possible reason for error 504 is that the executable script does not fit within the allotted limit time. This happens when the request is too heavy. Try to split your request into a few more small.

Error 505 HTTP Version not supported means the website is not Supports the version of the HTTP protocol that the browser uses to request a web page
Operating system for business
Email Messenger Forum Facebook Instagram Twitter YouTube Telegram LinkedIn
Copyright © OneBox 2024