(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:

NameDescriptionTypeRequiredPossible values
maxLimits the number of resources requested to return.Integerno 
offsetTells where to start returning records from the entire set of results.Integerno 
orderOrders ascending or descending.Integernoasc,desc
sortOrders the results by the specified field.Stringno 

The max parameter is set to 100 by default.

Filters parameters:

NameDescriptionTypeRequiredExample values
dateCreated_gtFilters by the resource's creation date time and operator greater thanDateno2016-08-15T14:52:48Z
dateCreated_gteFilters by the resource's creation date time and operator greater than or equalDateno 
dateCreated_ltFilters by the resource's creation date time and operator less thanDateno 
dateCreated_lteFilters by the resource's creation date time and operator less than or equalDateno 
lastUpdated_gtFilters by the resource's last-modified date time and operator greater thanDateno 
lastUpdated_gteFilters by the resource's last-modified date time and operator greater than or equalDateno 
lastUpdated_ltFilters by the resource's last-modified date time and operator less thanDateno 
lastUpdated_lteFilters by the resource's last-modified date time and operator less than or equalDateno 
operationTypeSearch by the operation typeStringnoORDER,PREORDER,INVOICE,DELIVERYNOTE,DELIVERY
referenceWildcard search by the resource's referenceStringno 
employeeReferenceWildcard search by the resource's employee referenceStringnoemployeeReference=Ref-6* , employeeReference=*ef-6 , employeeReference=*ef-6*
customerReferenceWildcard search by the resource's customer referenceStringnocustomerReference=Ref-6* , customerReference=*ef-6 , customerReference=*ef-6*
deliveredByReferenceWildcard search by the resource's deliveredBy employee referenceStringnodeliveredByReference=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:

NameDescriptionTypeRequiredExample values
idThe ID of the desired operationLong/Stringyes123

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:

NameDescriptionTypeRequiredExample values
reference Stringyes 
operationType StringyesORDER,PREORDER,INVOICE,DELIVERYNOTE,DELIVERY
statusADVANCE status is allowed , only if user can apply partial paymentStringyesNOT_PAID,ADVANCE,PAID,IN_PROCESS
customerIdThe numerical ID of customerLong/Stringyes 
userIdThe numerical ID of user. By default, it is set to the current connected userLong/Stringno 
total Doubleyes 
totalExclTax Doubleyes 
totalDiscounted Doubleyes 
discountOnly if user can apply discount percentDoubleno 
taxAmountThis attribute is used for invoiceDoubleno 
currencyISO code of configured currency. By default, it is set as the organization currency.StringnoEUR
exchangeRateIf exchange rate is not provided, it will be set as configured in currencies.Doubleno 
pdfFilePDF size must be lower than 10 MBpdfno 
deliveryDateRequired if order and isDeliveryDateMandatory is activatedDate-2016-08-15T14:52:48Z
deliveryStatus StringnoPENDING,DELIVERED,REJECTED
dueDateUsed for invoice. If due date is not provided, it will be set as configured in customer form.Dateno2016-08-15
latitude DoubleNo12.914
longitude DoubleNo14.99
checkInDate StringNo2016-04-12T19:30:48Z
billingCountryISO country code or a valid countryStringnoFR,France
billingCity Stringno 
billingPostalCode Stringno 
billingAddress Stringno 
deliveryCountryISO country code or a valid countryStringnoTN, Tunisia
deliveryCity Stringno 
deliveryPostalCode Stringno 
deliveryAddress Stringno 
deliveredByThe numerical ID of delivery manLong/Stringyes 
desiredDeliveryDate StringNo2016-04-12T19:30:48Z
deliveredOn StringNo2016-05-12T19:30:48Z
shippingFeeIf shipping fee is not provided, it will be set as configured in employee config.DoubleNo19.5
useExternalIdBy default, it is set to false. set it to true if you want to use external ids.Booleannotrue , 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
NameDescriptionTypeRequiredExample values
paymentDate Dateno2016-08-15T14:52:48Z
paymentTypeIdThe numerical ID of payment typeIntegerno 
advanceAmountRequired if status is ADVANCEDoubleno 
desiredPaymentDateUsed when payment is by CHEQUEDateno2016-08-15
chequeImageName of image parameter to upload. It's used when payment is by CHEQUEStringyes 
bankThe bank name. It's used when payment is by CHEQUEStringno 

Prepayments parameter:

Parameter name: orderPrepayments

Parameter type: a json structure

Prepayments are accepted only if operation type is equal to ORDER

NameDescriptionTypeRequiredExample values
prepaymentIdThe ID of prepaymentLong/Stringyes 
amountToCredit Doubleyes 

Order lines parameter:

Parameter name: orderLines

Parameter type: a json structure

NameDescriptionTypeRequiredExample values
itemUnitIdThe numerical ID of item-unitIntegeryes 
quantity Integeryes 
type StringnoREGULAR,GIFT,ASSET
tax Doubleno 
discountOnly if user can apply discountDoubleno 
customerDiscount Doubleno 
finalPrice Doubleyes 
unitPrice Doubleyes 
comment Stringno 
serialNumbersList of serial numbers idJSON listno[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:

NameDescriptionTypeRequiredExample values
idThe ID of the desired itemLong/Stringyes123
statusADVANCE status is allowed , only if user can apply partial paymentStringyesNOT_PAID,ADVANCE,PAID,IN_PROCESS
deliveryDateIf order and isDeliveryDateMandatoryDate-2016-08-15T14:52:48Z
deliveryStatus StringnoPENDING,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
NameDescriptionTypeRequiredExample values
paymentDate Dateno2016-08-15T14:52:48Z
paymentTypeIdThe numerical ID of payment typeIntegerno 
advanceAmountRequired if status is ADVANCEDoubleno 
desiredPaymentDateUsed when payment is by CHEQUEDateno2016-08-15
chequeImageName of image parameter to upload. It's used when payment is by CHEQUEStringno 
bankThe bank name. It's used when payment is by CHEQUEStringno 

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

NameDescriptionTypeRequiredExample values
prepaymentIdThe ID of prepaymentLong/Stringyes 
amountToCredit Doubleyes 

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:

NameDescriptionTypeRequiredExample values
idThe ID of the desired operationLong/Stringyes123

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."
}