Order a Lab Shop flow

0. Types of items available in the lab shop

Items

There are three item types available in the lab shop to be ordered:

Lab test: To fetch a list of all available lab test items, call the GET /item/lab-item/lab-test/ endpoint.
Lab panel: To fetch a list of all available lat panel items, call the GET /item/lab-item/lab-panel/ endpoint
Home kit: To fetch a list of all available home kit items, call the GET /item/lab-item/home-kit/ endpoint

The first two have a similar order flow, while the third one (home kit) has a slightly different flow. We'll talk about the ordering details later.

You can also list all available items of the three item types, calling the GET /item/lab-item/ endpoint.

Sample response:

[
  {
    "id": "68410265-0c9a-4d8d-a54b-8f50ea346021",
    "item_type": "lab-panel",
    "lab_tests": [
      "34274142-022e-4468-a681-443af3a49c5e"
    ],
    "updated_at": "2021-12-06T15:45:58.239271Z",
    "supplier_item_number": "N/A",
    "description": "",
    "name": "Hepatic Function Panel without Total Protein",
    "price": 2000,
    "supplier_package_id": "",
    "preparations": "Please do not exercise prior to testing. It is best that your blood is taken in a rested state.",
    "sample_report": "",
    "text": "Albumin, Total Bilirubin, Direct Bilirubin, Indirect Bilirubin (calculated), Alkaline Phosphatase, AST, ALT",
    "video": "",
    "archived": false,
    "supplier": "6fac37aa-3e3b-4000-bbb8-8f763d208451",
    "categories": [
      "9c2e05c0-1606-490d-85a7-9cdc9324dd8f"
    ],
    "collection_methods": []
  },
  ...
]

In the response, the categories and collection_methods fields are returned. They contain the list of IDs of the associated categories and collection methods, their description can be obtained in the following endpoints:

Collection methods

To get the list and details of all collection methods, call the GET /collection-method endpoint.

1. Placing the order

Get or create a profile

Before placing the order, you should have a profile_id to attach to the order during the create request. You can create the profile or get an existing one from the profiles endpoints.
You need to pass the profile_id in the profile field of the payload. Even though the endpoint doesn't require this field, it's necessary because this is the client that will be attached to the order so you can later track the results once they are available.

To place an order, you will call the POST /order/lab-shop-order/ endpoint.

A sample request looks like the following:

POST https://qa-selfdecode.com/service/orders/order/lab-shop-order/
Request body:

{
  "first_name": "John",
  "last_name": "Doe",
  "email": "[email protected]",
  "phone_number": "0123456789",
  "gender": "Male",
  "birth_date": "1990-01-01",
  "ethnicity": "South Asian (e.g. Indian, Pakistani, Bangladeshi, Nepali)",
  "line_items": [
    {
      "quantity": 1,
      "item": "e7a5e785-0d94-4004-9105-fb5d27060492"
    }
  ],
  "ship_to_address": "Street 5",
  "ship_to_address1": "",
  "ship_to_city": "Birmingham",
  "ship_to_state": "AL",
  "ship_to_postal_code": "54000",
  "ship_to_country": "United States of America",
  "profile": "978642eb-fe4b-46b4-a5cc-e010e6eb413b",
  "user_id": "ede136be-65ca-4bc7-99b9-7dfc7c053c47"
}

A field of major concern in the above payload is the line_items field. Please note that the field can contain as many line items, with the desired quantity of each item. In a single POST request, you can bulk order line items of all three types ("lab-panel", "lab-test", "home-kit"). Just make sure you populate the item field with the correct ID of the desired item. You can obtain the IDs of the items from the endpoints mentioned in Step 0, and use them in this POST request.

The order will be collectively posted in a single request, even if it has line items of all three types, but as mentioned in Step 0, there is a difference in the order state management and flow for different types. Keeping this difference in mind and for ease of understanding, you can find two sequence diagrams in the subsequent pages, one for "lab-panel" and "lab-test", and another for "home-kit".

2. Listing lab shop orders

Once an order is successfully created, you can either list all lab shop orders created or get one by id. To do so, call the GET /order/lab-shop-order/ or the GET /order/lab-shop-order/{order_id}. A sample request would look like this:

GET https://qa-selfdecode.com/service/orders/order/lab-shop-order/ede136be-65ca-4bc7-99b9-7dfc7c053c47/

This would help you get the current status of the order and the status of the results attached.

2.1 Get the PDF

You can pass the query param ?pdf=true to the GET endpoint to retrieve the PDF associated with the order. When this parameter is passed, you get a new field called encoded_pdf, which contains the base64 encoded PDF and it can be the requisition or the results PDF depending on the status of the order.

3. Order progress, status, and results

After the order is created, there is a scheduled task that runs every 10 minutes, which will send the order to the lab provider. Once the order is sent, you will see the changes reflected in the lab shop order object, like this:

Creation failed in the provider

The field api_error will change to true and the api_error_message will show the detail of the error. Usually it's because there is something wrong with the data passed during the order creation, so you will need to create a new order with the relevant fixes according to the error message. If the error cannot be fixed by changing the order creation data, please contact us and we will check the issue.

Order successfully created in the provider

Once the order is created in the provider and depending on the items you ordered, you'll get one of these two fields populated with data, lab_order and/or home_kit_order.

In these fields, you'll get an object with a status field, which can help you track the progress of the order. The statuses depend on the type of order and are listed below:

Lab Order Statuses

Status	Order Progress
PENDING	The order was created by the supplier and is waiting to be processed.
APPROVED	The order is approved by the provider and the requisition file is ready.
REJECTED	The provider found an issue during the processing of the order and rejected it. Need to contact the provider to figure out the issue.
CANCELLED	This is used to manually cancel the orders either by the provider or customer support.
RESULTED	The raw results of the lab order have been received by SD from the lab provider.

Home Kit Order Statuses

Status	Order Progress
PENDING	The order was created by the supplier and is waiting to be processed
APPROVED	The order is approved by the provider and the tests are being prepared.
REJECTED	The provider found an issue during the processing of the order and rejected it. Need to contact the provider to figure out the issue.
CANCELLED	This is used to manually cancel the orders either by the provider or customer support.
SHIPPED	The test kit has been shipped to the user.
RESULTED	The results of the home kit order have been received by SD from the lab provider

Once the order status is resulted, it means that the raw results have been received from the lab provider by orders service on SD platform. As soon as results are received in orders service, they are emitted to the labs service where a QueuedLabShopResult entity is created, which contains the raw / unprocessed results.

The QueuedLabShopResult is later processed by a cron job in the labs service.

To know the status of your results in the processing queue , after confirming that the order has been resulted, you can make a call to the /labs/queued-lab-shop-result/ endpoint, providing the lab_shop_order_id as a query parameter.

It’s response will be one of the following:

An empty list, meaning that there is yet no QueuedLabShopResult against the passed lab_shop_order_id
[{"status":"pending","error_message":""}]
This means that the order results were received from the orders service, and are now waiting to be processed and ingested in the labs database
[{"status":"error","error_message":"some error message"}]
This means that there was an error during processing those results and saving them to the labs database.
[{"status":"success","error_message":""}]
This means that the results were processed successfully and saved in the labs service, and can now be queried with GET labs/result/?lab_shop_order_id endpoint.