Transfer API

Transfer API

This API is used in transferring packages from producer to partner in labs, Orders.

Introduction

The Transfer API allows to fetch/initiate details from ICS account. Transfer API is secured by OAuth token validation, allowing customer to access any or all of the following depending on the API use case:

1. Fetch all Transfer details.
2. Fetch Transfer details with specific query parameters.
3. Create/Update Lab Transfer.
4. Create/Update Sales Order Transfer.

Overview

The Transfer API is a REST-based solution that deals secure and convenient customer and business access to transfer data. It provides information about the Lab/Sales/Purchase Transfer details from the ICS.

It has below endpoints,

/ping: This endpoint returns API health, it returns the health status of the API.

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

1. When the lab details are passed from the request it retrieves/initiate Lab transfer details
2. When the Sales Order number is passed from the request it retrieves Sales transfer details.
3. when the Purchase Order number is passed from the request it retrieves Purchase transfer details.

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

1. partnerFacility: It is a optional field used for querying the transfer details.
2. sourceSystem: It is optional parameter (sourceSystem can be passed along with combination of sourceSystemTransferId) used for querying the transfer details.
3. sourceSystemTransferId: This is an external (source) transfer Ids used for querying the transfer details.
4. icsTransferId: This is the ICS transfer ID generated by the ICS system. This is an optional field.
5. status: It is an optional field used for querying the transfer details for all stages.
6. pageNumber: It is an optional field used for querying the transfer details with specific page number.

PUT : This method creates/updates transfer details in ICS system. While creating transfer records below are the validation performed.

1. The sourceSystem,partnerFacility,driverLicense,licensePlate,packages and required parameters need to be passed to create transfer.
2. The required fields to be passed for respective transfers. for instance: icsSalesOrderId need to be passed while creating a salesOrder transfer.
3. The details of specific record can also be modified/updated by using same method,user need to pass sourceSystemTransferId of particular record.

Key features and benefits

1. Provides access to account details including token validation and initiates/retrieves for a variety of transfer types.
2. Puts your customers in control of their data sharing permissions and grants through our Security.
3. Validate data and access before performing transaction

How it works

The following diagram illustrates how the Transfer API works.

1. The customer sends client ID and Secret requesting authorization token to access Mule APi.
2. Mule API sends the secure token.
3. The customer enters their secure token and valid Json request for specific transfer type.
4. Mule OAuth provider processes the customer credentials and token to determine the authorization.
5. If the access is successful, the request is passed from Mule Api to ICS.
6. Response received from ICS is captured.
7. Mule API send the response back the customer in Json format.
8. 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 Transfer API.

1. sourceSystem is passed along with sourceSystemTransferId in creation or update of the Transfer record.
2. Update of a transfer record cannot be performed when the status of the transfer is “Out for Delivery” or "Approved" or is finalized.
3. Receive transfer is only possible with the transfer status is in “Out for Delivery” and finalTranfer flag is “True”.
4. (B2B) Allow the transfer if reserve quantity of package matches with the sales order quantity (order Item requested quantity) else if SO is created with product then order item quantity and packageSize is validated against package available quantity.
5. For B2B transfers, remaining quantity for each package is validated to be zero to ensure complete package transfer. Partial package transfers are restricted.
6. For B2B transfers order item Ids provided in the input request should match with SO order item Ids.
7. For B2C transfers, packages provided in input request should match with SO OI packages.
8. For B2C transfers, OI quantity is validated to be less than or equal to package reserve quantity. Partial package transfers are allowed in case of patient transfers.
9. Partner can see the "Ready for Review" and "Out for Delivery" transfers using GET call.
10. Transfer cannot be created if orderFulfilmentMethod value for provided SalesOrder is not Delivery.
11. icsSalesOrderId field is mandatory for transfer creation except if partner Facility is Lab.
12. (B2B) Validation is added to check whether partner has created a PO against the SO, before setting transfer to “Out for Delivery”. Exception:-When the partner facility is “Lab” or it is patient transfer.
13. Validation error is raised if input packages provided do not exists in the ICS.
14. (B2B) icsOrderItemIds passed are validated against sales order icsOrderItemIds. Validation error thrown if no icsOrderItemIds passed or incorrect icsOrderItemIds passed. Exception: Patient transfers.
15. Error is raised if test results are not passed in case partner facility if Pharmacy or it’s a patient transfer. Test result validation is bypassed for cultivator-processor transfers.
16. Valid driver and vehicle details are required in case of WholeSale and Internal transfers and for Retail Transfers either driver or courierName is mandatory.
17. If vehicle information is not provided in the input, it will be extracted from driver information.

Use cases

The following use cases are supported by the Transfer API.