Introduction

Welcome to the ezyVet Standard Product Supplier Integration Beta Reference Page!

The ezyVet Standard Product Supplier Integration is designed around a RESTful interface and utilizes OAuth 2.0 Client Credentials grant. The webhooks accepts and returns messages in JSON-format.

Standard Product Supplier Integration will be aliased to SPSI throughout this doc.

Partner Endpoints

Access Token

An endpoint which must be implemented by an API Partner. This endpoint will allow ezyVet to authenticate and use the Partner's web services (if authentication is required).

Fetch an Access Token

Note that this endpoint must be implemented by a Partner. This is NOT ezyVet's endpoint.

Sample Request: Get an Access Token.

var settings = {
  "url": "(Access Token Endpoint)",
  "method": "POST",
  "headers": {
    "content-type": "application/json"
  },
  "data": {
    "client_id": "abc",
    "client_secret": "def",
    "grant_type": "client_credentials"
  }
}

$.ajax(settings).done(function (response) {
  console.log(response);
});

Response (JSON)

{
  "access_token": "CnKAVqSqp6UBq3Ei17e1UIj2U39UuOQI1i9Db3QT",
  "token_type": "Bearer"
}

HTTP Request

POST (Access Token Endpoint)

Query Parameters

Parameter	Type	Default	Description
client_id	string	-	The client ID.
client_secret	string	-	The client secret.
grant_type	string	-	The grant type.

Response Parameters

Parameter	Type	Default	Description
access_token	string	-	The access token.
token_type	string	Bearer	The type of the access token. (Default of Bearer)

Purchase Order

An endpoint which must be implemented by an API Partner. This endpoint will allow ezyVet to send Purchase Orders to the supplier (partner).

Send a Purchase Order

Note that this endpoint must be implemented by a Partner. This is NOT ezyVet's endpoint.

Sample Request: Send a Purchase Order.

var settings = {
  "url": "(Purchase Order Endpoint)",
  "method": "POST",
  "headers": {
    "authorization": "Bearer mytoken",
    "content-type": "application/json"
  },
  "data": {
    "purchaseorder": {
      "id": "12",
      "active": "1",
      "created_at": "1514493886",
      "modified_at": "1514493886",
      "date": "1514466000",
      "shipping_address_id": "2",
      "comments": "Some comments.",
      "freight": "0",
      "freight_tax": "0",
      "tax": "0.4",
      "total": "4.4",
      "client_id": "2",
      "supplier_id": "10006",
      "status": "Approved",
      "supplier_order_number": "",
      "supplier_account_number": "",
      "purchase_order_number": "15000032",
      "ownership_id": "1",
      "purchase_order_item_list":[
        {
          "id": "9",
          "product_id": "50002",
          "supplier_code": "TP1",
          "outers": "1",
          "units_per_outer": "1",
          "price_per_unit": "4",
          "tax_per_unit": "0.4",
          "quantity": "1",
          "total": "4",
          "total_tax": "0.4",
          "ownership_id": "3",
        }
      ]
    }
  }
}

$.ajax(settings).done(function (response) {
  console.log(response);
});

Response (JSON)

{} 200 OK

HTTP Request

POST (Purchase Order Endpoint)

Body Parameters

Parameter	Type	Default	Description
id	num, string	-	The ID number used by the system to uniquely identify a `PurchaseOrder`.
active	num, string	-	If true, the `PurchaseOrder` is active and usable in ezyVet.
created_at	num, string	-	The epoch time when the `PurchaseOrder` was created.
modified_at	num, string	-	The epoch time when the `PurchaseOrder` was last modified.
date	num, string	-	The epoch time of the `PurchaseOrder` transaction date.
shipping_address_id	num, string	-	The ID of the shipping `Address` for the order. This is where the `products` ordered will be delivered.
comments	string	-	Any comments left by the `User` placing the order.
freight	num, string	-	The total monetary cost of the freight (inc tax).
freight_tax	num, string	-	The total tax content in the freight amount.
tax	num, string	-	The total tax content of the `PurchaseOrder`.
total	num, string	-	The total monetary amount of the `PurchaseOrder`. This value can be negative, indicating its a return of items. This value is tax inclusive.
client_id	num, string	-	The ID of the `client` linked to the `PurchaseOrder`. This may be `null` as it is an optional value in ezyVet.
supplier_id	num, string	-	The ID of the `supplier` to whom the order is sent.
status	string	-	The status of the `PurchaseOrder`. Can only be one of the following: `Created`, `Approved`, `Sent`, `Confirmed`, `Partial`, `Received`, `Completed` or `Cancelled`.
supplier_order_number	num, string	-	A number assigned by the `supplier` once an order is placed.
supplier_account_number	num, string	-	A string assigned on the `supplier` to identify the account the order is made from.
purchase_order_number	num, string	-	A number assigned to the `PurchaseOrder` by ezyVet.
ownership_id	num, string	-	The ID of the `Ownership Separation` to which this `PurchaseOrder` belongs.
purchase_order_item_list	list	-	A list of purchase order items.

Purchase Order Item Parameters

Parameter	Type	Default	Description
id	num, string	-	The ID number used by the system to uniquely identify a `PurchaseOrderItem`.
product_id	num, string	-	The ID of the `product` on the `PurchaseOrderItem`.
supplier_code	string	-	The code of the `product` in the `supplier's` records. (i.e. the code given to the product by the supplier)
outers	num, string	-	The number of outers being ordered for the given `product`.
units_per_outer	num, string	-	The number of units of the `product` included in one outer.
price_per_unit	num, string	-	The price of one unit in an outer.
tax_per_unit	num, string	-	The tax content per unit.
quantity	num, string	-	The number of `units` being ordered for the given `product`.
total	num, string	-	The total monetary amount of the `PurchaseOrderItem` excluding tax. This is calculated by multiplying the price of the `product` (excluding tax) by the `units_per_outer` and the `quantity` being ordered.
total_tax	num, string	-	The total tax content of the `PurchaseOrderItem`.
ownership_id	num, string	-	The ID of the `Ownership Separation` to which this `PurchaseOrderItem` belongs.

Products

An endpoint which must be implemented by an API Partner. This endpoint will allow ezyVet to get Products from the supplier (partner) and also perform product lookups.

Fetch Products

Note that this endpoint must be implemented by a Partner. This is NOT ezyVet's endpoint.

Sample Request: Get a list of Products.

var settings = {
  "url": "(Products Endpoint)",
  "method": "GET",
  "headers": {
    "authorization": "Bearer mytoken",
    "content-type": "application/json"
  },
  "data": {}
}

$.ajax(settings).done(function (response) {
  console.log(response);
});

Response (JSON)

{
  "products": [
    {
      "active": 1,
      "code": "ABC",
      "name": "ABC",
      "type": "medication",
      "category": "abc",
      "units_per_outer": "2",
      "unit_of_measure": "mg",
      "price_per_unit": "2",
      "list_price": 3,
      "contract_price": 1.5,
      "barcode": 1234,
      "stock_available": 2,
      "related_urls": [
        "https:\/\/example.com"
      ]
    }
  ]
}

HTTP Request

GET (Products Endpoint)

Query Parameters

Note: All query parameter values will be arrays (urlencoded).
I.e. https://endpoint.com/api/products?code=[]&name=[abc,def]
The above url will be url encoded.

Parameter	Type	Default	Description
name	array	[]	An array containing none, one or many product `names`. If values are provided, results should only include products with `names` that contain or match one or more of the values provided. An empty array means no filtering.
code	array	[]	An array containing none, one or many product `codes`. If values are provided, results should only include products with `codes` that contain or match one or more of the values provided. An empty array means no filtering.
category	array	[]	An array containing none, one or many product `categories`. If values are provided, results should only include products with `categories` that contain or match one or more of the values provided. An empty array means no filtering.
limit	array	[]	An array containing `ONLY one integer`. The `integer` provided will be the maximum number of results to return. If an empty value, empty array is provided, or if the parameter is non-existent, then return with no limit.
page	array	[]	An array containing `ONLY one integer`. The `integer` provided will be the page number to return. E.g. If the limit was 5 and the total number of results was 40, then a `page` value of `3` would give us results between 15-19 `inclusive`. `NOTE`: Page number starts at `0`. So the first page of results will be for page `0`.

Body Parameters

NOTE: Mandatory fields are marked with a *.

Parameter	Type	Default	Description
products*	list	-	An array containing a list of product details.

Product Parameters

Parameter	Type	Default	Description
active	int	-	An integer signifying if the product is active and used in the supplier's (partner) system. Must be either `1` or `0`, where `1` means actively used, `0` otherwise.
code*	string	-	The supplier's (partner's) product code.
name*	string	-	The supplier's (partner's) name for the product.
type	string	-	If provided, must be one of: `Standard`, `Medication`, `Vaccination`, `Diagnostic`, `Integrated Diagnostic`, `Procedure`.
category	string	-	The category/group the product is classed under.
units_per_outer	float	-	The number of product units per outer. E.g. 2 bottles per box (where 1 bottle is a unit and the box is 1 outer).
unit_of_measure	string	-	The unit of measure used to quantify the product. E.g. ml = millilitres - 2ml of paracetamol.
price_per_unit	float	-	The price per unit of product.
list_price*	float	-	The listing price of the product, however it may be classed. E.g. If the listing of a product shows a box of bottles, where 1 bottle is 1 unit of product, then the listing price is the price of the box containing the bottles and the price_per_unit is the price of 1 bottle.
contract_price	float	-	The contract/special price for the product, if one exists.
barcode	string	-	The barcode string/number/value of the product.
image_url	url	-	A url pointing to the image of the product.
stock_available	float	-	The amount of stock on hand/available for the product at the supplier's (partner's) end.
rrp	float	-	The recommended retail price of the product.
manufacturer	string	-	The manufacturer of the product.
manufacturer_code	string	-	The manufacturer code of the product.
product_instructions	string	-	Any instructions to accompany the product.
related_urls	array, url	[]	An array containing urls to related material.
rvm_course_length	string	-	Restricted Veterinary Medicine (RVM) course length.
rvm_dose	string	-	RVM dose.
rvm_administration	string	-	RVM administration details.
rvm_treatment_frequency	string	-	RVM treatment frequency.
rvm_treatment_count	string	-	RVM treatment count.
rvm_withholding_period_milk	string	-	RVM withholding period for milk.
rvm_withholding_period_meat	string	-	RVM withholding period for meat.
rvm_max_dispense_qty	float	-	RVM maximum dispense quantity.
rvm_max_dispense_frequency	float	-	RVM maximum dispense frequency.
rvm_active_ingredient	string	-	RVM active ingredient.

Introduction

Partner Endpoints

Access Token

Fetch an Access Token

HTTP Request

Query Parameters

Response Parameters

Purchase Order

Send a Purchase Order

HTTP Request

Body Parameters

Purchase Order Item Parameters

Products

Fetch Products

HTTP Request

Query Parameters

Body Parameters

Product Parameters

Categories

Fetch Product Categories

HTTP Request

Body Parameters

Endpoints

Authentication

Receive Invoice

Receive Invoice Item

Job Queue

Separation

Features

Errors