Quotes: Validation Rules
When a sales order is created or modified, validation will be performed on several fields. If any of these validations fail, then the API will return an HTTP-400 response.
All validation from the Transactions domain applies, which is covered by the Transactions documentation.
Configuration settings for quotes are stored in the "quotes.config" database table. There is no API or GUI to update the config; it will be done by manually updating the data in the database.
Quote Expiry Date
When a quote is created, if the expiry date is not specified then the API will assign it automatically. The expiry date will be set to today + "Default quote validity days". For example, if today is "2017-11-01" and "Default quote validity days" is 14, then the expiry date will be set to "2017-11-15".
"Default quote validity days" is defined in the Quotes config table.
Field Validations
The "Quote field validations" config is a pipe delimited value that contains all of the fields that should be validated. Only site_code, person_code, and product_code can be validated. Example values of the "Quote field validations" config are:
- "site_code|person_code|product_code". This would mean to validate all three fields.
- "none". Do not perform validation on any of the fields.
- "site_code|product_code". Perform validation on site_code and product_code.
- "person_code". Only validate person_code.
|
Field |
Validation |
|---|---|
|
site_code |
Checks that the specified site exists. Validate only if the value of the "Quote field validations" config includes "site_code". |
|
person_code |
Checks that the specified Person exists. Validate only if the value of the "Quote field validations" config includes "person_code". |
|
product_code |
Checks that the specified Product exists. Validate only if the value of the "Quote field validations" config includes "product_code". |
Search Dates
When specifying the dates in the search criteria the FROM date starts at 00:00 in the morning and the TO date ends at 23:99; e.g:
"expiry_date" : {
"date_from" : "2017-11-22",
"date_to" : "2017-11-23"
For the above it will search for all quotes between 2017-11-22 00:00:00 and 2017-11-23 23:99:99.
Quote Versioning
Once a quote has been updated, it is distributed to stores and any application that contains quote functionality. Because the data is distributed, there is the potential for the quote to be updated in more than one place. The API maintains a quote version for each quote to ensure that the calling application is working with the most recent version of that quote and line.
Quotes can be created and updated via the POST endpoint. If a new quote is being created, then the quote_version and line_versions must be blank. If an existing quote is being updated, then the quote_version and line_verisons must be provided.
When a quote is created via POST, the API will assign a quote version, which will be included in the response as the quote_version property. When a quote is updated via PUT, the caller must include the quote_version in the request. If the quote_version that is supplied does not match the current version of the quote then the call will be rejected with an HTTP-400 error. If the quote_version matches and all other validation passes, the quote will be updated and the API will respond with a new quote_version and line_version.
If an update is rejected, the client may retrieve the new version of the quote and present the user with the information required to resolve the issue and re-submit their request.
Example:
|
Action |
Client 1 |
Client 2 |
API |
|---|---|---|---|
|
Salesperson talks to customer and creates a quote. |
Creates a new quote. |
|
Quote is created, responds with quote_version of: 1 |
|
|
|
Retrieves the new quote. |
|
|
Salesperson updates the quote to add some internal notes. |
Updates the quote specifying quote version: 1 |
|
Quote is updated, responds with new quote version of: 2 |
|
Customer calls the store and says that they would like to change the product that is on the quote. |
|
Updates the quote specifying quote version: 1 |
Request is rejected as the quote has changed and the update may be inconsistent. |
|
|
|
Retrieve the quote updates, including the new quote version. |
|
|
Salesperson resolves the issue and updates the product on the quote. |
|
Updates the quote specifying quote version: 2 |
Quote is updated, responds with new quote version of: 3 |
Attachments
When an attachment is added to a quote, the API will validate that the quote does not already have an attachment with the same filename.