Table of Contents

eSIM Orders Search API Documentation

Overview

This API allows users to search for existing eSIM orders. It supports pagination and can return a list of orders matching the search criteria (if any are provided). By default, with an empty request body, it fetches a paginated list of all orders.

API Endpoint

  • URL: {{host}}/hub/esim/orders/search
  • Method: POST
  • Content-Type: application/json

Headers

Key Value Description
Authorization Bearer {token} Access token (Required)
Content-Type application/json Request/Response format

Request Body Parameters

The request body can be an empty JSON object {} to retrieve all orders with default pagination. Specific filter parameters may be supported but are not demonstrated in this example.

Field Type Required Description Example/Values
{} Object ✅ Yes An empty object for a general search, or an object containing filter criteria. {}

(Note: For specific filter fields, please refer to more detailed API specifications if available. This example shows a general search.)

Sample Request

curl --location '{{host}}/hub/esim/orders/search' \
--header 'Authorization: Bearer {token}' \
--header 'Content-Type: application/json' \
--data '{}'

Sample Response

{
  "durationInMilisecond": 33,
  "totalCount": 49,
  "totalPage": 3,
  "pageSize": 20,
  "pageIndex": 0,
  "clientOverride": false,
  "data": [
    {
      "id": "9bfefcf5-681b-42c3-bc1f-4553d2ca7de4",
      "readableId": "ES300525G001",
      "orderBaseInfo": {
        "providerCode": "esim.provider1",
        "providerReferenceId": "140",
        "status": "CLOSED",
        "statusIsFinal": true,
        "bookingType": "esim",
        "totalAmount": 1000.0,
        "totalAmountUSD": 0.0,
        "totalAmountVND": 0.0,
        "currency": "VND",
        "convertionRate": 0.0,
        "isNeedRebookPNR": false,
        "passengerCount": 0,
        "totalAmountAtHotel": 0.0,
        "refunded": false
      },
      "orderESimInfo": {
        "id": "ef4287ce-777f-43c1-8f30-6444b1185ced",
        "eSimBookingId": "9bfefcf5-681b-42c3-bc1f-4553d2ca7de4",
        "name": "GIGAGO DEMO",
        "countries": ["vn"],
        "operator": "VN",
        "qrCode": "LPA:1$viettelvietnam.validspereachdpplus.com$7TQ581WXZQEUNHIMUYG95TJNT0AKU68F4P6LYNNWBI0HSF8N7E3989G4DN1V07H1",
        "phoneNumber": "1698552134",
        "serialNumber": "8984048000941504283",
        "description": "GIGAGO DEMO - 0GB/1 days",
        "data": "0GB",
        "validityPeriod": "1",
        "accessPointName": "internet",
        "amount": 1000.0
      },
      "createdBy": "5B212B75-A969-4104-B528-4A3365327603",
      "createdUtc": "2025-05-30T04:08:19:8734",
      "updatedBy": "System",
      "updatedUtc": "2025-05-30T04:08:21:1668"
    }
    // ... other order objects
  ]
}

Response Field Description

This section describes the fields returned in the API response. All field description tables in this section follow the | Field | Type | Example | Description | format.

Root Level Fields

Field Type Example Description
durationInMilisecond Number 33 The time taken to process the request, in milliseconds.
totalCount Integer 49 Total number of orders matching the criteria across all pages.
totalPage Integer 3 Total number of pages available for the current pageSize.
pageSize Integer 20 Number of orders returned per page.
pageIndex Integer 0 The current page index (0-based).
clientOverride Boolean false Indicates if client-side overrides were applied to the query.
data Array [...] An array of Order Objects. Each object represents an eSIM order.

Order Object (in data array)

Each object in the data array represents an individual eSIM order.

Field Type Example Description
id String "9bfefcf5-..." Unique identifier for the order (UUID).
readableId String "ES300525G001" Human-readable identifier for the order.
orderBaseInfo Object {...} Order Base Information Object
orderESimInfo Object {...} Order eSIM Information Object
createdBy String "5B212B75-..." or email Identifier of the user/system that created the order.
agentId String "NV9999" (Optional) Identifier for the agent, if applicable.
createdUtc String "2025-05-30T04:08:19:8734" UTC timestamp when the order was created.
updatedBy String "System" Identifier of the user/system that last updated the order.
updatedUtc String "2025-05-30T04:08:21:1668" UTC timestamp when the order was last updated.

Order Base Information Object

Details about the base order.

Field Type Example Description
providerCode String "esim.provider1" Code of the eSIM provider.
providerReferenceId String "140" Reference ID from the provider for this order.
status String "CLOSED" Current status of the order (e.g., PENDING, CLOSED, CANCELED, REFUNED).
statusIsFinal Boolean true Indicates if the current status is final.
bookingType String "esim" Type of booking.
totalAmount Number 1000.0000 Total amount of the order in the order currency.
totalAmountUSD Number 0.0 Total amount of the order in USD (if applicable).
totalAmountVND Number 0.0 Total amount of the order in VND (if applicable).
currency String "VND" Currency of the totalAmount.
convertionRate Number 0.0 Conversion rate used, if applicable.
isNeedRebookPNR Boolean false Flag indicating if PNR rebooking is needed.
passengerCount Integer 0 Number of passengers (typically 0 for eSIM).
totalAmountAtHotel Number 0.0 Amount to be paid at hotel (not for eSIM).
refunded Boolean false Indicates if the order has been refunded.

Order eSIM Information Object

Details the characteristics and provisioning information for the eSIM item(s) within this order.

Field Type Example Description
id String "ef4287ce-..." Unique identifier for this eSIM order item.
eSimBookingId String "9bfefcf5-..." References the main order ID (id from the parent Order Object).
name String "GIGAGO DEMO" Name of the eSIM product as ordered.
countries Array of String ["vn"] or [] List of 2-letter ISO country codes covered. May be empty.
operator String "VN" (Optional) Operator associated with the eSIM. Not present on all items.
qrCode String "LPA:1$viettel...H1" (Optional) QR code string for eSIM activation. Not present if order failed.
phoneNumber String "1698552134" (Optional) Phone number associated with the eSIM. Not present if order failed.
serialNumber String "8984048000..." (Optional) Serial number (ICCID) of the eSIM. Not present if order failed.
description String "GIGAGO DEMO - 0GB/1 days" Description of the eSIM product.
data String "0GB" Data allowance of the ordered eSIM.
validityPeriod String "1" Validity period in days of the ordered eSIM.
accessPointName String "internet" APN (Access Point Name) for the eSIM.
amount Number 1000.0000 Price of a single eSIM unit in this order.

Notes

  • The response is paginated. The client should use pageIndex and pageSize to retrieve subsequent sets of data if totalPage is greater than 1.
  • The data array in the response contains a list of order objects. Each order object provides detailed information about a specific eSIM order.
  • Fields like qrCode, phoneNumber, and serialNumber within orderESimInfo are typically available for successfully provisioned eSIMs (e.g., status CLOSED). These fields might be absent or null for orders with other statuses, such as REFUNDED or CANCELED.
  • The orderESimInfo.operator field might not be present for all eSIM products or in all states of the order.
  • The agentId field in the Order Object appears to be optional.