(Quick Reference)
58 Operations (Orders, Pre-orders, Invoices, Delivery notes, Deliveries) - Reference Documentation
Version: 2.1
58 Operations (Orders, Pre-orders, Invoices, Delivery notes, Deliveries)
58.1 List
Service: List operations (orders,pre-orders, invoices ,delivery notes and deliveries) Description: This web service returns a json list of operations. URL: https://BASE_URL/api/VERSION/orders Method: GET Parameters: Pagination parameters: Name | Description | Type | Required | Possible values |
---|
max | Limits the number of resources requested to return. | Integer | no | | offset | Tells where to start returning records from the entire set of results. | Integer | no | | order | Orders ascending or descending. | Integer | no | asc,desc | sort | Orders the results by the specified field. | String | no | |
The max parameter is set to 100 by default. Filters parameters:
Name | Description | Type | Required | Example values |
---|
dateCreated_gt | Filters by the resource's creation date time and operator greater than | Date | no | 2016-08-15T14:52:48Z | dateCreated_gte | Filters by the resource's creation date time and operator greater than or equal | Date | no | | dateCreated_lt | Filters by the resource's creation date time and operator less than | Date | no | | dateCreated_lte | Filters by the resource's creation date time and operator less than or equal | Date | no | | lastUpdated_gt | Filters by the resource's last-modified date time and operator greater than | Date | no | | lastUpdated_gte | Filters by the resource's last-modified date time and operator greater than or equal | Date | no | | lastUpdated_lt | Filters by the resource's last-modified date time and operator less than | Date | no | | lastUpdated_lte | Filters by the resource's last-modified date time and operator less than or equal | Date | no | | operationType | Search by the operation type | String | no | ORDER,PREORDER,INVOICE,DELIVERYNOTE,DELIVERY | reference | Wildcard search by the resource's reference | String | no | | employeeReference | Wildcard search by the resource's employee reference | String | no | employeeReference=Ref-6* , employeeReference=*ef-6 , employeeReference=*ef-6* | customerReference | Wildcard search by the resource's customer reference | String | no | customerReference=Ref-6* , customerReference=*ef-6 , customerReference=*ef-6* | deliveredByReference | Wildcard search by the resource's deliveredBy employee reference | String | no | deliveredByReference=Ref-6* , deliveredByReference=*ef-6 , deliveredByReference=*ef-6* |
Dates should be formatted as the ISO-8601 format (YYYY-MM-DDTHH:MM:SSZ)
Success Output Success case: response.status=200 {
"paging": {
"total": 702,
"max": 5,
"offset": 5,
"previous": "/api/v1.0/orders?sort=dateCreated&max=5&order=asc&operationType=ORDER&offset=0",
"next": "/api/v1.0/orders?sort=dateCreated&max=5&order=asc&operationType=ORDER&offset=10"
},
"data": [
{
"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"
}
],
"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": "2015-08-16T23: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": "invalid_param",
"error_description": "The parameters [dateCreated_gta] you provided are not valid for this request."
}
{
"error": "invalid_datetime_format",
"error_description": "Invalid datetime filter (not ISO-8601 formatted): [2016-08-1Z]"
} Failure case:response.status = 500
{
"error": "server_error",
"error_description": "Oops! Something went wrong..."
}
58.2 Show
Service: Show an operation (order, pre-order, invoice, delivery note or delivery) Description: Returns the requested operation in json format when successful. Returns a json response, describing the failure condition when unsuccessful. URL: https://BASE_URL/api/VERSION/orders/{id} URL with external_id: https://BASE_URL/api/VERSION/orders/reference/{id} Method: GET Parameters: Name | Description | Type | Required | Example values |
---|
id | The ID of the desired operation | Long/String | yes | 123 |
Success Output Success case: response.status = 200 {
"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"
}
],
"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": "invalid_param_type",
"error_description": "The type of parameter id you provided is not valid for this request."
} Failure case:response.status = 404 {
"error": "not_found",
"error_description": "The order with the id 7065 doesn't exist."
}
58.3 Create
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..."
}
58.4 Update
Service: Update an operation Description: This web service is used for changing operation status, payment details and order delivery details. URL: https://BASE_URL/api/VERSION/orders/{id} URL with external_id: https://BASE_URL/api/VERSION/orders/reference/{id} Method: POST Request content type: application/x-www-form-urlencoded or multipart/form-data Parameters: Name | Description | Type | Required | Example values |
---|
id | The ID of the desired item | Long/String | yes | 123 | status | ADVANCE status is allowed , only if user can apply partial payment | String | yes | NOT_PAID,ADVANCE,PAID,IN_PROCESS | deliveryDate | If order and isDeliveryDateMandatory | Date | - | 2016-08-15T14:52:48Z | deliveryStatus | | String | no | PENDING,DELIVERED,REJECTED | 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 | no | | bank | The bank name. It's used when payment is by CHEQUE | String | no | |
Example:
orderPayments=[{"paymentReference": "5_8_2014_09_17","paymentDate":"2014-12-20T23:00:00Z","paymentTypeId":8,"chequeImage":checkFile}] Add checkFile parameter to upload image file
$ curl -i -H "Content-Type: multipart/form-data" -X POST -F 'checkFile=<@filename>;type=<mime type>' <url>
Prepayments parameter: Parameter name: orderPayments 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 | |
Example:
prepaymentPayment=[{"prepaymentId": 524,"amountToCredit":8}] Success Output Success case: response.status=200 {
"id": 5,
"operationType": "ORDER",
"reference": "marie_order_2014_12_20",
"status": "PAID",
"latitude": 29.932,
"longitude": 12.101,
"checkInDate": null,
"total": 155,
"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": 908,
"reference": "5_8_2014_12_20",
"href": "/api/v1.0/orderPayments/908"
}
],
"orderPrepayments": [
{
"id": 252,
"reference": "L-aa-1505382365189",
"href": "/valomniav2/api/v2.1/orderPayments/252"
}
],
"dueDate": null,
"customerReference": "cust_A6",
"customer": {
"id": 5,
"reference": "cust_A6",
"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": "Delivered on 20/12/2014",
"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": "2015-08-16T23: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": "missing_param",
"error_description": "advanceAmount parameter is missing"
}
{
"error": "unsupported_file_type",
"error_description": "image format not supported."
}
{
"error": "invalid_paid_amount",
"error_description": "The sum of amounts should be equal to the total."
}
{
"error": "invalid_advance_amount",
"error_description": "The sum of advance amounts can not exceed the total amount of the order."
}
Failure case:response.status = 404 {
"error": "not_found",
"error_description": "The order with the id 5 doesn't exist."
}
{
"error": "not_found",
"error_description": "The payment type with the id 8000 doesn't exist."
}
58.5 Delete
Service: Delete an operation (order,pre-order, invoice or delivery note) Description: Returns a json response. URL: https://BASE_URL/api/VERSION/orders/{id} URL with external_id: https://BASE_URL/api/VERSION/orders/reference/{id} Method: DELETE Parameters: Name | Description | Type | Required | Example values |
---|
id | The ID of the desired operation | Long/String | yes | 123 |
Success Output Success case: response.status=200 {
"success": "true",
"success_description": "Instance deleted successfully"
}
Failure Output Failure case:response.status = 400 {
"error": "delete_failed",
"error_description": "Failed to delete instance."
} Failure case:response.status = 404 {
"error": "not_found",
"error_description": "The order with the id 706 doesn't exist."
}
|
|