Skip to main content

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/order

Creates 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 OPTIONAL

Identifier or code of a product in the purchase order.

Example values: 3105, SKU-845-G54


imageSTRING OPTIONAL

URL of the product's main image.

Example values: https://domain.com/images/products/product/product_image.jpg


nameSTRING REQUIRED

Product name.

Example values: Facial cream


descriptionTEXT OPTIONAL

Product description.

Example values: This is the facial cream description


quantityINTEGER REQUIRED

Quantity of the product in the purchase order.

Example values: 1, 5


priceDECIMAL REQUIRED

Product price

Example values: 2990, 39000.00, 0.99


unit_priceBOOLEAN OPTIONAL

Whether 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 REQUIRED

Currency used in the purchase order.

Possible values: CLP, USD, EUR


include_taxBOOLEAN OPTIONAL

Defines whether the product price includes tax or not.

Possible values: true, false

DEFAULT true


discount_typeCHAR OPTIONAL

Defines whether the product discount is a percentage or an absolute amount.

Possible values: percent amount

DEFAULT amount


discountDECIMAL OPTIONAL

Discount 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[] OPTIONAL

Variants of the product in the purchase order.

DEFAULT []

Show properties
nameSTRING REQUIRED

Name of the product variant.

Example values: Size, Dimensions, Volume


valueSTRING REQUIRED

Value of the product variant.

Example values: Black, XL, 30cm x 30cm, 30ml


categoriesARRAY[] OPTIONAL

Product categories.

DEFAULT []

Show properties
categoriesARRAY OPTIONAL

Array of the categories the product may belong to.

Example values: [Atención Online, Bussines]


Parameter Example​

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​

PUT /sessions/OCULAR_SESSION_ID/order

Creates 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​

params
{
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/order

View 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​

Create or update a purchase order
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)
})