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/update and get the details from ICS account. It is secured by OAuth token validation, 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.
4. Update Purchase Order.

Overview

The Purchase Order API is a REST-based solution that deals secure and convenient customer and business access to orders data. It has below endpoints:

/ping: This endpoint returns API health.

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

/purchaseOrders: This endpoint returns transfer details from the ICS.

This endpoint consists of GET, PUT methods, these are used to fetch, create and update the purchaseOrders.

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

1. sourceSystem: It is mandatory parameter used for querying the purchaseOrder details.
2. sourceSystempurchaseOrderId: This is an external (source) purchaseOrder Ids used for querying the purchaseOrder details.
3. icspurchaseOrderId: This is the ICS transfer ID generated by the ICS system. This is an optional field.
4. pageNumber: It is an optional field used for querying the purchaseOrder 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/updates purchaseOrder details in ICS system.

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 with valid JSON request to Purchase Order endpoint.
3. If the access is successful, API will perform the operations and create/update/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. itemProduct under order items are required if facility is receiving item through transfer.
3. icsPackageId is mandatory for pharmacy returns from patients.
4. If patientNumber or caregiverNumber is available in request, API treats it as Pharmacy order.
5. If it is purchase from partner/seller, API verifies the transfer created against the sales order to create the purchase order.

Use cases

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