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. driverLicense is passed from the request to get the driver information to avoid duplications.
2. licensePlate is passed from the request to get the vehicle information to avoid duplications.
3. Update of a transfer record cannot be performed when the status of the transfer is in “outForDelivery”
4. Receive transfer is only possible when transfer status is in “outForDelivery” along with finalTranfer flag is “True”.
5. Account information can be retrieved internally by passing the sourceSystem in the request.
6. If quantity of package matches with the sales orderItems quantity then only Transfer is allowed for creation.
7. transfer cannot be created as orderFulfilmentMethod for provided SalesOrder is not Delivery

Use cases

The API supports data access for the following use cases.