# Formosa Online Order System API Documentation

First, you have to apply for the key in order to connect to our system.

From "Members -> API Intergration", Click the "Generate" Button to generate consumer secret and consumer key. Note: The consumer secret and consumer key will only appear once. So please make sure you save the key and secret.


## Testing

We use CUrl to demonstrate how to connect the API.

GET&http%3A%2F%2Fwww.formosascreens.com.au%2Fwp-json%2Fwc%2Fv3%2Fget_product_list&oauth_consumer_key%3Dabc123%26oauth_signature_method%3DHMAC-SHA1

Or you can use postman to test via OAuth 1.0.


### Official libraries

- [JavaScript](https://www.npmjs.com/package/@woocommerce/woocommerce-rest-api) Library
- [PHP](https://packagist.org/packages/automattic/woocommerce) Library
- [Python](https://pypi.python.org/pypi/WooCommerce) Library
- [Ruby](https://rubygems.org/gems/woocommerce_api) Library

### Tools
[Postman](https://www.postman.com/) - Cross-platform REST client, available for Mac, Windows, and Linux.
[Insomnia](https://github.com/Kong/insomnia) - Cross-platform GraphQL and REST client, available for Mac, Windows, and Linux.

## Error

| Error Code | Error Type |
| :------------- | :---------- |
| 400 Bad Request | Invalid request, e.g. using an unsupported HTTP method |
| 401 Unauthorized | Authentication or permission error, e.g. incorrect API keys |
| 404 Not Found | Requests to resources that don't exist or are missing |
| 500 Internal Server Error | Server error |

## Use different exmaple and link and authancation

You may use HTTP Basic Auth by providing the REST API Consumer Key as the username and the REST API Consumer Secret as the password.

const WooCommerceRestApi = require("@woocommerce/woocommerce-rest-api").default;
// import WooCommerceRestApi from "@woocommerce/woocommerce-rest-api"; // Supports ESM

const WooCommerce = new WooCommerceRestApi({
  url: 'https://www.formosascreens.com.au/',
  consumerKey: 'your_consumer_key',
  consumerSecret: 'your_consumer_secret',
  version: 'wc/v3'
});

Occasionally some servers may not parse the Authorization header correctly (if you see a "Consumer key is missing" error when authenticating over SSL, you have a server issue). In this case, you may provide the consumer key/secret as query string parameters instead.

**node.js**

const WooCommerceRestApi = require("@woocommerce/woocommerce-rest-api").default;
// import WooCommerceRestApi from "@woocommerce/woocommerce-rest-api"; // Supports ESM

const WooCommerce = new WooCommerceRestApi({
  url: 'https://www.formosascreens.com.au/',
  consumerKey: 'your_consumer_key',
  consumerSecret: 'your_consumer_secret',
  version: 'wc/v3',
  queryStringAuth: true // Force Basic Authentication as query string true and using under HTTPS
});

**php**

<?php
require __DIR__ . '/vendor/autoload.php';

use Automattic\WooCommerce\Client;

$woocommerce = new Client(
    'https://www.formosascreens.com.au/',
    'your_consumer_key',
    'your_consumer_secret',
    [
        'wp_api' => true,
        'version' => 'wc/v3',
        'query_string_auth' => true // Force Basic Authentication as query string true and using under HTTPS
    ]
);
?>

**python**

from woocommerce import API

wcapi = API(
    url="https://www.formosascreens.com.au/",
    consumer_key="your_consumer_key",
    consumer_secret="your_consumer_secret",
    wp_api=True,
    version="wc/v3",
    query_string_auth=True // Force Basic Authentication as query string true and using under HTTPS
)

**Ruby**

require "woocommerce_api"

woocommerce = WooCommerce::API.new(
  "https://example.com",
  "consumer_key",
  "consumer_secret",
  {
    wp_json: true,
    version: "wc/v3",
    query_string_auth: true // Force Basic Authentication as query string true and using under HTTPS
  }
)

## ==GET==view_order_list

Retrieve Order List

### Available parameters
| Attribute | Type | Description |
| :------------- | :----------: | :----------- |
| limit | integer | Optional:number of list retrieve |
| paged | integer | Optional:You can specify further pages with the `?paged` parameter: |

### Return Properties ARRAY<object>
| Attribute | Type | Description |
| :------------- | :----------: | :----------- |
| order_number | integer | Order number |
| order_date | WC_Date |date\<yyyy-MM-dd HH:mm:ss\> / timezone_type<1>/timezone<"+00:00">|
| status | string | Pending/Processing/On Hold/ Completed/Ready For Delivery/Ready For Pickup/Picked up |
| total | float | total of order |
| note | string | the note of order |
| reference | Array\<String\> | the reference of item(s) |

### Request sent (Node.js):

WooCommerce.get("view_order_list?limit=5&paged=2")
  .then((response) => {
    console.log(response.data);
  })
  .catch((error) => {
    console.log(error.response.data);
  });

### Request sent (php):

<?php
print_r($woocommerce->get('view_order_list?limit=5&paged=2'));
?>

### Request sent (Python):

print(wcapi.get("view_order_list?limit=5&paged=2").json())

### Request sent (Ruby):

woocommerce.get("view_order_list?limit=5&paged=2").parsed_response

### JSON response example:

[
    {
        "order_number": "1234",
        "order_date": {
            "date": "2021-03-11 04:32:29.000000",
            "timezone_type": 1,
            "timezone": "+00:00"
        },
        "status": "pending",
        "total": "3278.89",
        "note": [],
        "reference": [
            "Reference #34256",
            "Reference #18923",
            "Reference #49201",
            "Reference #327641",
        ]
    },
    .
    .
    .
]

## ==GET==view_order_detail
Retrieve Order By Order Id

### Available parameters
| Attribute | Type | Description |
| :------------- | :----------: | :----------- |
| order_number | integer | Required:Specify order id |

### Return Properties
| Attribute | Type | Description |
| :------------- | :----------: | :----------- |
| order_number | integer | id of order |
| order_date | string | date of date |
| status | string | status of order |
| subtotal | float | the total without GST. |
| shipping_method | string | Shipping method |
| total | float | The total included GST. |
| phone | string | Phoner number |
| email | string | Email |
| billing_address | string | Billing address |
| shipping_address | string | if empty, shipping address as billing adress |
| item_list | Array\<item_detail\> | |

#### Return Properties - item_detail

| Attribute | Type | Description |
| :------------- | :----------: | :----------- |
| product_name | string | product title |
| product_quantity | integer | quantity of item(s) |
| total | float | the total of item(s) |
| field | object\<Field\> | include width/height/colour/Note/customise colour/direction |

### Request sent:

WooCommerce.get("view_order_detail?order_number=2341")
  .then((response) => {
    console.log(response.data);
  })
  .catch((error) => {
    console.log(error.response.data);
  });

### JSON response example:

{
    "order_number": "2341",
    "order_date": "2021-03-11 04:32:29.000000",
    "status": "on-hold",
    "subtotal": 2980.81,
    "shipping_method": "",
    "total": "3278.89",
    "phone": "0412345678",
    "email": "[e-mail]",
    "billing_address": "Formosa Screens</br>1 Malibu Circuit,Carrum Downs ,Victoria 3201",
    "shipping_address": "Formosa Screens</br>1 Malibu Circuit,Carrum Downs ,Victoria 3201",
    "item_list": [
        {
            "product_name": "slim Double retractable screen",
            "product_quantity": 1,
            "total": "496.409091",
            "field": {
                "width": "1841",
                "height": "1477",
                "colour": "customise colour",
                "Note": "##testing$## 49th test",
                "customise colour": "APO Black 3552"
            }
        },
        {
            "product_name": "Trackless Single Side Double Slide Blind",
            "product_quantity": 1,
            "total": "769.827273",
            "field": {
                "width": "2042",
                "height": "1421",
                "colour": "White",
                "Note": "##testing$## 49th test roller a5785 rtical retractae"
            }
        },
        {
            "product_name": "Roller C Shape Vertical Blind",
            "product_quantity": 1,
            "total": "350.445455",
            "field": {
                "width": "1245",
                "height": "1132",
                "colour": "White",
                "Note": "##testing$## 49th test retractable screen"
            }
        },
        {
            "product_name": "Standard Single  Window Horizontal Retractable FlyScreen",
            "product_quantity": 1,
            "total": "378.463636",
            "field": {
                "width": "1499",
                "height": "1399",
                "colour": "customise colour",
                "Note": "##testing$## 49th test vertical retractable screen",
                "direction": "right to left",
                "customise colour": "APO Grey 3928"
            }
        },
        {
            "product_name": "Standard Single  Window Vertical Retractable FlyScreen",
            "product_quantity": 1,
            "total": "228.736364",
            "field": {
                "width": "1245",
                "height": "1132",
                "colour": "White",
                "Note": "##testing$## 49th test retractable screen",
                "direction": "right to left"
            }
        },
        {
            "product_name": "Standard C Shape  Window Horizontal Retractable FlyScreen",
            "product_quantity": 1,
            "total": "378.463636",
            "field": {
                "width": "1499",
                "height": "1399",
                "colour": "customise colour",
                "Note": "##testing$## 49th test screen 3928",
                "direction": "right to left",
                "customise colour": "APO Grey 3928"
            }
        },
        {
            "product_name": "Standard C Shape Window Vertical Retractable FlyScreen",
            "product_quantity": 1,
            "total": "378.463636",
            "field": {
                "width": "1499",
                "height": "1399",
                "colour": "customise colour",
                "Note": "##testing$## Traroller a5779 shape vertical retractable screen",
                "direction": "right to left",
                "customise colour": "APO Grey 3928"
            }
        }
    ]
}

## ==GET==get_product_list
Get Product List

### Return Properties
| Attribute | Type | Description |
| :------------- | :----------: | :----------- |
| \*result | Array\<Object\> | return object |
| id | integer | in the object , Id of product that use for any further operate|
| title | string | in the object , title of product|

### Request sent:

WooCommerce.get("get_product_list")
  .then((response) => {
    console.log(response.data);
  })
  .catch((error) => {
    console.log(error.response.data);
  });

### JSON response example:

[
    {
        "id": 10637,
        "title": "Standard Corner Pleated Screens"
    },
    {
        "id": 6461,
        "title": "Standard Uneven Double Pleated Screens"
    },
    {
        "id": 5787,
        "title": "Roller Type Single Vertical C-Shape retractable screen"
    },
    {
        "id": 5786,
        "title": "Roller Type Single Horizontal C-Shape retractable screen"
    },
    .
    .
    .
]

## ==GET== get_product_fields
Retrieve Product Field

### Available parameters
| Attribute | Type | Description |
| :------------- | :----------: | :----------- |
| product_id | integer | Required:specify product ID |

### Return Properties
| Attribute | Type | Description |
| :------------- | :----------: | :----------- |
| label | string | field title |
| type | string | numeric/text/radio/picklist|
| required | bool | if true , the field required. |
|options|array<string>|come with radio/picklist option|
|options|object<string>|come with numeric option, the limitation of input range.|

### Request sent:

WooCommerce.get("get_product_fields?product_id=3991")
  .then((response) => {
    console.log(response.data);
  })
  .catch((error) => {
    console.log(error.response.data);
  });

### JSON response example:

[
    {
        "label": "customize colour",
        "type": "text",
        "required": "0"
    },
    {
        "label": "colour",
        "type": "radio",
        "required": "1",
        "options": [
            "Black",
            "White",
            "Monument",
            "Clear Anodised",
            "Customise Colour"
        ]
    },
    {
        "label": "width",
        "type": "numeric",
        "required": "0",
        "options": {
            "max_value": "4000",
            "min_value": "300"
        }
    },
    {
        "label": "height",
        "type": "numeric",
        "required": "1",
        "options": {
            "max_value": "3000",
            "min_value": "300"
        }
    },
    {
        "label": "note",
        "type": "text",
        "required": "0"
    },
    {
        "label": "mesh material",
        "type": "picklist",
        "required": "0",
        "options": [
            "Black Mesh",
            "Grey Mesh"
        ]
    },
    {
        "label": "direction",
        "type": "radio",
        "required": "1",
        "options": [
            "Right to Left",
            "Left to Right"
        ]
    },
    {
        "label": "quantity",
        "type": "numeric",
        "required": "1",
        "options": {
            "max_value": "",
            "min_value": "1"
        }
    }
]

## ==POST== calculate_price_dynamic
Retrieve Live Product Price

### Available parameters
| Attribute | Type | Description |
| :------------- | :----------: | :----------- |
| product_id | integer | required：specify product id |
| quantity | integer | required:quantity of your product |
| width a | integer | required:only required when the proudct need this field like uneven double standard screen|
| width b | integer | required:only required when the proudct need this field like uneven double standard screen |
| width | integer | required:only ignored when the product doesn't need this field.it depends `get_product_fields` returns parameters. |
| height | integer | required:height of product |
| colour | string | if it's not standard colour, select the customise colour. |
| direction | string | if it's not standard colour, select the customise colour. |

### Return Properties
| Attribute | Type | Description |
| :------------- | :----------: | :----------- |
| price | integer | calculate the product price live. |

### Request sent(Node.js):

let price_data = {
    "product_id": "4018",
    "quantity": 1,
    "width":2142,
    "height": 2449,
    "colour": "customise colour",
    "customise colour": "APO Grey",
};

WooCommerce.post("calculate_price_dynamic",price_data)
  .then((response) => {
    console.log(response.data);
  })
  .catch((error) => {
    console.log(error.response.data);
  });

### Request sent(php):

<?php
$price_data = array(
    'product_id' => '4018',
    'quantity' => 1,
    'width' => 2142,
    'height' => 2449,
    'colour' => "customise colour",
    'customise colour' => "APO Grey"
);

print_r($woocommerce->post('calculate_price_dynamic', $price_data));

?>

### Request sent(python):

price_data = {
    "product_id": "4018",
    "quantity": 1,
    "width":2142,
    "height": 2449,
    "colour": "customise colour",
    "customise colour": "APO Grey",
}

print(wcapi.post("calculate_price_dynamic", price_data).json())

### Request sent(Ruby):

price_data = {
    "product_id": "4018",
    "quantity": 1,
    "width":2142,
    "height": 2449,
    "colour": "customise colour",
    "customise colour": "APO Grey",
}

woocommerce.post("calculate_price_dynamic", data).parsed_response

### JSON response example:

{
    "price": "1209.32"
}

## ==POST==place_an_order
Place an order

### Available parameters

| Attribute | Type | Description |
| :------------- | :----------: | :----------- |
| product_id | integer | required |
| quantity | integer | default is 1 |
| width | integer | required |
| height | integer | Like this \| |
| colour | string | if it's not standard colour, select the customise colour. |
| customise colour | string | optional if colour is customised colour |
| direction | string | optional if the product type required. |
| note | string | if it's not standard colour, select the customise colour. |

### Return Properties
| Attribute | Type | Description |
| :------------- | :----------: | :----------- |
| totals | integer | the whole price of your order |
| order_id | integer | order number you submit |

### Request sent:

let order_data = {
    "items": [
        {
            "product_id": "3991",
            "quantity": 1,
            "width": 1841,
            "height": 1477,
            "colour": "customise colour",
            "customise colour": "APO Black 3552",
            "note": "##testing$## test 67th round - standard",
            "direction" : "left to right"
        },
        {
            "product_id": "10637",
            "quantity": 1,
            "width" : "2142,2341"
            "height": 2749,
            "colour": "black",
            "customise colour": "APO Grey 3928",
            "note": "##testing$## test 67th round - Corner"
        }
    ]
}

WooCommerce.post("place_an_order",order_data)
  .then((response) => {
    console.log(response.data);
  })
  .catch((error) => {
    console.log(error.response.data);
  });

### JSON response example:

{
    "totals": "1577.79",
    "order_id": "11448"
}