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.
5. Complete Transfer (by Partner).

Overview

The Transfer API is a REST-based solution that deals secure and convenient customer and business access to transfer data.
Transfer Api is secured by Mule OAuth
The Transfer API provides information about the Lab/Sales/Purchase Transfer details from the ICS. It has below endpoints
/ping: This endpoint returns API health.
This endpoint consists of GET method, which gives the health status of the API.
/transfers: This endpoint returns transfer details from the ICS.
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

The following are features and benefits of the Transfer API:
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.

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 of the Transfer record.
2. driverLicense is passed from the request to get the driver information to avoid duplications.
3. licensePlate is passed from the request to get the vehicle information to avoid duplications.
4. Update of a transfer record cannot be performed when the status of the transfer is in “outForDelivery”
5. Receive transfer is only possible with the transfer status is in “outForDelivery” and finalTranfer flag is “True”.
6. Account information is retrieved internally by passing the sourceSystem in the request.
7. Allow the transfer if reserve quantity of package matches with the sales order quantity (order Item requested quantity).
8. Partner can see the open transfers using GET call.
9. Transfer cannot be created if orderFulfilmentMethod value for provided SalesOrder is not Delivery.
10. icsSalesOrderId field is mandatory for transfer creation except if partner Facility is Lab.
11. If transfer status is sent as “out for delivery” then final transfer flag is mandatory to be true.
12. 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. 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. Order items’ requested quantity is validated against package reserve quantity. If mismatch found then validation error is thrown for all types of transfers.
17. Package remaining quantity is validated to be zero. Else error is thrown and user is asked to split package and then try to avoid transferring partial reserved package quantities

Use cases

The API supports data access for the following use cases.