Purchase Order API

Purchase Order API

This API is use for creation of purchase orders. The consumer who is purchasing items from producer can keep track of their purchases in ICS System using this API. Pharmacy can also use this API to accept returns from patients which updates the patient purchase limits.

Introduction

The Purchase Order API allows to create and get the details from ICS account. It is secured by OAuth token, allowing customer to access any or all of the order data for specific facility depending on the API use case:

1. Fetch all Purchase Order details.
2. Fetch Purchase Order details with specific query parameters.
3. Create Purchase Order.

Overview

The Purchase Order API is a REST-based service that provides secure and efficient access to purchase order information, enabling consumers to create and retrieve order data from the ICS platform. The API exposes the following endpoints.:

/ping:

This endpoint consists of GET method, which provides the health status of the API.

/purchaseOrders:

This endpoint consists of GET, PUT methods, these are used to fetch, create the Purchase Orders.

GET: This method returns purchaseOrder details by using below query parameters.

1. sourceSystem: It is mandatory parameter used for querying the PO details.
2. sourceSystempurchaseOrderId: This is an external (source) PO Ids used for querying the order details.
3. icspurchaseOrderId: This is the ICS purchase order id (name) generated by the ICS system. This is an optional field.
4. pageNumber: It is an optional field used for querying the PO details with specific page number.
5. fromDate: use this field to extract PO from specific date until today if toDate param is not passed.
6. toDate: use this field to extract PO till specific date from specific date. If fromDate is not present then it will exract all records until current date.

PUT: This method creates purchaseOrder details in ICS system.

1. Purchase order can be created for B2B when partnerFacility value is passed in request.
2. API allows order with icsPackageId only for all transactions.
3. Purchase order for B2C i.e. return from patient is created when patientNumber or caregiverNumber is passed in the request by pharmacy.

Key features and benefits

The following are features and benefits of the Purchase Order API:

1. Access is controlled through specific client id and source system codes.
2. Puts customers in control of their data sharing permissions and grants through API Security.
3. Data validation while modifying orders.
4. No PII or secure information is logged during transaction.

How it works

The following diagram illustrates how the Purchase Order API works.

1. The customer sends client ID and Secret requesting authorization token from Mule OAuth provider API.
2. Send the security token and client id in header with valid JSON request to Purchase Order endpoint.
3. If the access is successful, API will perform the operations and create/get the records to/from ICS.
4. Response from ICS is captured and return to source system.
5. If any error in the flow or validation error, Mule API handles and reverts the specific error with the customer along with standard error codes.

Validations

The following are the validations for data transformation in Purchase Orders API.

1. sourceSystem, sourceSystemPurchaseOrderId, icsSalesOrderId and order items are required to create purchase order records.
2. icsPackageId under order items are required for B2B and B2C scenarios
3. For B2B, API verifies the transfer created against the sales order before creating the purchase order.
4. For B2B, once purchase order is created, it automatically approves the transfer and sales order.
5. For B2C, if patientNumber or caregiverNumber is available in request, API treats it as Pharmacy order returns.
6. For Pharmacy, returns will be allowed with partial quantities of packages and patient purchase history will be adjusted.
7. For B2C, returned quantities will be adjusted to original package associated with transaction.
8. Pharmacy can create refund record using purchase order by not passing orderItems in the request. Refund does not adjust patient history.
9. Purchase order updates are restricted.

Use cases

The Purchase Order API supports data access for the following use cases.