Standard Product Supplier Integrations

What are the benefits of the SPSI framework?

Suppliers can:

• Create and update their catalogue and configure what products are visible to each clinic ad hoc as ezyVet updates the catalogue nightly (clinics have the option to sync manually any time).
• Set custom contract pricing at a clinic level.
• Indicate how much stock is available upon ordering.
• Receive POs in a consistent, easily digestible API call.
• Set custom business logic to assess POs sent via the SPSI and indicate to the clinic whether the PO is accepted or declined in real time.
• Send invoices to the clinic electronically based on what is included in each shipment.
• Send multiple invoices for a single PO if the order requires multiple shipments.
• Return batch information electronically for better inventory tracking in ezyVet.
• Configure custom invoice amounts at the time of billing based on specials or deals.

Clinics can:

• Search for and add products from the supplier's catalogue in advance or at the time of ordering.
• Have their existing products linked to the supplier's catalogue products.
• Have linked products automatically unlinked from the supplier when the supplier no longer stocks a product.
• Automatically update their inventory levels based on what is received.
• Have their received inventory automatically linked to batches.
• Have their product cost and sell prices automatically update based on ezyVet settings and supplier price updates (including special contract pricing).
• Have their cost of goods reporting automatically updated.
• Decide whether price updates and invoices require staff approval before taking effect.
• Get a consistent workflow experience across suppliers.
• Be notified via Memo when a invoice is received and completed.

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.

Even if the search parameters yield no results when querying the partner's endpoint, the partner must return a valid response. Below is a valid response to a query that did not yield a matched product.

{ 
    "products": [
        
    ]
}

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.

Certification Agenda

Session preparation for partner

• Partner to ensure the integration is at a state that is ready to use by clinics.
• Partner to ensure user documentation has been completed, returned to, and approved by the ezyVet Partnerships team.

Session guideline

1. Does the integration authenticate successfully?
2. When creating a new product in ezyVet, can we search for a product in the supplier’s list by name?
   • Is the correct pricing and tax pulled through into ezyVet once the product has been added?
3. What happens when a search yields no matches to a partner’s product?
   • The partner should return an empty list to avoid generating errors
4. When linking an existing product in ezyVet to a supplier’s product, can we search for a product via code?
   • Is the correct pricing and tax pulled through into ezyVet once the product has been added?
5. Create a purchase order.
   • Can a supplier’s product can be added to a purchase order?
   • Can the purchase order be sent via B2B?
6. Generate and send a receive invoice in the partner’s software.
   • Does the invoice appear in the job queue?
   • Can it be approved?
   • Is the invoice linked to the purchase order?
   • Is the invoice linked to the same location/separation as the purchase order?
   • Does the correct information come back into ezyVet? (Price, QTY, Total)
7. Update the supplier’s product list.
   • If the list is edited on the partner side, does it reflect in ezyVet?
   • If a price is changed in the list, does it reflect in ezyVet?