• Register

Update Booking API Documentation

Guide to Update Booking API

API Spec⬇️ API ConsolePostman Collection⬇️

Welcome to the JAS Connect Update Booking API. This service allows your business applications (such as an ERP, TMS, or e-commerce platform) to communicate directly with our core booking systems. 

By integrating with this REST-based API, you can automate your entire booking update process, enabling your systems to directly register new bookings with JAS in an easy and automated way. This guide provides a complete overview of how to use the Update Booking API services to get started. 

Key Capabilities & Features 

Our Booking API is a powerful service designed for simplicity, security, and accuracy. 

  • Update Bookings: The API's primary function is to update existing bookings in the JAS system that have not been converted to a shipment for transport. Once a booking has been converted to a shipment by the operations team for transport, it can no longer be updated.To update a booking you must provide a valid JobNumber (BookingNumber) or HouseBillNumber.  If a HouseBillNumber is provided and more than one booking is found to have that house bill number, then you will receive a response advising that a JobNumber must be provided. 

  • Flexible Data Formats: We support both major data formats for your convenience. You can submit your booking requests in either application/json or application/xml. 

  • Secure & Encrypted: All API communication is secured. We use the OAuth 2.0 protocol for authentication, and all web calls are made over HTTPS to ensure your data is always encrypted in transit. 

  • Robust Error Handling: The API provides clear and accurate error handling. You will receive standard HTTP response codes (like 400 Bad Request or 401 Unauthorized) to help your team debug any issues with an integration request . 

Getting Started: Authentication & Endpoints 

All API requests must be securely authenticated before they can interact with the system. Accessing the API is a two-step process. 

Step 1: Generate an Access Token 

Before you can update a booking, you must request a bearer token using the OAuth 2.0 client_credentials grant type. 

  • Method: POST 

  • Endpoint: https://<<URL_PROVIDED_IN_THE_PORTAL >>/oauth2/token 

  • Headers: Content-Type: application/x-www-form-urlencoded 

Body parameters 

Values 

grant_type 

client_credentials 

client_id 

<YOUR_CLIENT_ID> 

client_secret 

<YOUR_CLIENT_SECRET> 

Step 2: Call the Booking API 

Once you have your access token, you can call the UpdateBooking endpoint. You must include the token to every request. 

Required Headers: 

  

Authorization 

Bearer <<ACCESS_TOKEN>> 

Content-Type 

application/json or application/xml 

  • API Endpoints (Method: POST ): 

  • Test: https://<<TEST_INSTANCE_URL_IN_PORTAL>> 

  • Production: https://<<PROD_INSTANCE_URL_IN_PORTAL>> 

  • Resources: 

  • JSON: /v1/Booking/UpdateBookingjson 

  • XML: /v1/Booking/UpdateBookingxml 

Understanding the API Flow 

The process of updating a booking is straight forward. 

1. Request Validation 

When JAS receives your UpdateBooking request, our system first performs a validation. This check ensures: 

  • Your Authentication headers are valid. 

  • Your Content-Type header matches the endpoint (e.g., application/json for the UpdateBookingjson endpoint). 

  • Your request payload is well-formed and includes all mandatory fields. A 400 Bad Request error will be returned if there are mismatches or other issues with the request . 

  • Only a single booking can be updated per API call.  Thus, if multiple bookings are found to contain the provided house bill number, then the API will return stating multiple bookings found.  It is then required that the unique JobNumber/Booking Number be provided to update the booking. 

2. Update Booking & Receive Confirmation 

After a successful validation, JAS updates the booking in our system. The API will return a synchronous response in the same format you sent (JSON or XML), indicating the result: 

  • On Success (Code 200 ): You will receive a response containing: 

  • "Success": true 

  • "JobNumber": "S508480248" (This is your Booking ID) 

  • On Failure: You will receive a response with: 

  • "Success": false 

  • "Error": "Detailed error message..." 

  • This can be due to business logic errors or unexpected server issues (e.g., 500 Internal Server Error ). 

Core Data Structure 

A booking update request is built from several primary data collections. Full specification is available for download, but the key components are: 

  • Details : The main information about the booking, including the mandatory ContainerMode and TransportModeCode , as well as ServiceLevelCode , GoodsDescription , and total weight/volume.  JobNumber and HouseBillNumber are in this section and one of the two are required to update a booking. 

  • ClientAddress: Information about your organization (the "client") that is placing the booking. 

  • ShippersAddress: The full address and contact details for the party sending the goods. 

  • ConsigneeAddress: The full address and contact details for the final recipient of the goods. This section contains several mandatory fields, including Address1, City, CompanyName, CountryCode, and PostCode. 

  • DateCollection : Contains critical dates for the booking, including the mandatory PickupRequiredBy date and time. 

  • OrderNumberCollection : A list where you can provide your internal order references. 

  • AdditionalReferenceCollection : Allows you to add other key business identifiers, such as a Purchase Order Number (Code: PO) or Client Reference (Code: CRF) . 

  • NoteCollection: Allows you to add standard or custom notes to the shipment. 

  • PackingLineCollection: A detailed, item-level list of the goods being shipped. You can include unlimited packing lines. Each line must include: 

    • ItemNo (Line Number) 

    • GoodsDescription 

    • PackQty (Package Quantity) 

    • PackTypeCode (e.g., PKG, CTN, PLT) 

    • Weight 

    • WeightUnitCode (e.g., KG, LB) 

    • ContainerCollection : For sea freight, this collection specifies the ContainerType (e.g., 20GP, 40HC) and Quantity . 

version 4 as of 4 days ago by Saksham Thakur

0 Comments

Please sign in to post a comment.