openapi: 3.2.0
info:
  title: Brutus Bookings API
  contact:
    email: devsupport@icontainers.com
  license:
    name: private
    url: https://www.icontainers.com
  version: 1.0.0
  x-logo:
    url: https://icontainers-public.s3.us-east-1.amazonaws.com/images/iContainers+Logo.svg
  description: Bookings
servers:
- url: https://brutus.icontainers.com
  description: Production server
- url: https://brutus-dev.icontainers.com
  description: Developing server
tags:
- name: Bookings
  description: Bookings
  x-audience:
  - velocity
  - xhipment
paths:
  /api/v1/bookings/{bookingUuid}/documents:
    post:
      tags:
      - Bookings
      summary: Upload a document for a booking
      operationId: AddDocumentForBooking
      parameters:
      - name: bookingUuid
        in: path
        description: Uuid of the booking
        required: true
        schema:
          type: string
          format: uuid
        example: 918f07a7-14b3-4587-aa46-69f9089dd663
      requestBody:
        description: Document to upload
        required: true
        content:
          multipart/form-data:
            schema:
              $ref: '#/components/schemas/Bookings.AddDocumentForBookingRequest'
      responses:
        '201':
          description: Document uploaded successfully
        '401':
          description: Authentication required
        '403':
          description: User is not the owner of the booking
        '404':
          description: Booking not found
        '422':
          description: Invalid Data
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/422Response'
        '500':
          description: Internal server error
      security:
      - bearerAuth: []
      x-audience:
      - velocity
      - xhipment
  /api/v1/rates/{rateUuid}/book:
    post:
      tags:
      - Bookings
      summary: Book a rate
      operationId: BookRate
      parameters:
      - name: rateUuid
        in: path
        description: Uuid of the rate
        required: true
        schema:
          type: string
          format: uuid
        example: 918f07a7-14b3-4587-aa46-69f9089dd663
      requestBody:
        description: Book a rate by rateUuid
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/BookRateRequest'
      responses:
        '202':
          description: Successful operation
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/BookRateResource'
        '401':
          description: Unauthorized
        '422':
          description: Invalid Data
          content:
            application/json:
              schema:
                type: object
              example:
                type: string
                example: Unauthorized
                property: message
        '500':
          description: Internal server error
      security:
      - bearerAuth: []
      x-audience:
      - velocity
      - xhipment
  /api/v1/bookings/{bookingUuid}/details:
    get:
      tags:
      - Bookings
      summary: Get booking details
      operationId: GetBookingDetails
      parameters:
      - name: bookingUuid
        in: path
        description: Uuid of the booking
        required: true
        schema:
          type: string
          format: uuid
        example: 918f07a7-14b3-4587-aa46-69f9089dd663
      responses:
        '200':
          description: Successful operation
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/BookingResource'
        '401':
          description: Authentication required
        '403':
          description: User is not the owner of the booking
        '422':
          description: Invalid Data
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/422Response'
        '500':
          description: Problem with external Client
      security:
      - bearerAuth: []
      x-audience:
      - velocity
      - xhipment
  /api/v1/bookings/{bookingUuid}/documents/{documentId}:
    get:
      tags:
      - Bookings
      summary: Download booking document
      operationId: GetBookingDocument
      parameters:
      - name: bookingUuid
        in: path
        description: Uuid of the booking
        required: true
        schema:
          type: string
          format: uuid
        example: 918f07a7-14b3-4587-aa46-69f9089dd663
      - name: documentId
        in: path
        description: Id of the document
        required: true
        schema:
          type: string
        example: WcOADB4ddQXukNi6cvZVm6SLOrJUlNF5AGYFh-mbxHZNXKpMB8-QdC5AGsiBbJ6cIxFDMRHzb4glE3ngExtiTcdC
      responses:
        '200':
          description: Successful operation
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/BookingDocumentDownloadResource'
        '401':
          description: Authentication required
        '403':
          description: User is not the owner of the booking
        '404':
          description: Booking or document not found
        '422':
          description: Invalid Data
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/422Response'
        '500':
          description: Problem with external Client
      security:
      - bearerAuth: []
      x-audience:
      - velocity
      - xhipment
  /api/v1/bookings/{bookingUuid}/trackAndTrace:
    get:
      tags:
      - Bookings
      summary: Get booking track and trace information
      operationId: GetBookingTrackAndTracer
      parameters:
      - name: bookingUuid
        in: path
        description: Uuid of the booking
        required: true
        schema:
          type: string
          format: uuid
        example: 918f07a7-14b3-4587-aa46-69f9089dd663
      responses:
        '200':
          description: Successful operation
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/BookingTrackAndTraceResource'
        '401':
          description: Authentication required
        '403':
          description: User is not the owner of the booking
        '422':
          description: Invalid Data
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/422Response'
        '500':
          description: Problem with external Client
      security:
      - bearerAuth: []
      x-audience:
      - velocity
      - xhipment
components:
  schemas:
    BookingAddressData:
      title: BookingAddressData
      description: Address data to associate with a booking.
      required:
      - address
      - city
      - companyName
      - countryIsoCode
      - contactName
      properties:
        address:
          type: string
        city:
          type: string
        companyName:
          type: string
        countryIsoCode:
          description: ISO 3166-1 alpha-2 country code
          type: string
          maxLength: 2
          minLength: 2
        email:
          type:
          - string
          - 'null'
          format: email
        eoriCode:
          type:
          - string
          - 'null'
        legalId:
          type:
          - string
          - 'null'
        phone:
          type:
          - string
          - 'null'
        postalCode:
          type:
          - string
          - 'null'
        stateCode:
          type:
          - string
          - 'null'
        contactName:
          type: string
      type: object
      x-audience:
      - velocity
      - xhipment
    BookingParty:
      properties:
        shipper:
          oneOf:
          - $ref: '#/components/schemas/Address'
          type:
          - object
          - 'null'
        consignee:
          oneOf:
          - $ref: '#/components/schemas/Address'
          type:
          - object
          - 'null'
        notify:
          oneOf:
          - $ref: '#/components/schemas/Address'
          type:
          - object
          - 'null'
        billing:
          oneOf:
          - $ref: '#/components/schemas/Address'
          type:
          - object
          - 'null'
        pickup:
          oneOf:
          - $ref: '#/components/schemas/Address'
          type:
          - object
          - 'null'
        delivery:
          oneOf:
          - $ref: '#/components/schemas/Address'
          type:
          - object
          - 'null'
      type: object
      x-audience:
      - velocity
      - xhipment
    OptionalDimensionedCargoItem:
      required:
      - weight
      - weightUnit
      - quantity
      - packageType
      - numberOfPieces
      properties:
        weight:
          type: number
          format: float
          example: 105.8
        weightUnit:
          $ref: '#/components/schemas/WeightUnit'
        height:
          type:
          - number
          - 'null'
          format: float
          example: 10.2
        length:
          type:
          - number
          - 'null'
          format: float
          example: 2.9
        width:
          type:
          - number
          - 'null'
          format: float
          example: 13.2
        dimensionUnit:
          oneOf:
          - $ref: '#/components/schemas/DimensionUnit'
        volume:
          type:
          - number
          - 'null'
          format: float
          example: 3.69
        volumeUnit:
          oneOf:
          - $ref: '#/components/schemas/VolumeUnit'
        quantity:
          type: number
          example: 3
        packageType:
          $ref: '#/components/schemas/PackageType'
        cargoDescription:
          type:
          - string
          - 'null'
          example: Fragile goods
        cargoType:
          type:
          - string
          - 'null'
          example: general
        stackable:
          type:
          - boolean
          - 'null'
          example: false
        temperatureControl:
          oneOf:
          - $ref: '#/components/schemas/TemperatureControlledGoods'
        dangerousGoods:
          type: array
          items:
            $ref: '#/components/schemas/DangerousGood'
        numberOfPieces:
          type: integer
          example: 9
      type: object
    VolumeUnit:
      description: Volume unit
      type: string
      enum:
      - CM3
      - M3
      - IN3
      - FT3
      example: M3
    DimensionedCargoItem:
      required:
      - weight
      - height
      - length
      - width
      - dimensionUnit
      - weightUnit
      - quantity
      - packageType
      - numberOfPieces
      properties:
        weight:
          type: number
          format: float
          example: 105.8
        height:
          type: number
          format: float
          example: 10.2
        length:
          type: number
          format: float
          example: 2.9
        width:
          type: number
          format: float
          example: 13.2
        dimensionUnit:
          $ref: '#/components/schemas/DimensionUnit'
        weightUnit:
          $ref: '#/components/schemas/WeightUnit'
        quantity:
          type: number
          example: 3
        packageType:
          $ref: '#/components/schemas/PackageType'
        cargoDescription:
          type:
          - string
          - 'null'
          example: Fragile goods
        cargoType:
          type:
          - string
          - 'null'
          example: general
        stackable:
          type:
          - boolean
          - 'null'
          example: false
        temperatureControl:
          oneOf:
          - $ref: '#/components/schemas/TemperatureControlledGoods'
        dangerousGoods:
          type: array
          items:
            $ref: '#/components/schemas/DangerousGood'
        numberOfPieces:
          type: integer
          example: 9
      type: object
    WeightUnit:
      description: Weight unit
      type: string
      enum:
      - Kg
      - Ton
      - Lb
      example: Kg
    Charges:
      properties:
        localCharges:
          $ref: '#/components/schemas/BookingChargeCollection'
        freightCharges:
          $ref: '#/components/schemas/BookingChargeCollection'
        otherCharges:
          $ref: '#/components/schemas/BookingChargeCollection'
        inlandCharges:
          $ref: '#/components/schemas/BookingChargeCollection'
        additionalServicesCharges:
          $ref: '#/components/schemas/BookingChargeCollection'
      type: object
      x-audience:
      - velocity
      - xhipment
    BillingBookingAddressData:
      title: BillingBookingAddressData
      description: Address data for billing addresses. Requires email and phone in addition to the base address fields.
      required:
      - email
      - phone
      allOf:
      - $ref: '#/components/schemas/BookingAddressData'
      x-audience:
      - velocity
      - xhipment
    LCLItemCollection:
      type: array
      items:
        $ref: '#/components/schemas/LclCargoItem'
    OptionalBillingItemSelectionData:
      description: Details of the optional billing item selection
      required:
      - name
      - serviceItem
      properties:
        name:
          type: string
        serviceItem:
          type: string
          enum:
          - Pickup
          - Delivery
          - PortOriginCharges
          - PortDestinationCharges
          - Freight
          - AdditionalService
        data:
          type: object
      type: object
    BookingTrackAndTraceData:
      properties:
        uuid:
          type: string
          format: uuid
          example: 918f07a7-14b3-4587-aa46-69f9089dd663
        estimatedTimeArrival:
          type: string
          example: '2021-09-01 12:00:00'
        estimatedTimeDeparture:
          type: string
          example: '2021-09-01 12:00:00'
        actualTimeArrival:
          type:
          - string
          - 'null'
          example: '2021-09-01 12:00:00'
        actualTimeDeparture:
          type:
          - string
          - 'null'
          example: '2021-09-01 12:00:00'
        status:
          type: string
          enum:
          - PREBOOKING
          - REQUESTED
          - PENDING
          - CANCELED
          - DONE
          example: PREBOOKING
      type: object
      x-audience:
      - velocity
      - xhipment
    BookingLocation:
      properties:
        locationType:
          type: string
          example: PORT
        portIsoCode:
          type: string
          example: ESBCN
        postalCode:
          type:
          - string
          - 'null'
          example: 08001
        cityName:
          type:
          - string
          - 'null'
          example: Barcelona
      type: object
      x-audience:
      - velocity
      - xhipment
    422Response:
      properties:
        message:
          example: The given data was invalid.
        errors:
          type: object
          example:
            someProperty:
            - The some property field is required.
          additionalProperties:
            type: array
            items:
              type: string
      type: object
    BookingChargeCollection:
      type: array
      items:
        $ref: '#/components/schemas/BookingCharge'
      x-audience:
      - velocity
      - xhipment
    BookRateResource:
      required:
      - data
      properties:
        data:
          $ref: '#/components/schemas/AsyncBooking'
      type: object
      x-audience:
      - velocity
      - xhipment
    BookingDocumentDownloadResource:
      properties:
        data:
          $ref: '#/components/schemas/BookingDocumentDownloadData'
      type: object
      x-audience:
      - velocity
      - xhipment
    LclCargoItem:
      properties:
        weight:
          type: number
          format: float
          example: 105.25
        weightUnit:
          $ref: '#/components/schemas/WeightUnit'
        volume:
          type: number
          format: float
          example: 3.69
        volumeUnit:
          $ref: '#/components/schemas/VolumeUnit'
        height:
          type:
          - number
          - 'null'
          format: float
          example: 10.2
        length:
          type:
          - number
          - 'null'
          format: float
          example: 2.9
        width:
          type:
          - number
          - 'null'
          format: float
          example: 13.2
        dimensionUnit:
          oneOf:
          - $ref: '#/components/schemas/DimensionUnit'
          type:
          - string
          - 'null'
        quantity:
          type: number
          example: 4
        packageType:
          $ref: '#/components/schemas/PackageType'
        cargoDescription:
          type:
          - string
          - 'null'
          example: Electronics
        cargoType:
          type:
          - string
          - 'null'
          example: general
        stackable:
          type:
          - boolean
          - 'null'
          example: true
        temperatureControl:
          oneOf:
          - $ref: '#/components/schemas/TemperatureControlledGoods'
        dangerousGoods:
          type: array
          items:
            $ref: '#/components/schemas/DangerousGood'
        numberOfPieces:
          type: integer
          example: 7
      type: object
    AsyncBooking:
      required:
      - bookingUuid
      properties:
        bookingUuid:
          type: string
          format: uuid
      type: object
      x-audience:
      - velocity
      - xhipment
    TemperatureControlledGoods:
      description: Temperature limits for temperature-controlled cargo (LCL/AIR/LTL)
      required:
      - min
      - max
      - unit
      properties:
        min:
          type: number
          format: float
          example: 2
        max:
          type: number
          format: float
          example: 8
        unit:
          $ref: '#/components/schemas/TemperatureUnit'
      type: object
    DangerousGood:
      description: Dangerous good identified by its UN number
      required:
      - unNumber
      properties:
        unNumber:
          type: string
          example: UN1993
      type: object
    BookingResource:
      properties:
        data:
          $ref: '#/components/schemas/BookingData'
      type: object
      x-audience:
      - velocity
      - xhipment
    TemperatureUnit:
      description: Temperature unit
      type: string
      enum:
      - C
      - F
      example: C
    OptionalDimensionedCargoItemCollection:
      type: array
      items:
        $ref: '#/components/schemas/OptionalDimensionedCargoItem'
    BookingTrackAndTraceResource:
      properties:
        data:
          $ref: '#/components/schemas/BookingTrackAndTraceData'
      type: object
      x-audience:
      - velocity
      - xhipment
    ContainerItem:
      properties:
        type:
          type: string
          enum:
          - DV20
          - DV40
          - DV40HC
          - HC45
          - OT20
          - OT40
          - RE20
          - RE40
          - RE40HC
          - FR20
          - FR40
          - NOR20
          - NOR40
          - PL20
          - PW20H
          - IN20B
          - RF40H
          - RF40
          - PL40
          - ISO20
          - FT40
          - OT20
          - PW40H
          - GR20
          - HC45
          - IN20A
          - FT20
          - RF20
          - TK20
          - TK40
          - HC40
          - OT40
          - ISO40
        quantity:
          type: number
          minimum: 1
        cargoDescription:
          type:
          - string
          - 'null'
          example: Flammable chemicals
        weight:
          properties:
            weight:
              type: number
              format: float
              example: 950.5
            unit:
              $ref: '#/components/schemas/WeightUnit'
          type:
          - object
          - 'null'
        temperatureControl:
          oneOf:
          - $ref: '#/components/schemas/ContainerTemperatureControl'
        dangerousGoods:
          type: array
          items:
            $ref: '#/components/schemas/DangerousGood'
      type: object
    BookRateRequest:
      title: BookRateRequest
      required:
      - currency
      - servicesSelected
      - bookingDetails
      - optionalBillingItems
      properties:
        currency:
          type: string
          example: EUR
        lang:
          type: string
          enum:
          - es_ES
          - en_US
        servicesSelected:
          $ref: '#/components/schemas/ServicesSelected'
        bookingDetails:
          required:
          - cargoReadyDate
          - commodity
          properties:
            cargoReadyDate:
              description: Date when the cargo is ready to be picked up. The date must be today or in the future.
              type: string
              format: date
            commodity:
              type: string
              enum:
              - Regular Cargo
              - Refrigerated
              - Hazardous goods (DGR, IMO)
              - Perishable
              - Used Tires/Scrap
              - Household Goods
              - Livestock and Animals
              - Explosives
          type: object
        optionalBillingItems:
          description: Property used to book optional additional services.
          type: array
          items:
            $ref: '#/components/schemas/OptionalBillingItemSelectionData'
        addresses:
          description: Optional addresses to associate with the booking. Each key is an address type (shipper, consignee, pickup, delivery, billing).
          properties:
            shipper:
              $ref: '#/components/schemas/BookingAddressData'
            consignee:
              $ref: '#/components/schemas/BookingAddressData'
            pickup:
              $ref: '#/components/schemas/BookingAddressData'
            delivery:
              $ref: '#/components/schemas/BookingAddressData'
            billing:
              $ref: '#/components/schemas/BillingBookingAddressData'
          type:
          - object
          - 'null'
      type: object
      x-audience:
      - velocity
      - xhipment
    Address:
      properties:
        name:
          type:
          - string
          - 'null'
          example: John Doe
        address:
          type:
          - string
          - 'null'
          example: Carrer de la Marina, 16
        postalCode:
          type:
          - string
          - 'null'
          example: 08001
        city:
          type:
          - string
          - 'null'
          example: Barcelona
        country:
          type:
          - string
          - 'null'
          example: ES
        phone:
          type:
          - string
          - 'null'
          example: +34 123 456 789
        email:
          type:
          - string
          - 'null'
          example: hi@icontainers.com
      type: object
      x-audience:
      - velocity
      - xhipment
    BookingCharge:
      properties:
        amount:
          type: number
          example: 100
        currency:
          type: string
          example: EUR
        description:
          type: string
          example: Description of the charge
        taxes:
          type: number
          example: 21
      type: object
      x-audience:
      - velocity
      - xhipment
    BookingDocumentDownloadData:
      properties:
        url:
          type: string
          example: https://icontainers-s3-bucket/2040455/COMM_INVOICE/COMM_INVOICE_1.docx
      type: object
      x-audience:
      - velocity
      - xhipment
    Bookings.AddDocumentForBookingRequest:
      required:
      - documentType
      - document
      properties:
        documentType:
          description: Type of document
          type: string
          enum:
          - CommercialInvoice
          - PackingList
          - Others
          example: CommercialInvoice
        document:
          description: Document file (PDF, CSV, or XLSX)
          type: string
          format: binary
      type: object
      x-audience:
      - velocity
      - xhipment
    Document:
      properties:
        id:
          type: string
          example: WcOADB4ddQXukNi6cvZVm6SLOrJUlNF5AGYFh-mbxHZNXKpMB8-QdC5AGsiBbJ6cIxFDMRHzb4glE3ngExtiTcdC
        name:
          type: string
          example: Document name
        createdAt:
          type: string
          example: '2022-01-02 00:00:00'
      type: object
      x-audience:
      - velocity
      - xhipment
    ContainerTemperatureControl:
      description: Temperature control for reefer containers (FCL)
      required:
      - cargoLimits
      - setPoint
      - requiresGenset
      properties:
        cargoLimits:
          properties:
            min:
              type: number
              format: float
              example: -15
            max:
              type: number
              format: float
              example: 8
            unit:
              $ref: '#/components/schemas/TemperatureUnit'
          type: object
        setPoint:
          properties:
            value:
              type: number
              format: float
              example: -3
            unit:
              $ref: '#/components/schemas/TemperatureUnit'
          type: object
        requiresGenset:
          type: boolean
          example: true
      type: object
    DimensionedCargoItemCollection:
      type: array
      items:
        $ref: '#/components/schemas/DimensionedCargoItem'
    Money:
      properties:
        amount:
          type: number
          example: 100
        currency:
          type: string
          example: EUR
      type: object
      x-audience:
      - velocity
      - xhipment
    PackageType:
      description: Package type
      type: string
      enum:
      - Container
      - Package
      - Bag
      - Bulk Bag
      - Break Bulk
      - Bale Compressed
      - Bale Uncompressed
      - Bundle
      - Bottle
      - Box
      - Basket
      - Case
      - Coil
      - Cradle
      - Crate
      - Carton
      - Cylinder
      - Dozen
      - Drum
      - Envelope
      - Gross
      - Keg
      - Mix
      - Pail
      - Piece
      - Pallet
      - Reel
      - Roll
      - Sheet
      - Skid
      - Spool
      - Tote
      - Tube
      - Unit
      example: Pallet
    ContainerItemCollection:
      type: array
      items:
        $ref: '#/components/schemas/ContainerItem'
    BookingData:
      properties:
        uuid:
          type: string
          format: uuid
          example: 918f07a7-14b3-4587-aa46-69f9089dd663
        totalAmount:
          $ref: '#/components/schemas/Money'
        origin:
          $ref: '#/components/schemas/BookingLocation'
        originRoutingPort:
          type:
          - string
          - 'null'
          example: ESBCN
        destination:
          $ref: '#/components/schemas/BookingLocation'
        destinationRoutingPort:
          type:
          - string
          - 'null'
          example: ESBCN
        createdAt:
          type: string
          example: '2022-01-02 00:00:00'
        status:
          type: string
          enum:
          - PREBOOKING
          - REQUESTED
          - PENDING
          - CANCELED
          - DONE
          example: PREBOOKING
        shipmentType:
          type: string
          enum:
          - FCL
          - LCL
          - AIR
          - LTL
          example: FCL
        items:
          anyOf:
          - $ref: '#/components/schemas/ContainerItemCollection'
          - $ref: '#/components/schemas/LCLItemCollection'
          - $ref: '#/components/schemas/DimensionedCargoItemCollection'
          - $ref: '#/components/schemas/OptionalDimensionedCargoItemCollection'
        charges:
          $ref: '#/components/schemas/Charges'
        commodityType:
          type: string
          example: Regular Cargo
        bookingParty:
          $ref: '#/components/schemas/BookingParty'
        documents:
          properties:
            packagingList:
              oneOf:
              - $ref: '#/components/schemas/Document'
              type:
              - object
              - 'null'
            commercialInvoice:
              oneOf:
              - $ref: '#/components/schemas/Document'
              type:
              - object
              - 'null'
            others:
              type: array
              items:
                $ref: '#/components/schemas/Document'
          type: object
      type: object
      x-audience:
      - velocity
      - xhipment
    DimensionUnit:
      description: Dimension unit
      type: string
      enum:
      - cm
      - m
      - ft
      - in
      example: cm
    ServicesSelected:
      description: Details of the services selected
      required:
      - pickup
      - origin
      - destination
      - freight
      - delivery
      properties:
        pickup:
          type: boolean
        origin:
          type: boolean
        destination:
          type: boolean
        freight:
          type: boolean
        delivery:
          type: boolean
      type: object
  securitySchemes:
    bearerAuth:
      type: http
      bearerFormat: JWT
      scheme: bearer