openapi: 3.0.3
info:
  title: ITT eSIM API
  version: 1.0.0
  description: |
    The ITT eSIM API exposes connectivity services that complement the existing Hotel APIs
    in the travel platform. Hotel services cover accommodation search, content and booking,
    while the eSIM services let you attach mobile data connectivity to the same customer
    journeys.

    This specification focuses exclusively on the eSIM services. Hotel APIs are documented
    separately in the Hotel API specification and are currently available for production
    use. The eSIM endpoints described here are available only via the REST interface and
    are not yet accessible through WSIM based integrations.

    Typical integration pattern:

    - Use Hotel APIs to search and book accommodation.
    - Use the eSIM APIs from this document to search, price and book data connectivity
      for the same traveller and trip.
    - Present eSIM options as an add-on in the booking flow or post-booking journeys.

    Key eSIM flows and their endpoints:

    - Plan discovery and selection
      - [Search eSIM plans](/esim/search)
      - [Get single eSIM package](/esim/single-esim-package)
    - Customer and booking lifecycle
      - [Update customer information](/esim/update-customer)
      - [Create eSIM booking](/esim/create-booking)
      - [Get booking details](/esim/booking-details)
    - Post-purchase operations
      - [Get data usage](/esim/data-usage)
      - [Get installation instructions](/esim/installation-instructions)
      - [Get compatible devices](/esim/compatible-devices)
    - Top-up and ongoing spend
      - [Get top-up packages](/esim/topup-packages)
      - [Create top-up booking](/esim/topup-booking)
      - [Get top-up history](/esim/topup-history)
    - Eventing
      - [Register webhook](/esim/register-webhook)
servers:
  - url: serviceapi.tripapi.site
tags:
  - name: eSim
    description: eSIM related operations
security:
  - apiKeyAuth: []
    secretCodeAuth: []
paths:
  /esim/search:
    post:
      tags: [eSim]
      summary: Search eSIM plans
      description: |
        Searches for available eSIM plans for a given region, country or supplier. Use this
        endpoint to build the initial connectivity offer alongside hotel search results,
        then narrow down to a specific package with `/esim/single-esim-package`.
      operationId: esimSearch
      requestBody:
        required: true
        content:
          application/json:
            schema:
              type: object
              additionalProperties: true
            examples:
              default:
                value:
                  eSim:
                    region_type: local
                    country_code: BD
                    plan_type: data
                    topup_included: yes
                  supplier_uid: all
                  partner_id: "1"
                  short_ref: xxxx111
                  language: en
      responses:
        '200':
          description: Search results
          content:
            application/json:
              schema:
                type: object
                additionalProperties: true
        '400': { $ref: '#/components/responses/BadRequest' }
        '401': { $ref: '#/components/responses/Unauthorized' }
        '500': { $ref: '#/components/responses/ServerError' }
  /esim/single-esim-package:
    post:
      tags: [eSim]
      summary: Get single eSIM package
      description: |
        Retrieves detailed information and pricing for a specific eSIM package that was
        returned from `/esim/search`. The response can be used to confirm the offer shown
        to the user before creating a booking with `/esim/create-booking`.
      operationId: singleEsimPackage
      requestBody:
        required: true
        content:
          application/json:
            schema:
              type: object
              additionalProperties: true
            examples:
              default:
                value:
                  tracking_id: 11763299361URM1
                  package_id: X1AO00012||bangladesh||1067||fatafati-in-7days-1gb
      responses:
        '200':
          description: Package details
          content:
            application/json:
              schema:
                type: object
                additionalProperties: true
        '400': { $ref: '#/components/responses/BadRequest' }
        '401': { $ref: '#/components/responses/Unauthorized' }
        '500': { $ref: '#/components/responses/ServerError' }
  /esim/update-customer:
    post:
      tags: [eSim]
      summary: Update customer information
      description: |
        Updates passenger and contact details on an existing eSIM booking. Call this
        endpoint after hotel or itinerary changes so that the connectivity order has the
        same traveller profile and contact information as the related hotel booking.
      operationId: updateCustomer
      requestBody:
        required: true
        content:
          application/json:
            schema:
              type: object
              additionalProperties: true
            examples:
              default:
                value:
                  booking_tracking_id: 11176335754526194RQYGH
                  member_id: "2"
                  save_pax: yes
                  passenger:
                    - pax_id: "1"
                      pax_type: ADT
                      title: MR
                      first_name: Jasim
                      last_name: Karimm
                      age: "30"
                      isd_code: "880"
                      contact_no: 1966330000
                      email_address: test@mail.com
      responses:
        '200':
          description: Updated
          content:
            application/json:
              schema:
                type: object
                additionalProperties: true
        '400': { $ref: '#/components/responses/BadRequest' }
        '401': { $ref: '#/components/responses/Unauthorized' }
        '500': { $ref: '#/components/responses/ServerError' }
  /esim/create-booking:
    post:
      tags: [eSim]
      summary: Create eSIM booking
      description: |
        Creates a confirmed eSIM booking for one or more packages. Typically called after
        hotel booking confirmation, using the same member and contact details so that eSIM
        vouchers and installation instructions can be surfaced in the same post-booking
        experience.
      operationId: createBooking
      requestBody:
        required: true
        content:
          application/json:
            schema:
              type: object
              additionalProperties: true
            examples:
              default:
                value:
                  booking_tracking_id: 11176335754526194RQYGH
                  package_tracking_id: 11176335754526194RQYGH||fatafati-in-7days-1gb
                  eSim_quantity: "1"
                  member_id: "2"
                  isPartialPay: no
                  redirect_url: https://test.example.com/test-tech/custom_modal.html
                  payment_type: account_balance
                  isd_code: "880"
                  contact_no: 1966330000
                  email_address: iam@mail.com
                  agency_email: iam@mail.com
      responses:
        '200':
          description: Booking created
          content:
            application/json:
              schema:
                type: object
                additionalProperties: true
        '400': { $ref: '#/components/responses/BadRequest' }
        '401': { $ref: '#/components/responses/Unauthorized' }
        '500': { $ref: '#/components/responses/ServerError' }
  /esim/data-usage:
    post:
      tags: [eSim]
      summary: Get data usage
      description: |
        Returns data usage for a provisioned eSIM, including remaining balance and
        consumption trends. Use this to power “trip dashboard” or “upcoming stay” views
        where usage is shown next to hotel and itinerary details.
      operationId: dataUsage
      requestBody:
        required: true
        content:
          application/json:
            schema:
              type: object
              additionalProperties: true
            examples:
              default:
                value:
                  member_id: "2"
                  tracking_id: 11176276126126194RHSGI
                  eSim_iccid: "873000000000040589"
      responses:
        '200':
          description: Usage details
          content:
            application/json:
              schema:
                type: object
                additionalProperties: true
        '400': { $ref: '#/components/responses/BadRequest' }
        '401': { $ref: '#/components/responses/Unauthorized' }
        '500': { $ref: '#/components/responses/ServerError' }
  /esim/booking-details:
    post:
      tags: [eSim]
      summary: Get booking details
      description: |
        Retrieves the full details of an eSIM booking, including package, traveller, and
        status information. This is the primary read endpoint to keep your UI in sync
        when showing combined hotel, flight or activity bookings with attached eSIMs.
      operationId: bookingDetails
      requestBody:
        required: true
        content:
          application/json:
            schema:
              type: object
              additionalProperties: true
            examples:
              default:
                value:
                  member_id: "2"
                  tracking_id: 11176276126126194RHSGI
                  booking_id: ES2510NOKJAAFK
      responses:
        '200':
          description: Booking info
          content:
            application/json:
              schema:
                type: object
                additionalProperties: true
        '400': { $ref: '#/components/responses/BadRequest' }
        '401': { $ref: '#/components/responses/Unauthorized' }
        '404': { $ref: '#/components/responses/NotFound' }
        '500': { $ref: '#/components/responses/ServerError' }
  /esim/installation-instructions:
    post:
      tags: [eSim]
      summary: Get installation instructions
      description: |
        Provides device-specific installation instructions for a purchased eSIM, in the
        requested language. Use this endpoint to embed install guides into your trip
        confirmation flows alongside hotel check-in instructions.
      operationId: installationInstructions
      requestBody:
        required: true
        content:
          application/json:
            schema:
              type: object
              additionalProperties: true
            examples:
              default:
                value:
                  member_id: "1"
                  tracking_id: 11176276126126194RHSGI
                  eSim_iccid: "873000000000040589"
                  preferred_language: en
      responses:
        '200':
          description: Instructions
          content:
            application/json:
              schema:
                type: object
                additionalProperties: true
        '400': { $ref: '#/components/responses/BadRequest' }
        '401': { $ref: '#/components/responses/Unauthorized' }
        '500': { $ref: '#/components/responses/ServerError' }
  /esim/compatible-devices:
    post:
      tags: [eSim]
      summary: Get compatible devices
      description: |
        Returns the list of devices that are compatible with the eSIM offering. This can
        be used during hotel or package checkout to pre-validate that travellers’ phones
        and tablets support eSIM before you surface connectivity upsells.
      operationId: compatibleDevices
      requestBody:
        required: true
        content:
          application/json:
            schema:
              type: object
              additionalProperties: true
            examples:
              default:
                value:
                  member_id: 1
      responses:
        '200':
          description: List of devices
          content:
            application/json:
              schema:
                type: object
                additionalProperties: true
        '400': { $ref: '#/components/responses/BadRequest' }
        '401': { $ref: '#/components/responses/Unauthorized' }
        '500': { $ref: '#/components/responses/ServerError' }
  /esim/topup-packages:
    post:
      tags: [eSim]
      summary: Get top-up packages
      description: |
        Lists available top-up options for an active eSIM. Call this endpoint when
        building account or “manage booking” pages so that travellers staying at a hotel
        can purchase additional data without leaving your application.
      operationId: topupPackages
      requestBody:
        required: true
        content:
          application/json:
            schema:
              type: object
              additionalProperties: true
            examples:
              default:
                value:
                  member_id: "1"
                  tracking_id: 11176328969726194MHHQA
                  eSim_iccid: "873000000000042014"
      responses:
        '200':
          description: Packages
          content:
            application/json:
              schema:
                type: object
                additionalProperties: true
        '400': { $ref: '#/components/responses/BadRequest' }
        '401': { $ref: '#/components/responses/Unauthorized' }
        '500': { $ref: '#/components/responses/ServerError' }
  /esim/topup-booking:
    post:
      tags: [eSim]
      summary: Create top-up booking
      description: |
        Creates a booking for a selected top-up package. This is usually invoked from a
        self-service area where the traveller is reviewing their hotel stay and chooses
        to add more data for the same trip.
      operationId: topupBooking
      requestBody:
        required: true
        content:
          application/json:
            schema:
              type: object
              additionalProperties: true
            examples:
              default:
                value:
                  booking_tracking_id: 11176681417103210LPBXA
                  topup_tracking_id: TUP11766825537SLD1
                  package_id: 8900000644360253498||asialink-7days-1gb-topup
                  member_id: "2"
                  redirect_url: https://itttest.example.com/booking-details/e-sim?tracking_id=11176681417103210LPBXA&
                  payment_type: onlinepayment
                  isd_code: "880"
                  contact_no: 1966330000
                  email_address: iam@saaqeb.com
                  agency_email: iam@saaqeb.com
      responses:
        '200':
          description: Top-up booking created
          content:
            application/json:
              schema:
                type: object
                additionalProperties: true
        '400': { $ref: '#/components/responses/BadRequest' }
        '401': { $ref: '#/components/responses/Unauthorized' }
        '500': { $ref: '#/components/responses/ServerError' }
  /esim/topup-history:
    post:
      tags: [eSim]
      summary: Get top-up history
      description: |
        Returns historical top-up transactions for a given eSIM. Use this to show spend
        history and support flows (for example, confirming charges related to a hotel
        stay or corporate trip).
      operationId: topupHistory
      requestBody:
        required: true
        content:
          application/json:
            schema:
              type: object
              additionalProperties: true
            examples:
              default:
                value:
                  member_id: "1"
                  tracking_id: 11176328969726194MHHQA
                  eSim_iccid: "873000000000042014"
      responses:
        '200':
          description: History
          content:
            application/json:
              schema:
                type: object
                additionalProperties: true
        '400': { $ref: '#/components/responses/BadRequest' }
        '401': { $ref: '#/components/responses/Unauthorized' }
        '500': { $ref: '#/components/responses/ServerError' }
  /esim/register-webhook:
    post:
      tags: [eSim]
      summary: Register webhook
      description: |
        Registers a webhook subscription so that your platform can receive asynchronous
        events such as low data balance or lifecycle updates. These events can be used to
        trigger notifications inside your travel UI, for example while the traveller is
        viewing upcoming or in-progress hotel stays.
      operationId: registerWebhook
      requestBody:
        required: true
        content:
          application/json:
            schema:
              type: object
              additionalProperties: true
            examples:
              default:
                value:
                  supplier_code: airalo
                  supplier_uid: X1AO00065
                  notification_type: webhook_low_data
      responses:
        '200':
          description: Webhook registered
          content:
            application/json:
              schema:
                type: object
                additionalProperties: true
        '400': { $ref: '#/components/responses/BadRequest' }
        '401': { $ref: '#/components/responses/Unauthorized' }
        '500': { $ref: '#/components/responses/ServerError' }
components:
  securitySchemes:
    apiKeyAuth:
      type: apiKey
      in: header
      name: apikey
    secretCodeAuth:
      type: apiKey
      in: header
      name: secretecode
  responses:
    BadRequest:
      description: Bad request
      content:
        application/json:
          schema:
            type: object
            properties:
              error:
                type: string
    Unauthorized:
      description: Unauthorized
      content:
        application/json:
          schema:
            type: object
            properties:
              error:
                type: string
    NotFound:
      description: Not found
      content:
        application/json:
          schema:
            type: object
            properties:
              error:
                type: string
    ServerError:
      description: Server error
      content:
        application/json:
          schema:
            type: object
            properties:
              error:
                type: string
