Purchase orders
Purchase orders are what make it possible to integrate the sales commission services. Use the Product Management API calls to manage your orders with Ocular.
This section details how to call the create and update services
for a purchase order. This module is an add-on to the Ocular Solution
video support widget, which is configured to automatically deliver
an input in your cart update forms during a video support session:
<input type="hidden" name="ocular_session_id" value="1536">
The purpose of this additional input is to track the agent's sale by passing the
video session identifier parameter ocular_session_id.
Create or update an order
POST /sessions/OCULAR_SESSION_ID/orderCreates or updates a purchase order.
Endpoint
https://api.ocularsolution.com/api/product-management/v1/sessions/{ocular_session_id}/order
Parameters
external_id
STRING
OPTIONAL
Identifier or code of the purchase order.
Example values: 1015, ORDER-8454
items
OBJECT[]
REQUIRED
List 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
{
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
PUT /sessions/OCULAR_SESSION_ID/orderCreates or updates a purchase order.
Endpoint
https://api.ocularsolution.com/api/product-management/v1/sessions/{ocular_session_id}/order
Parameters
external_id
STRING
OPTIONAL
Identifier or code of the purchase order.
Example values: ORDER-8454
payment_status
INTEGER
REQUIRED
Payment status of the purchase order.
Example values: 0 (success), 1 (declined)
Parameter example
{
external_id: 'SKU-845-G54',
payment_status: 0
}
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.',
...
],
...
}
}
View purchase order details
GET /sessions/OCULAR_SESSION_ID/orderView the purchase order details for the session.
Endpoint
https://api.ocularsolution.com/api/product-management/v1/sessions/{ocular_session_id}/order
Parameters
ocular_session_id
INTEGER
REQUIRED
Purchase order details for the session.
The parameter must be sent in the URL.
Example values: 1
Service responses
Successful response
{
statusCode: 0,
message: 'Sucess',
sessionOrder: {
id: 4,
session_id: 1,
external_id: 'ORDER-8454',
session_order_state_id: 2,
session_order_state: {
id: 2,
name: 'Pagada',
description: null
},
session_order_items: [
{
id: 7,
session_order_id: 4,
item_id: 7,
unit_of_measurement_id: 2,
quantity: '2',
unit_price: false,
price: '10000.00',
discount_type: 'amount',
discount: '2990.00',
include_tax: true,
tax_value: '10.0',
currency: 'CLP',
unit_of_measurement: {
id: 2,
name: 'Unidad',
description: null
},
item: {
id: 7,
name: 'Product name',
image: 'https://domain.com/images/products/product/product_image.jpg',
description: 'Product description',
stock: 1,
item_state_id: 2,
organization_id: 1,
brand_id: null,
external_id: 'SKU-845-G54',
item_state: {
id: 2,
name: 'Sin stock',
description: null
},
item_attrs: [
{
id: 19,
item_id: 7,
name: 'Color',
value: 'Black'
},
{
id: 20,
item_id: 7,
name: 'Size',
value: 'XL'
},
{
id: 21,
item_id: 7,
name: 'Dimensions',
value: '30cm x 30cm'
}
],
brand: null
}
}
]
}
}
}
Failed response
{
statusCode: 1,
message: 'Error 500 - Internal server error'
sessionOrder: null
}
Example: update a purchase order
- Node.js
import axios from 'axios'
const baseURL: 'https://api.ocularsolution.com/api/product-management/v1'
const ocularSessionId = 1654653
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'
}
]
},
]
}
axios.post(`${baseURL}/sessions/${ocularSessionId}/order`, params)
.then(response => {
console.log(response)
})
.catch(error => {
console.log(error)
})