Purchase Orders JavaScript API
This section details the Purchase Orders JavaScript API used to integrate with the create and update services provided by the purchase order API, through the Ocular Solution video support widget:
Create or edit a purchase order
This method sends the data needed to generate a purchase order. It receives an object as its main parameter, which is described in the following section.
ocularOrderTrack.setBuyOrder(params)
Parameters
params
OBJECT[]
REQUIRED
Show properties
external_idSTRING OPTIONALIdentifier or code of the purchase order.
Example values: 1015, ORDER-8454
itemsOBJECT[] REQUIREDList of the products that belong to the purchase order.
Show properties
external_idSTRING OPTIONALIdentifier or code of a product in the purchase order.
Example values: 3105, SKU-845-G54
imageSTRING OPTIONALURL of the product's main image.
Example values: https://domain.com/images/products/product/product_image.jpg
nameSTRING REQUIREDProduct name.
Example values: Facial cream
descriptionTEXT OPTIONALProduct description.
Example values: This is the facial cream description
quantityINTEGER REQUIREDQuantity of the product in the purchase order.
Example values: 1, 5
priceDECIMAL REQUIREDProduct price
Example values: 2990, 39000.00, 0.99
unit_priceBOOLEAN OPTIONALWhether the product price sent is the unit price or the total price.
The price is calculated as follows:
true: price = price * quantity
false: price = price
Possible values: true, false.
DEFAULT false
currencySTRING REQUIREDCurrency used in the purchase order.
Possible values: CLP, USD, EUR
include_taxBOOLEAN OPTIONALDefines whether the product price includes tax or not.
Possible values: true, false
DEFAULT true
discount_typeCHAR OPTIONALDefines whether the product discount is a percentage or an absolute amount.
Possible values: percent amount
DEFAULT amount
discountDECIMAL OPTIONALDiscount applied to the product.
Example values: 1990.00 (amount) 5.00 (percent = 5%) 30.00 (percent = 30%) 25.50 (percent = 25.5%)
DEFAULT 0.00
variantsOBJECT[] OPTIONALVariants of the product in the purchase order.
DEFAULT []
Show properties
nameSTRING REQUIREDName of the product variant.
Example values: Size, Dimensions, Volume
valueSTRING REQUIREDValue of the product variant.
Example values: Black, XL, 30cm x 30cm, 30ml
categoriesARRAY[] OPTIONALProduct categories.
DEFAULT []
Show properties
categoriesARRAY OPTIONALArray of the categories the product may belong to.
Example values: [Atención Online, Bussines]
Parameter Example
const params = {
external_id: 'ORDER-8454',
items: [
{
external_id: 'SKU-845-G54',
image: 'https://domain.com/images/products/product/product_image.jpg',
name: 'Product name', // Required
description: 'Product description',
quantity: 2, // Required
include_tax: true,
unit_price: false,
discount_type: 'amount',
discount: 2990.00,
currency: 'CLP', // Required
price: 10000.00, // Required
variants: [
{
name: 'Color', // Required
value: 'Black' // Required
},
{
name: 'Size', // Required
value: 'XL' // Required
},
{
name: 'Dimensions', // Required
value: '30cm x 30cm' // Required
}
],
categories: ["Atención Online", "Bussines"] // Optional
},
]
}
Service responses
Successful response
{
statusCode: 0,
message: 'Success'
}
Failed response
{
statusCode: 1,
message: 'Error 500 - Internal server error'
}
Response with validation errors
{
statusCode: 2,
message: 'Field validation error',
detail: {
field_one: [
'SessionOrderControllerValidator: field_one is required.',
'SessionOrderControllerValidator: field_one must be an integer.',
...
],
field_two: [
'SessionOrderControllerValidator: field_two is required.',
'SessionOrderControllerValidator: field_two must be a string.',
'SessionOrderControllerValidator: field_two exceeds the maximum number of characters :max.',
...
],
...
}
}
Update the state of an order
This method updates the status of a purchase order. It receives an object as its main parameter.
ocularOrderTrack.setBuyOrderState(params)
Parameters
params
OBJECT
REQUIRED
Show properties
external_idSTRING OPTIONALIdentifier or code of the purchase order.
Example values: ORDER-8454
payment_statusINTEGER REQUIREDPayment status of the purchase order.
Allowed values: 0 (success), 1 (declined)
Parameter example
const params = {
external_id: 'SKU-845-G54',
payment_status: 0
}
ocularOrderTrack.setBuyOrderState(params)
Service responses
Successful response
{
statusCode: 0,
message: 'Success'
}
Failed response
{
statusCode: 1,
message: 'Error 500 - Internal server error'
}
Response with validation errors
{
statusCode: 2,
message: 'Field validation error',
detail: {
field_one: [
'SessionOrderControllerValidator: field_one is required.',
'SessionOrderControllerValidator: field_one must be an integer.',
...
],
field_two: [
'SessionOrderControllerValidator: field_two is required.',
'SessionOrderControllerValidator: field_two must be a string.',
...
],
...
}
}
Example: update a purchase order
- javascript
const params = {
external_id: 'ORDER-8454',
items: [
{
external_id: 'SKU-845-G54',
image: 'https://domain.com/images/products/product/product_image.jpg',
name: 'Product name',
description: 'Product description',
quantity: 2,
include_tax: true,
unit_price: false,
discount_type: 'amount',
discount: 2990.00,
currency: 'CLP',
price: 10000.00,
variants: [
{
name: 'Color',
value: 'Black'
},
{
name: 'Size',
value: 'XL'
},
{
name: 'Dimensions',
value: '30cm x 30cm'
}
]
},
]
}
ocularOrderTrack.setBuyOrder(params)