TravelCaster API - ReportBO

Back to Reports home.

The ReportBO is a webhook service that notifies external systems about reservation status changes. When an event occurs, the service automatically sends an asynchronous notification to the configured client endpoint.

Supported Events

  • Issue: Triggered when a new ticket is issued.
  • Void: Triggered when a ticket is voided.
  • Exchange: Triggered when a reservation undergoes a reissue or exchange process.

Endpoint & Credential Configuration

Each Credential is linked to a unique ApiKey that provides security and defines the delivery scope. To receive notifications, the client must provide a secure destination URL.

Security & Protocol

  • Protocol: Must be HTTPS (TLS 1.2 or higher). Plain HTTP endpoints are not supported.
  • URL: A valid destination (e.g., https://client.com).
  • Authentication: The client must validate the Authorization: Bearer <ApiKey> header.

Credential Capabilities

The Credential configuration allows for granular control of the reporting service:

  • Content Filtering: Notifications can be filtered by PCC (Pseudo City Code) and/or IdWeb, ensuring the client only receives relevant data.
  • Multi-Destination Routing: Clients can use multiple Credentials/ApiKeys to route information to different folders or specific endpoint paths based on business logic.

Note: To request additional credentials or inquire about multi-credential setups, please contact our Sales Department.

Delivery Specifications

ReportBO delivers the event data via an HTTP POST request. The payload is sent as a compressed GZip binary to optimize data transfer.

Outgoing Headers

Header Value Description
Method POST The request method used for delivery.
User-Agent Starlings-ReportBO Client identifier for logging and diagnostic purposes.
Authorization Bearer <ApiKey> Authentication token for security.
Content-Type application/json Indicates the media type of the decompressed resource.
Content-Encoding gzip Specifies that the body content is compressed using GZip.
Content-Length [bytes] Size of the GZip compressed binary body.
Content-Disposition attachment; filename="{filename}.json" Pattern: {ZuluDateTime}-{BookingNumber}.json.

Delivery Example

POST /your-endpoint-url HTTP/1.1
Host: your-server.com
User-Agent: Starlings-ReportBO
Authorization: Bearer {{ApiKey}}
Content-Type: application/json
Content-Encoding: gzip
Content-Length: 1318
Content-Disposition: attachment; filename="20260427_182936Z-BL12345.json"

[Binary GZip Content]

Delivery Policy & Acknowledgement

To ensure reliable data delivery and correct processing, please consider the following standards:

  1. Data Handling (GZip): The request body is sent as a GZip compressed binary. The receiving server must decompress the payload before attempting to parse it. Once decompressed, the content is a standard UTF-8 JSON string.
  2. Expected Response: Your endpoint must return an HTTP 200 OK (or any 2xx) status code. This confirms the notification has been successfully received.
  3. Timeout: ReportBO waits up to 30 seconds for a response. If the connection times out or fails, the system will not attempt an automatic redelivery.
  4. Manual Redelivery: In case of delivery failure or a need to reprocess a file, an agent can manually trigger a redelivery from Servicing:
    • Locate the reservation and, under the "Booking history" section, update the status by checking the "Force notification to ReportBO" option.
    • Recommendation: Select the reservation's current status to avoid unintended changes to the booking, unless a status update is specifically required.
  5. Security: Always validate the Bearer token in the Authorization header to ensure the request originates from ReportBO.

Body Document Structure

The following structure represents the JSON schema once the GZip content is decompressed.

Note: Optional fields may be omitted from the JSON payload if they contain no data.

{
  "FileType": "Air",
  "Reservation": {
    "BookingNumber": "BL12345", // Provider locator code.
    "BookingStatus": "Issued", // Values: Issued, Voided, Exchanged, Issued-Exch.
    "UpdateDate": "2026-05-27T18:28:23.770Z", // Zulu DateTime. Event occurrence timestamp.
    "TicketingDate": "2026-05-27T18:28:23.770Z", // ZuluDateTime.
    "BookingDate": "2026-05-27T18:27:58.827Z", // ZuluDateTime.
    "BookingID": 2829437, // Internal booking ID.
    "ExchangedTo": 2815929, // Optional. Exchanged to BookingID.
    "ExchangedFrom": 2815929, // Optional. Exchanged from BookingID.
    "ExternalID": "AS45V673HP", // Optional.
    "Provider": "NDC", // Refers to Providers list.
    "PCCBook": "AAAAA", // Booking PCC.
    "PCCIssue": "BBBBB", // Ticketing PCC.
    "ValidatingCarrier": "LA", // IATA 2-letter code.
    "AirlineLocator": "BL12345A", // Airline locator code.
    "WingsCC": "5553", // Optional. Wings ClientCode.
    "WingsUser": "juan@agency.com", // Optional. Username who created the booking.
    "BuyerDocument": "20341112221" // Optional.
  },
  "Commission": { // MatchBox.
    "Pct": 0.1, // Commission percentage.
    "WingsCDISC": 0.0 // Wings commission discount.
  },
  "Over": { // MatchBox.
    "OverPct": 0.0, // Over percentage.
    "OverCalculation": "D", // Optional. Character - D:Direct - I:Indirect.
    "OverPaxType": "ALL", // Pax Type reference - Values: ALL = All the passengers, "ADT|CHD" = Adult and minor passengers.
    "WingsODISC": 0.0 // Optional. Wings over discount.
  },
  "Fees": {
    "ApiFees": { // Servicing Fees.
      "Application": "ETK", // Applies to ETK tickets.
      "Currency": "USD", // ISO 3-letter code.
      "ContentCost": 0.0, // Optional.
      "ContentFee": 0.0,
      "ApiFee": 7.0
    },
    "WingsFees": { // Wings Fees.
      "Application": "ETK", // Applies to ETK tickets.
      "Currency": "USD", // ISO 3-letter code.
      "CFEE": 0.0, // Wings Consolidator Fee. Optional. May not be returned if not a Wings reservation.
      "AFEE": 0.0 // Wings Agency Fee. Optional. May not be returned if not a Wings reservation.
    }
  },
  "Remark": [ // Optional. Customer-specific remarks.
    {
      "PaxNumber": 1, // Usually associated with passenger 1 by default, though some implementations may use specific passenger mapping.
      "Type": "RMK-CV", // Remark key.
      "Text": "AA11" // Remark value.
    }
  ],
  "Product": {
    "Owner": "AAA", // Agency product owner.
    "OwnProduct": true, // Is the agency the product owner?
    "IdWeb": 1122, // Agency product seller.
    "WebOwner": "BBB", // Agency product seller.
    "OwnChannel": true // Is the agency the product seller?
  },
  "Ratio": [ // Optional.
    {
      "Currency": "USD", // ISO 3-letter code.
      "Amount": 928.0, // Decimal(16, 8).
      "TargetCurrency": "CLP" // ISO 3-letter code.
    }
  ],
  "Van": [ // Optional.
    {
      "Used": true, // Boolean. True if the card was used.
      "CardType": "XXX111223", // Provider.
      "CardNumber": "541111XXXXXX2222" // PCI compliance - Masked number.
    }
  ],
  "Payment": [
    {
      "Number": 1,
      "Type": "FARE", // System values: FARE, FEE, OFFERS / In API implementations, it depends on the implementation.
      "FOPtype": "CC", // Values: CASH, CC.
      "Currency": "USD", // ISO 3-letter code.
      "Amount": 42.6637931, // Decimal(20, 8).
      "Reference": "ALL", // PaxNumber reference - Values: ALL = All the passengers, "1,2" = Passenger 1 and 2.
      "CreditCard": { // Optional. Present if FOPtype is CC.
        "Type": "CA", // 2-letter code.
        "Number": "541111XXXXXX2222", // PCI compliance - Masked number.
        "AuthCode": "123456", // Returns those manually entered by the agent.
        "Installments": 3
      }
    }
  ],
  "Ticket": [
    {
      "TicketId": 3191622,
      "Type": "ETK", // Values: ETK, EMD.
      "SubType": "MainTicket", // ETK values: MainTicket, ConjTicket / EMD values: Provider information.
      "Number": "0452262801209", // Optional. Refers to Ticket information.
      "PaxNumber": 1, // Passenger reference
      "Currency": "CLP", // ISO 3-letter code.
      "TotalAmount": 19796.0, // Decimal(16, 8).
      "FareAmount": 11990.0, // Optional. Decimal(16, 8) - Currently available for ETK.
      "TaxAmount": 7806.0, // Optional. Decimal(16, 8) - Currently available for ETK.
      "RawData": "ETK:ADT_1/ROMERO.DIEGO/0452262801209"
    }
  ],
  "Segment": [
    {
      "LegNumber": 1,
      "SegmentNumber": 1,
      "Airline": "LA", // IATA 2-letter code.
      "Number": 150, // Flight number.
      "DepartureAirport": "SCL", // IATA 3-letter code.
      "DepartureDate": "2025-12-24T11:14:00", // ISO 8601 yyyy-MM-ddTHH:mm:ss format.
      "ArrivalAirport": "CJC", // IATA 3-letter code.
      "ArrivalDate": "2025-12-24T13:21:00", // ISO 8601 yyyy-MM-ddTHH:mm:ss format.
      "BookingClass": "A" // Class of service.
    }
  ],
  "Pax": [
    {
      "PaxNumber": 1,
      "PaxRef": "ADT_1",
      "FirstName": "DIEGO",
      "LastName": "ROMERO",
      "Type": "ADT", // Values: ADT, CHD, INF, YTH, C03..C12.
      "Purchase": { // Sales Information.
        "Currency": "USD", // ISO 3-letter code.
        "Fare": 12.92025862, // Decimal(16, 8).
        "Tax": 8.41163793 // Decimal(16, 8).
      }
    }
  ],
  "Tax": [
    {
      "TicketId": 3191622, // Ticket reference
      "TaxDetails": [ // Optional. Currently available for ETK.
        {
          "Code": "CL",
          "Amount": 7806.0 // Expressed in the respective Ticket.Currency.
        }
      ]
    }
  ]
}

Implementation information

This section details the business logic and technical rules required to correctly process the ReportBO data. To ensure a successful integration, please review the detailed technical guidelines in the following link:

Providers list

For a detailed reference of supported travel providers and their respective codes, please refer to the following global list:

Change log

Date Affects versions Change detail
2026-04-27 1.0 Initial version.

Back to Reports home.

See change history for this file
Loading...