Sales Order API

Sales Order API

This API is used for creating sales orders for partner facilities as well as patient sales orders.

Introduction

The Sales Order API allows to create/update/get details from ICS account. API is secured by OAuth authentication, allowing customer to access records for specific facility depending on the API use case:

1. Fetch Sales Order details.
2. Create Sales Order for partner facilities or for patient sale.
3. Update Sales Order.

Overview

The Sales Order API has below endpoints,

/ping:

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

/SalesOrder:

This endpoint consists of GET, PUT methods, these are used to fetch, create/update the Sales Orders in ICS system.

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

• sourceSystem: It is mandatory parameter used for querying the SalesOrder details.
• sourceSystemSalesOrderId: This is an external (source) salesOrder Ids used for querying the SalesOrder details.
• icsSalesOrderId: This is the ICS sales order id (name) generated by the ICS system. This is an optional field.
• pageNumber: It is an optional field used for querying the SalesOrder details with specific page number. If your records are beyond 2000, use date query parameters.
• toDate & fromDate: These are optional parameters to extract sales order based on specific creattion date range in ICS system.

PUT: This method creates/updates SalesOrder details in ICS system.

1. Sales order can be created for B2B when partnerFacility value is passed in request.
2. API allows order with icsPackageId or itemProduct for B2B.
3. Sales order for B2C i.e. sales to patient is created when patientNumber or caregiverNumber is passed in the request.

Key features and benefits

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

1. Provides access to Sales Order data based on client id and source system code.
2. Puts customers in control of their data sharing permissions and grants through API Security.
3. Data validation is performed while modifying orders.
4. No PII or secure information is logged during transaction.

How it works

The following diagram illustrates how the Sales 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 Sales 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 Sales Orders API.

1. sourceSystem and sourceSystemSalesOrderId are mandatory parameters while SO creation.
2. sourceSystemSalesOrderId is the combinations of sourceSystem+ "-" + sourceSystemSalesOrderId while stored in ICS System.
3. order Items is mandatory in Sales order and payment Information is optional.
4. icsPackageId is mandatory for pharmacy sales order and it is optional for cultivators and processors. i.e. B2B sales
5. Cultivators/processors can either pass icsPackageId or itemProduct values in order item.
6. Patient/Caregiver number or partnerFacility either of one is mandatoty field while creating sales order.
7. For pharmacy and patient transfer, package must have packageSize and valid test result while creating Sales Order
8. Partial Sales are allowed for pharmacy to patients but not for facility to facility (B2B) sales.
9. If package is used at order item level, package quantity is reserved while order status is in progress. It gets reduce to zero after receive transfer is complete.
10. Order item quantity and package remaining quantity should be less than or equal while creating the order.
11. Order Item quantity cannot be more than package quantity if icsPackageId is used while SO creation.
12. Tax information is optional for all facilities, however valid tax name along with either tax rate or tax amount to be passed in input.
13. Payment information is optional segment while creating sales orders.
14. Location information such as Building and room is mandatory at order item level.
15. Transfer fee will be set to default value in ICS system.
16. Sales order update is allowed before it is approved
17. For B2B, Sales order get approved automatically via Purchase Order creation. No updates allowed once Sales order is approved
18. For B2B, consumer facility can see sales order details once associated transfer is in "Ready for Review" status.

Assumptions

The following message handling is expected by API from API consumers,

1. While adding multiple orderItems for same package or product, accumulate the records in single orderItem object by adjusting quantity before passing to API.
2. API consumer will pass valid token, valid JSON payload while invoking this API.
3. Use toDate and fromDate parameters while extracting high volume data from ICS instead of using pagination over 100 pages.
4. The API will not perform validation of the payment information. Responsibility for submitting the required payment information for compliance rests with the industry.

Use Cases

The following use cases are supported by the Sales Order API.