SIRCLO API

version: 1.2

Table of Contents
Creating Access T oken
General Request & Response Format
Request Format
Response Format
Products
Get Products
Examples
Query single e xisting product
Request
Response
Query all with paging
Request
Response
Create Product
Examples
Request
Response
Update Pr oduct
Delete Product
Update Stock/T otal Inventory of Batch Pr oducts
Examples
Request
Response
Orders
Get Orders
Examples
Query single e xisting order
Request
Response
Query all with paging
Request
 Response
Create Order
Examples
Request
Response
Update Or der
Delete Order

Creating Access Token

To be able to call API from a SIRCLO shop, you need an access token, which can be created manually from
our secret admin panel URI:

<your shop id>.mysirclo.com/admin/content/api_accesses

You will then be greeted with the following page:

API Accesses Admin Panel Page

Press "New API Access" button to create a new access token and ll the appearing form:
 New API Access Form

The important elds are "Access Token" and "Scopes", other elds are for reference purpose only, so you
know which this token belongs to or intended for. "Access Token" is what you will need to pass in every
request, the value is up to you. While "Scopes" are what this token may access, a comma separated value
consisting of one or more of:

products_read (R)
products_write (CUD)
batch_products (CUD)
orders_read (R)
orders_write (CUD)

please don't use space around the comma, so:

products_read,products_read (&#9989;)
products_read, products_read (&#10060;)

Press "Save" button to create the access token.

General Request & Response Format

Request Format
All endpoints are relative to the shop base URL, e.g.: if your shop is myshop.com and you want to access get
products, the URL will be:

myshop.com/api/products

All requests must pass the following header:

X-Sirclo-Access-Token: <access token>

where <access token> is the access token you just made in previous step. Other than that, everything
else is plain REST API call, where CRUD operation is determined from the HTTP method.

(C) POST (R) GET (U) PUT/POST (D) DELETE

due to diculty in implementation, some update endpoints use POST instead of PUT.

Response Format
Response is always a JSON structure, with the always guaranteed to exist key is status , which can be 2XX /
4XX / 5XX. any other elds is up to each endpoint:

{
"status" : 200
}

Failing to give access token so or giving incorrect/inexistent access token will result in the following
response:

{
"status" : 401,
"message" : "Unauthorized"
}

While giving a correct access token without required permission will result in:

{
"status" : 403,
"message" : "Insufficient Permission"
}

When it comes to RUD, but the corresponding object is not found, the general response is:

{
"status" : 404,
"message" : "Not Found"
}

However, the message value can be dier up to the respective endpoint.

Products
Get Products
Get a list of products or a single product if <id> is specied. <id> is the internal product id.

Method: GET

Endpoint: /api/products/[<id>]

Parameters (all optional):

brand
type: string
description: get products having this brand only

sale
type: integer
description: if truthy (other than 0), get only sale products

min_price
type: integer
description: get products with price higher than or equal to this value

max_price
type: integer
description: get products with price lower than or equal to this value

sort
type: enum (product_code, title, price, date_added)
description: get products sorted by this eld

desc

type: boolean

description: if truthy (other than 0), get products sorted descendingly,

otherwise ascendingly

query
type: string

description: get products containing this value in their title or

specification field

page:
type: integer
description: get only products on this page

items_per_page
type: integer

description: get this number of products per page, use in conjunction with

page parameter
Examples

Query single e xisting pr oduct

Request

curl -H "X-Sirclo-Access-Token: my -access-token" http://myshop.mysirclo.com/api/products/255

Response
{
"status" : 200,
"product" : {
"fid": "nganu" ,
"product_code" : "NGANU" ,
"title" : "nganu" ,
"short_description" : "",
"description" : "",
"specification" : "nganu" ,
"link": "http://myshop.mysirclo.com/products/nganu" ,
"attachment" : null,
"label" : "GROCERIES" ,
"label_fid" : "groceries" ,
"brand" : "",
"weight" : 0,
"is_new" : false,
"is_featured" : false,
"is_active" : false,
"created_at" : "2016-06-02 16:30:04" ,
"images" : [
"http://sirclo-shops.s3-ap-southeast-
1.amazonaws.com/myshop/products/160602163315_nganu.jpg"
],
"detailed_images" : [
{
"url": "http://sirclo-shops.s3-ap-southeast-
1.amazonaws.com/myshop/products/160602163315_nganu.jpg" ,
"file_basename" : "nganu" ,
"color" : null
}
],
"is_in_stock" : true,
"stock" : 11,
"sold_stock" : 0,
"price" : "IDR 10000" ,
"price_raw" : 10000,
"category_ids" : [
12
],
"decoration" : null,
"wish_count" : 0,
"options" : [],
"general_options" : [],
"is_backorder" : false,
"is_ignore_stock" : false,
"variants" : [],
"detailed_variants" : [],
"prices_by_color" : [],
"advanced_pricing_rules" : null,
"size": null,
"color" : null,
"id": 255,

"custom_attribute1" : null,
 "custom_attribute2" : null,
"custom_attribute3" : null,
"custom_attribute4" : null,
"custom_attribute5" : null
}
}

Query all with paging

Request

curl -H "X-Sirclo-Access-Token: my -access-token" http://myshop.mysirclo.com/api/products/?

items_per_page=5&page=2

Response
 {
"status" : 200,
"products" : [
{
... // product 1 JSON
},
{
... // product 2 JSON
},
...
{
... // product 5 JSON
},
],
"paging" : {
"page": 2,
"total_in_page" : 5,
"total" : 2427,
"next": "http://bold/api/products?page=3&items_per_page=5"
}
}

Create Product
Method: POST (multipart/form-data)

Endpoint: /api/products

Parameters:

title

required
type: string
description: the product title
specication

required
type: string
description: the product speciciation
category_id

required
type: integer
description: id of a registered category
picture
 required
type: array of le
description: list of product images

item_code
optional
type: string
description: the product code

brand_label
optional
type: string
description: the product brand

price
optional
type: double
description: the product price

sale_price
optional
type: double
description: the product sale price

stock
optional
type: integer
description: the product stock

weight
optional
type: integer
description: the product weight (in grams)

is_featured
optional
type: boolean
description: set to a truthy value (commonly 1) if it's a featured product

is_new
optional
type: boolean
description: set to a truthy value (commonly 1) if it's a new product

is_allow_backorder
optional
type: boolean
description: set to a truthy value (commonly 1) if backorder is allowed

is_ignore_stock
optional
type: boolean
 description: set to a truthy value (commonly 1) if stock is ignored

is_active
optional
type: boolean
description: set to a truthy value (commonly 1) if it should be published

publish_update
optional

type: boolean
description: set to a truthy value (commonly 1) if update to social media

should be published

variants

optional
type: JSON as string

description: set to create aggregator product, example:

:::json
{
"option1_title": "Size",
"option2_title": "Color",
"with_price_per_variant": true, // true if you want each variant
// to have its own price
"variants": [{
"option1": "S",
"option2": "",
"product_code": "", // if empty, system will assign a unique
// value automatically
"stock": 1,
"price": 10000
}, {
"option1": "M",
"option2": "",
"product_code": "",
"stock": 2,
"price": 11000
}, {
"option1": "XL",
"option2": "",
"product_code": "",
"stock": 3,
"price": 12000
}]
}

Examples
Request

curl -H "X-Sirclo-Access-Token: my -access-token" -F 'stock=11' -F 'title=nganu' -F

'specification=nganu' -F 'category_id=12' -F '[email protected]'
http://myshop.mysirclo.com/api/products

Response

{
"status" : 200,
"message" : "New product created"
}

In case of failure (e.g.: duplicated slug or product code, invalid image, etc.):

{
"status" : 500,
"message" : "Create new product failed: <some reason>"
}

{
"status" : 500,
"message" : "Error in processing new product: <some reason>"
}

Update Product
Method: POST (multipart/form-data)

Endpoint: /api/products/<id>

Parameters are the same as Create Product, so are the responses with these as additional responses:

{
"status" : 400,
"message" : "Error in updating product: <some reason>"
}

Delete Product
Method: DELETE

Endpoint: /api/products/<id>

Parameters: none

Update Stock/Total Inventory of Batch Pr oducts

Update Stock/Total Inventory of Batch Pr oducts
Method: POST

Endpoint: /api/products/batch

Parameters: raw JSON array

product_code
required
type: string
description: the product code

total_inventory

required
type: integer
description: the product stock

Examples
Request

[
{
"product_code" : "product one" ,
"total_inventory" : 10
},
{
"product_code" : "product two" ,
"total_inventory" : 10
},
{
"product_code" : "product three" ,
"total_inventory" : 10
}
]

Response

{
"status" : 200,
"message" : "Products updated successfully"
}

In case of failure (e.g.: product not found based on its product code, forbidden to update total inventory of
product aggregator type, etc.):
 {
"status" : 500,
"message" : "Error in updating products." ,
"errors" : [
"Product not found with product code: product one" ,
"Forbidden to update total inventory of product aggregator type with
product code: product two"
]
}

Orders
Get Orders
Get a list of orders or a single order if <id> is specied. <id> is the internal order id.

Method: GET

Endpoint: /api/order/[<id>]

Parameters (all optional):

query

type: string

description: get products containing this value in their title or

specification field

page:

type: integer
description: get only products on this page
items_per_page

type: integer

description: get this number of products per page, use in conjunction with

page parameter

Examples

Query single e xisting order

Request

curl -H "X-Sirclo-Access-Token: my -access-token" http://myshop.mysirclo.com/api/orders/249

Response
{
"status" : 200,
"order" : {
"order_id" : "201600037" ,
"invoice_id" : "201600037" ,
"order_timestamp" : 1465971815 ,
"expiry_timestamp" : 1466058215 ,
"expiry_hours" : 24,
"invoice_link" : "http://bold/orders/201600037/invoice/174b6ef9" ,
"payment_notif_message" : null,
"prefered_delivery_timestamp" : false,
"coupon_code" : "",
"n_points_earned" : 1,
"n_points_used" : null,
"currency" : "IDR",
"item_total_amount_raw" : 135800,
"total_amount_raw" : 144800,
"total_amount" : "IDR 144,800.00" ,
"status" : "Pending" ,
"merchant_remarks" : null,
"message" : "",
"items" : [
"Almond Milk Rich Foot Cream 85ml"
],
"detailed_items" : [
{
"id": 274,
"friendly_id" : null,
"product_code" : "Skinfood010" ,
"image" : "http://sirclo-shops.s3-ap-southeast-
1.amazonaws.com/hobelo/products/160321111201_17..jpg" ,
"title" : "Almond Milk Rich Foot Cream 85ml" ,
"quantity" : 1,
"price" : 135800
}
],
"shipping" : 9000,
"discount" : 0,
"shipping_discount" : 0,
"payment_fee" : 0,
"payment_fee_discount" : 0,
"tax": 0,
"down_payment" : null,
"shipping_info" : "JNE REG" ,
"backorder_shipping_info" : null,
"payment_method" : "paypal" ,
"billing_info" : {
"name": "Mario " ,
"address" : "Jalan Haji Kocen No. 2 RT/RW 002/002 Kel. Kalimulya Kec. Cilodong " ,
"city": "Kota Depok - Cilodong" ,
"postal_code" : "16413" ,
"state" : "Jawa Barat" ,

"country" : "Indonesia" ,
 "phone" : "087788161895" ,
"email" : "[email protected]" ,
"salutation" : null,
"id_number" : null,
"nationality" : null,
"phone2" : null,
"dob_timestamp" : false
},
"delivery_info" : {
"name": "Mario " ,
"address" : "Jalan Haji Kocen No. 2 RT/RW 002/002 Kel. Kalimulya Kec. Cilodong " ,
"city": "Kota Depok - Cilodong" ,
"postal_code" : "16413" ,
"state" : "Jawa Barat" ,
"country" : "Indonesia" ,
"phone" : "087788161895" ,
"email" : "[email protected]" ,
"salutation" : null,
"id_number" : null,
"nationality" : null,
"phone2" : null,
"dob_timestamp" : false
},
"payment_instruction" : "",
"attribute1" : null,
"attribute2" : null,
"attribute3" : null,
"attribute4" : null,
"attribute5" : null,
"id": 249
}
}
Query all with paging
Request

curl -H "X-Sirclo-Access-Token: my -access-token" http://myshop.mysirclo.com/api/orders/?

items_per_page=5&page=2

Response

{
"status" : 200,
"orders" : [
{
... // order 1 JSON
},
{
... // order 2 JSON
},
...
{
... // order 5 JSON
},
],
"paging" : {
"page": 2,
"total_in_page" : 5,
"total" : 37,
"next": "http://bold/api/orders?page=3&items_per_page=5"
}
}

Create Order
Method: POST

Endpoint: /api/orders

Parameters: raw JSON

Examples
Request
 {
"billing-info" :{
"salutation" :"Mr",
"full-name" :"Mario Ray" ,
"address-line1" :"Jalan Biak 19C" ,
"district" :"Gambir" ,
"city":"Jakarta Pusat" ,
"province" :"DKI Jakarta" ,
"country" :"Indonesia" ,
"phone-number" :8121812 ,
"email" :"[email protected]" ,
"postal-code" :12122
},
"shipping-info" : {
"method" :"JNE-REG" ,
"cost":9000
},
"shipping-address" :{
"same-with-billing-info" :true
},
"items" :[{
"product-code" :"SANDALJPT-32" ,
"quantity" :1
},{
"product-code" :"SANDALJPT-42" ,
"quantity" :3
}],
"payments" :{
"coupon" :"[email protected]" ,
"method" :"bank-transfer"
},
"buyers-message" :"Tolong yak, ga pakai lama" ,
"order-date" :"2015-21-12 21:12:12"
}

P.S.:
despite the name product -code , it's actually friendly id that's expected

Response
 {
"status" :200,
"message" :"New Order created"
}

When coupon is given but the code is invalid:

{
"status" :500,
"message" :"Invalid Coupon Code"
}

When the stock for a product is not enough:

{
"status" :500,
"message" :"Problem during stock validation: <some information>"
}

Update Order
Method: PUT

Endpoint: /api/orders/<id>

Parameters are the same as Create Order, so are the responses

Delete Order
Method: DELETE

Endpoint: /api/orders/<id>

Parameters: none