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

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