Standard Product Supplier Integrations

What are inners/units and outers?

Outers and inners relate to the container and number of items within a container for a supplied product.

For example, a product is supplied with the name Amoxicillin. The product is a box of 10 tablets.

• The inners (or units) would be 10 (tablets).

• The outers would be 1 (box).

What separations should be referenced in a Receive Invoice?

The ownership_id field in the body of the receiveinvoice object represents the clinic/business that will have their financial records impacted by the receive invoice.

The value of this field should be mapped to the value of the ownership_id field that is sent to the partner in the main body of the purchaseorder object.

The location_id field in the body of the receive invoice line_item object represents the physical stock location/room that will have it’s balances impacted by the items in the receive invoice.

The value of this field should be mapped to the value of the ownership_id field that is sent to the partner in the body of the purchase_order_item_list object.

Example

"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": "1502", 
    "ownership_id": "2", 
    "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" 
        } 
    ] 
}

{ 
    "invoice_number": "INV_001", 
    "date": 1558559681, 
    "due_date": 1558559681, 
    "comments": "For PO 1502.", 
    "freight": 4.00, 
    "freight_tax": 10.00, 
    "ownership_id": 2, 
    "line_item": [ 
        { 
            "quantity": 2, 
            "price": 4.00, 
            "tax": 0.4, 
            "tax_rate": 10, 
            "tax_code": "S", 
            "supplier_code": "TP1", 
            "location_id": 3, 
            "purchase_order_item_id": 9 
        }
    ] 
}

How can a partner link receive invoice line items to a purchase order line items?

When a purchase order is created, each line item is represented by an object in the purchase_order_item_list and is allocated a unique id.
This id is referenced as the value for the field named purchase_order_item_id in a receive invoice line_item object.

The example above demonstrates this.

If an item is included in a receive invoice that was not included in the corresponding purchase order, the purchase_order_item_id field should be omitted for that line_item object.

What if some products are batch tracked?

Batches are a common way of tracking inventory so it’s necessary to understand how batches are allocated with respect to a receive invoice.

One or more batches can be allocated to a receive invoice line_item as an array of objects, meaning that the partner can supply the same product from one or more batches and specify the supplied quantity from each batch.

Example

{ 
    "invoice_number": "INV_001", 
    "date": "1558559681", 
    "due_date": "1558559681", 
    "comments": "Order invoice INV_001.", 
    "freight": "4.00", 
    "freight_tax": "10.00", 
    "ownership_id": "2", 
    "line_item": [ 
        { 
            "quantity": "2", 
            "price": "2.35", 
            "tax": "0.235", 
            "supplier_code": "supplier123", 
            "location_id": "3", 
            "purchase_order_item_id": "10", 
            "batch": [ 
                { 
                    "name": "BAT254", 
                    "expiry": 1560718800, 
                    "quantity": 1 
                } 
            ] 
        } 
    ] 
}

What if I want a list of batches that already exist in the PIMS?

Calling the v2/batch API endpoint will return a list of batches that exist in the PIMS and their expiry dates.

When creating a receive invoice, how should I round the tax value?

ezyVet accepts rounding of 4dp for the tax and total_tax fields of receive invoice line_item objects.

When creating a receive invoice, how should I calculate the quantity?

When creating Receive Invoice line items, the quantity field should reflect the number of outers/containers provided, not the number of inners/units. (This is a known issue)

Querying the partner’s product endpoint

How does ezyVet query the partner’s product endpoint?

Per the API documentation, ezyVet will query the partner’s product endpoint with the parameters being URL encoded and the values enclosed in arrays, separated by commas.

E.g. https://endpoint.com/api/products?code=[]&name=[abc,def]

These values are set in the UI.

The partner’s endpoint must support queries of this structure and return appropriate results.

Because ezyVet offers customers the ability to search the partner’s (supplier’s) catalog by product categories, it’s mandatory for the partner to provide a category endpoint and ensure products can be searched/filtered by category.

When does ezyVet query the partner’s product endpoint?

• When the clinic is wanting to map an existing ezyVet product to a partner’s (supplier’s) catalog product. This is done manually by navigating to the Ordering tab of the product, adding a supplier and searching.

• When a clinic is creating a purchase order for the supplier and doesn’t already have the supplier’s product mapped to an ezyVet product.

• When the purchase order is accepted through the PIMS
  
  

  

• When a Receive Invoice comes back into the ezyVet Job Queue
  
  

  

What is contract pricing and when is it used?

Contract pricing is special pricing that’s provided to clinics that meet special requirements. Usually these prices will differ on a per-clinic basis. Contract pricing will be applied to a clinic’s product pricing if the setting named “Supports Contract Price” is enabled.

Do cost and sell prices automatically update?

Cost and sell prices will update when a purchase order is next made for that product so long as the appropriate Auto-Update Settings are enabled. See the above screenshot.

If the option named Price updates require approval is enabled, any detected price change will need to be approved through the job queue.

How do purchase orders impact back-order statistics?

When a purchase order is made and sent to the supplier (partner), the product’s on-order table is updated to reflect the order quantity.

When a receive invoice record (and subsequently a receive inventory record) are created and approved, the products that are included in the invoice will have their on-order table updated to reflect the correct quantity.

How are receive invoices accepted?

In the Auto-Update Settings there is an option named Receive Invoice Manually. If this option is not selected, receive invoices that come through to the job queue with no errors will be accepted automatically. If the option is selected, receive invoices that come through without errors will be held in the job queue until a staff member manually accepts them. Receive Invoices that are waiting to be accepted will have a status of Pending Approval.

How to debug receive invoices from the job queue

If there is an issue with a receive invoice, the job queue will catch and hold it until it’s fixed. It will appear in the job queue with details including the supplier name, integration name and invoice number. The Status will display as Error. By hovering over the word Error a popup will appear that details what needs to be corrected in order for the invoice to be accepted.

Selecting the blue Fix button will open the Fix Job Wizard where the receive invoice can be corrected.

How to set purchase order account codes for a business/clinic

As part of the API POST request ezyVet sends when a purchase order is placed, there is an account code field that is included that can be used to identify which separation (clinic) it originated from.

By navigating to the SPSI integration record and double clicking on the Supplier record (shown below):

ezyVet will bring up the supplier’s contact record (blue tab). Click on the supplied sub-tab shown below:

Here you’ll find a section named Supplier Account Details where you can set account codes and map them to a separation (clinic).

Below you can see a JSON representation of a purchase order API request that was made from Death Star Vets. Note that the value for the field named supplier_account_number matches what is mapped to the division shown above.