(Quick Reference)
Service: Create an operation (order,pre-order,invoice ,delivery note and delivery)
Description: Returns the created operation in json format when successful. Returns a json response, describing the failure condition when unsuccessful.
URL:
https://BASE_URL/api/VERSION/orders
Method: POST
Request content type: application/x-www-form-urlencoded or multipart/form-data
Parameters:
Name | Description | Type | Required | Example values |
---|
reference | | String | yes | |
operationType | | String | yes | ORDER,PREORDER,INVOICE,DELIVERYNOTE,DELIVERY |
status | ADVANCE status is allowed , only if user can apply partial payment | String | yes | NOT_PAID,ADVANCE,PAID,IN_PROCESS |
customerId | The numerical ID of customer | Long/String | yes | |
userId | The numerical ID of user. By default, it is set to the current connected user | Long/String | no | |
total | | Double | yes | |
totalExclTax | | Double | yes | |
totalDiscounted | | Double | yes | |
discount | Only if user can apply discount percent | Double | no | |
taxAmount | This attribute is used for invoice | Double | no | |
currency | ISO code of configured currency. By default, it is set as the organization currency. | String | no | EUR |
exchangeRate | If exchange rate is not provided, it will be set as configured in currencies. | Double | no | |
pdfFile | PDF size must be lower than 10 MB | pdf | no | |
deliveryDate | Required if order and isDeliveryDateMandatory is activated | Date | - | 2016-08-15T14:52:48Z |
deliveryStatus | | String | no | PENDING,DELIVERED,REJECTED |
dueDate | Used for invoice. If due date is not provided, it will be set as configured in customer form. | Date | no | 2016-08-15 |
latitude | | Double | No | 12.914 |
longitude | | Double | No | 14.99 |
checkInDate | | String | No | 2016-04-12T19:30:48Z |
billingCountry | ISO country code or a valid country | String | no | FR,France |
billingCity | | String | no | |
billingPostalCode | | String | no | |
billingAddress | | String | no | |
deliveryCountry | ISO country code or a valid country | String | no | TN, Tunisia |
deliveryCity | | String | no | |
deliveryPostalCode | | String | no | |
deliveryAddress | | String | no | |
deliveredBy | The numerical ID of delivery man | Long/String | yes | |
desiredDeliveryDate | | String | No | 2016-04-12T19:30:48Z |
deliveredOn | | String | No | 2016-05-12T19:30:48Z |
shippingFee | If shipping fee is not provided, it will be set as configured in employee config. | Double | No | 19.5 |
useExternalId | By default, it is set to false. set it to true if you want to use external ids. | Boolean | no | true , false |
latitude
and longitude
must have a valid value otherwise, they will be considered as null
Delivery parameters are saved only for pre-order and order and delivery operation
A delivery note use the same attributes used for an invoice except those two ; taxAmount
and dueDate
deliveredBy parameter is required only for delivery operation
If delivery and billing address parameters are not provided, they will be set as the customer address.
Payments parameter:
Parameter name: orderPayments
Parameter type: a json structure
Payments parameter is mandatory if order status is equal to ADVANCE or PAID
Name | Description | Type | Required | Example values |
---|
paymentDate | | Date | no | 2016-08-15T14:52:48Z |
paymentTypeId | The numerical ID of payment type | Integer | no | |
advanceAmount | Required if status is ADVANCE | Double | no | |
desiredPaymentDate | Used when payment is by CHEQUE | Date | no | 2016-08-15 |
chequeImage | Name of image parameter to upload. It's used when payment is by CHEQUE | String | yes | |
bank | The bank name. It's used when payment is by CHEQUE | String | no | |
Prepayments parameter:
Parameter name: orderPrepayments
Parameter type: a json structure
Prepayments are accepted only if operation type is equal to ORDER
Name | Description | Type | Required | Example values |
---|
prepaymentId | The ID of prepayment | Long/String | yes | |
amountToCredit | | Double | yes | |
Order lines parameter:
Parameter name: orderLines
Parameter type: a json structure
Name | Description | Type | Required | Example values |
---|
itemUnitId | The numerical ID of item-unit | Integer | yes | |
quantity | | Integer | yes | |
type | | String | no | REGULAR,GIFT,ASSET |
tax | | Double | no | |
discount | Only if user can apply discount | Double | no | |
customerDiscount | | Double | no | |
finalPrice | | Double | yes | |
unitPrice | | Double | yes | |
comment | | String | no | |
serialNumbers | List of serial numbers id | JSON list | no | [750,711] |
Serial numbers parameter is only used in delivery note or invoice operations
Serial numbers should be saved in the stock of the employee's van
Success Output
Success case: response.status=201
{
"id": 5,
"operationType": "ORDER",
"reference": "marie_order_2014_12_20",
"status": "PAID",
"latitude": 29.932,
"longitude": 12.101,
"checkInDate": null,
"total": 1572,
"totalExclTax": 1572,
"totalDiscounted": 1572,
"discount": null,
"taxAmount": null,
"shippingFee": 7,
"paymentDate": "2014-12-20T23:00:00Z",
"paymentTypeId": 8,
"paymentType": {
"id": 8,
"reference": "CHEQUE",
"name": "Cheque",
"href": "/api/v1.0/paymentTypes/8"
},
"advanceAmount": null,
"orderPayments": [
{
"id": 5,
"reference": "5_8_2014_12_20",
"href": "/api/v1.0/orderPayments/5"
}
],
"orderPrepayments": [
{
"id": 252,
"reference": "L-aa-1505382365189",
"href": "/valomniav2/api/v2.1/orderPayments/252"
}
],
"dueDate": null,
"customerReference": "C0959",
"customer": {
"id": 5,
"reference": "C0959",
"reference2": null,
"name": "Marie's Jewelry",
"href": "/api/v1.0/customers/5"
},
"currency": "EUR",
"exchangeRate": 1,
"employeeReference": "emp-04",
"user": {
"id": 4,
"reference": "emp-04",
"href": "/api/v1.0/users/4"
},
"billingCountry": null,
"billingCity": null,
"billingPostalCode": null,
"billingAddress": null,
"deliveryStatus": "DELIVERED",
"deliveryDate": "2014-12-20T23:00:00Z",
"deliveryComment": null,
"deliveryCountry": "FR",
"deliveryCity": "Paris",
"deliveryPostalCode": null,
"deliveryAddress": null,
"orderLines": [
{
"id": 5,
"href": "/api/v1.0/orderDetails/5"
}
],
"pdfUrl": "https://BASE_URL/entity1-1450169988465/orderPDF/4_marie_order_2014_12_20.pdf",
"organization": "entity1",
"dateCreated": "2014-12-20T23:00:00Z",
"lastUpdated": "2014-12-20T23:00:00Z",
"deliveredBy": {
"id": 5,
"reference": "emp-06",
"href": "/api/v1.0/users/5"
},
"desiredDeliveryDate" : "2015-08-16T23:00:00Z",
"deliveredOn" : "2015-05-18T21:00:00Z",
"assignmentDate" : "2015-03-21T23:00:00Z"
}
Failure Output
Failure case:response.status = 400
{
"error": "save_failed",
"error_description": "Failed to save instance."
}
{
"error": "not_unique",
"error_description": "reference already used"
}
{
"error": "invalid_param_type",
"error_description": "An invalid value was specified for parameter: totalDiscounted (must be positive)"
}
{
"error": "date_validation_error",
"error_description": "Failed to add the Order with the reference little_shop_order_1: paymentDate incorrect Date Format"
}
{
"error": "not_in_list_error",
"error_description": "Failed to add the Order with the reference little_shop_order_1: operationType can have only these values [ ORDER,PREORDER,INVOICE,DELIVERYNOTE,DELIVERY ]"
}
{
"error": "not_in_list_error",
"error_description": "Failed to add the Order with the reference little_shop_order_1: status can have only these values [ NOT_PAID,ADVANCE,PAID,IN_PROCESS ]"
}
{
"error": "not_in_list_error",
"error_description": "Failed to Add the Order with the reference little_shop_order_1: type can have only these values [ REGULAR,GIFT ]"
}
{
"error": "invalid_param_type",
"error_description": "An invalid value was specified for parameter: quantity (must be an Integer)"
}
{
"error": "invalid_param_type",
"error_description": "An invalid value was specified for parameter: unitPrice (must be a Double)"
}
{
"error": "credit_limit_exceeded",
"error_description": "The customer credit limit has been exceeded."
}
{
"error": "can_not_apply_discount",
"error_description": "The user can not apply discount."
}
{
"error": "quantity_not_available",
"error_description": "Quantity should be less than or equal to the available quantity: [[quantity:16944, item:497, unit:1, itemUnit:2]]"
}
{
"error":"invalid_datetime_format",
"error_description": "Invalid datetime format for checkInDate it must be in this format : YYYY-MM-DDTHH:MM:SSZ"
}
{
"error": "invalid_param_type",
"error_description": "The type of parameter serial number id you provided is not valid for this request."
}
{
"error": "invalid_serial_number",
"error_description": "The number of serial codes should be equal to the quantity intended to be sold"
}
{
"error": "invalid_param_type",
"error_description": "An invalid value was specified for parameter: exchangeRate (must be a Double)"
}
Failure case:response.status = 404
{
"error": "not_found",
"error_description": "The Customer with the id 10 doesn't exist."
}
{
"error": "not_found",
"error_description": "The payment type with the id 8000 doesn't exist."
}
{
"error": "not_found",
"error_description": "The User with the id 1 doesn't exist."
}
{
"error": "not_found",
"error_description": "The User (deliveredBy) with the id 20 doesn't exist."
}
{
"error": "not_found",
"error_description": "The serial number with the id 616 doesn't exist."
}
{
"error": "not_found",
"error_description": "The currency with name IN doesn't exist."
}
{
"error": "not_found",
"error_description": "The currency with name INR is not configured."
}
Failure case:response.status = 500
{
"error": "server_error",
"error_description": "Oops! Something went wrong..."
}