Qargo Use case / Location booking API

Required api role: not applicable (push/push) Purpose: This interface allows an external party to integrate with warehouse management systems and location booking platforms. The location booking uses a push/push model: Qargo pushes a booking dispatch payload to an external endpoint. The third party then updates Qargo with booking status changes using our webhook endpoint:  ### Operations Each dispatch payload includes an `operation` field indicating the type of action: | Operation | Description | |-----------|-------------| | `CREATE` | New booking request. The external system should create a time slot reservation. | | `UPDATE` | Booking details have changed (e.g. updated time window, different vehicle). | | `CANCEL` | The booking is no longer needed and should be released. | ### Booking scenarios The `scenario` field indicates the direction of goods movement at the location: | Scenario | Description | |----------|-------------| | `INBOUND` | Goods are being delivered to the location (e.g. warehouse receiving). | | `OUTBOUND` | Goods are being picked up from the location (e.g. warehouse shipping). | | `INBOUND_OUTBOUND` | Both pickup and delivery happen at the same location in a single booking. | ### Status lifecycle The external system updates the booking status via the [booking update webhook](/docs/use-case-location-booking/location-booking-update-webhook): | Status | Description | |--------|-------------| | `TO_REQUEST` | Initial state - booking has not yet been sent to the external system. | | `REQUESTED` | Booking request sent, awaiting confirmation from the location. | | `BOOKED` | Time slot confirmed by the location. | | `CANCELLED` | Booking was cancelled. | ### Payload structure The dispatch payload contains: - **Trip information**: trip ID, name, and orders linked to the booking - **Booking details**: booking ID, booking name, location address, and relevant stops - **Resources**: vehicle, trailer, and resource allocations assigned to the trip The destination of the dispatch can be a RESTful interface or file-based protocol like SFTP. ### Update payload The [booking update webhook](/docs/use-case-location-booking/location-booking-update-webhook) is the inbound channel the external system uses to send booking confirmations, status changes, and execution status updates back to Qargo. Each update carries: - **Booking reference**: either the Qargo booking `id` or a `match` (matching criteria agreed with the external system) - **Status**: new booking status (`REQUESTED`, `BOOKED`, `CANCELLED`) - **Execution statuses**: fine-grained status tracking with event times and remarks - **Question answers**: answers to questions configured on the booking, mapped onto the order