The quote object in our Rest API provides a way for other systems to access quotes, invoke actions on them, edit their products, and access attachments within the quote and its child quote products.
Overview
A quote object is very detailed. You'll find not only summary information about its general price and cost, but all specific information about its quote products, including the field values of any configured products in the quote. Likewise, the authenticated API user querying this object can also make changes to these details, if access has been granted.
Retrieving the Quote
Calling GET https://subdomain.kbmax.com/api/quotes/[id] gives you all details about the quote: not only the quote header information, but also details about the list of products within it.
Certain visual details about the quote product, including validation, which fields were enabled or visible, and other information that's specific to the UI are not included.
Accessing Configured Product Field Values
Once you have a handle to a particular quote, you can also access the quote's product list via quote.products. If the quote product is configured (product.isConfigured), its configuredProduct provides details about that configuration.
Accessing File Attachments in the Quote
Quotes can have attachments: either files your customer has placed into a file upload field while filling out the configurator form, or files an output builder has created during the workflow process. These attachments are not associated with the quote. They are associated with one of the QuoteProducts within the quote.
- Determine the ID of the quote you need, either through a search or by having that ID already from a previous process. For example, we want an attachment from the first product in quote ID 61.
- Use the GetByID API call to get the quote, such as
https://your-domain.kbmax.com/api/quotes/61 - Given that quote, loop through the Files array. You can see the ID of each attached file. To continue the example, we may see an attachment of file ID 76 in the first product of quote ID 61.
- Use the Download API call to get the file itself, including the binary data of that file, such as
https://training-dev.kbmax.com/api/quotes/productfile/download/76 - Now, with the binary data of the attachment on your own server, you can commit the file to a repository, pass the file and other information to your mail server to compose an email message, or other business tasks.
Editing the Quote
If you are making changes to information about the quote itself, such as its name, discount, customer, etc., you can make the changes by calling PUT https://subdomain.kbmax.com/api/quotes/[id] with the entire quote object in the request body.
Editing a Quote Product
If you only wish to edit a product within a quote, you can call PUT https://subdomain.kbmax.com/api/quotes/[quoteId]/product/[quoteProductId] with the product data in the request body.
If you are making changes to a quote that is within a workflow, performing these changes will invoke whatever actions are defined for the state this quote is in. For example, if the quote has the "change customer" action defined for a state which advances the quote to another state, then changing that customer's details via the API will also advance the quote to another state.
Invoking Custom Actions for a Quote
Custom actions can also manipulate the quote's advancement through a workflow. A common scenario is having an external system wish to invoke actions which will advance the quote to another state within a workflow. You can perform these actions by calling POST https://subdomain.kbmax.com/api/quotes/custom with an object in the request body which has an idQuote property and idCustomAction property.
For the full list of web service calls, see the full API documentation.