openapi: 3.1.0
info:
  description: The Setlog API provides simple RESTful HTTP interfaces to share your logistics data with your partners
  version: 0.9.0
  title: Setlog Booking API
  contact:
    email: interfaces@setlog-support.com
security:
  - APIKeyHeader: []
servers:
  - url: https://test-api.setlog.com
    description: Server URL in uat environment
  - url: https://api.setlog.com
    description: Server URL in Production environment
paths:
  /data/v1/booking:
    get:
      tags:
        - Get list of requested bookings
      summary: Returns bookings
      operationId: GetBookingByUid
      description: Returns bookings accordingly to the requested uid list
      parameters:
      - name: uid
        in: query
        description: UID-list of requested bookings (comma separated, if more than one)
        required: true
        schema:
          type: string
      responses:
        '200':
          description: successful operation
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/BookingResponse'
            application/xml:
              schema:
                $ref: '#/components/schemas/BookingResponse'
        '400':
          description: API call has failed because the request is incomplete.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ApiResponse'
            application/xml:
              schema:
                $ref: '#/components/schemas/ApiResponse'
        '401':
          description: API Call has failed because of the apikey is not given or unknown
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/UnauthorizedResponse'
            application/xml:
              schema:
                $ref: '#/components/schemas/UnauthorizedResponse'
    post:
      tags:
        - Create a booking
      description: Create a booking
      operationId: CreateUpdateBooking
      requestBody:
        description: content of a booking to update (fields with values)
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/Booking'
          application/xml:
            schema:
              $ref: '#/components/schemas/Booking'
      responses:
        '200':
          description: successful operation
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/BookingResponse'
            application/xml:
              schema:
                $ref: '#/components/schemas/BookingResponse'
        '400':
          description: API call has failed because the request is incomplete.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ApiResponse'
            application/xml:
              schema:
                $ref: '#/components/schemas/ApiResponse'
        '401':
          description: API Call has failed because of the apikey is not given or unknown
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/UnauthorizedResponse'
            application/xml:
              schema:
                $ref: '#/components/schemas/UnauthorizedResponse'
    patch:
      tags:
        - Update a booking by UID
      description: Update a booking by UID
      operationId: UpdateBookingByUid
      parameters:
      - name: uid
        in: query
        description: UID of a booking to update
        required: true
        schema:
          type: string
      requestBody:
        description: content of a booking to update (fields with values)
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/Booking'
          application/xml:
            schema:
              $ref: '#/components/schemas/Booking'
      responses:
        '200':
          description: successful operation
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/BookingResponse'
            application/xml:
              schema:
                $ref: '#/components/schemas/BookingResponse'
        '400':
          description: API call has failed because the request is incomplete.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ApiResponse'
            application/xml:
              schema:
                $ref: '#/components/schemas/ApiResponse'
        '401':
          description: API Call has failed because of the apikey is not given or unknown
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/UnauthorizedResponse'
            application/xml:
              schema:
                $ref: '#/components/schemas/UnauthorizedResponse'
  /data/v1/booking/new:
    get:
      tags:
        - Get list of new bookings
      summary: Returns new bookings that has been generated
      description: Returns bookings that have been confirmed by the customer and not been acknowledged yet
      operationId: GetNewUpdatedBookings
      responses:
        '200':
          description: successful operation
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/BookingResponse'
            application/xml:
              schema:
                $ref: '#/components/schemas/BookingResponse'
        '401':
          description: API Call has failed because of the apikey is not given or unknown
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/UnauthorizedResponse'
            application/xml:
              schema:
                $ref: '#/components/schemas/UnauthorizedResponse'
  /data/v1/booking/acknowledgement:
    post:
      tags:
        - Send an acknowledgement for received bookings
      summary: Send an acknowledgement for received bookings
      operationId: SendsBookingAcknowledgement
      requestBody:
        description: content of a booking to update (fields with values)
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/Acknowledgement'
          application/xml:
            schema:
              $ref: '#/components/schemas/Acknowledgement'
      responses:
        '200':
          description: successful operation
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ApiResponse'
            application/xml:
              schema:
                $ref: '#/components/schemas/ApiResponse'
        '401':
          description: API Call has failed because of the apikey is not given or unknown
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/UnauthorizedResponse'
            application/xml:
              schema:
                $ref: '#/components/schemas/UnauthorizedResponse'
webhooks:
  'Receives Booking Request':
    post:
      security:
      - BasicAuth: []
      summary: Receives a booking request from customer OSCA System
      operationId: ReceivesBookingRequest
      requestBody:
        description: Receives the booking request from OSCA System
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/Booking'
          application/xml:
            schema:
              $ref: '#/components/schemas/Booking'
      responses:
        200:
          description: Booking request could be received
        400:
          description: Booking could not be received
        401:
          description: The given user is unauthorized
components:
  schemas:
    Booking:
      type: object
      properties:
        uid:
          type: string
          description: Unique ID of the booking. This id is crucial, if it is necessary to relate to this booking in other messages.
        version:
          type: integer
          description: Version of the booking, if exists. 0 – this is a new booking, larger than 0 – an update of an existing one (according to booking.uid)
        booking_no:
          type: string
          description: Given booking number from the OSCA system
        created_at:
          type: string
          format: date-time
          description: Creation time of the booking as defined by date-time RFC3339
        updated_at:
          type: string
          format: date-time
          description: Last update time of the booking as defined by date-time RFC3339
        status:
          $ref: '#/components/schemas/BookingStatus'
        volume:
          type: number
          description: Volume of the booking, in cbm
        weight:
          type: number
          description: Chargeable weight, in kg
        qty_pcs:
          type: integer
          description: Quantity of pieces
        qty_ctn:
          type: integer
          description: Quantity of cartons
        remark:
          type: string
          description: Remark for the booking
        container:
          type: array
          items:
            $ref: '#/components/schemas/Container'
        address:
          type: array
          items:
            $ref: '#/components/schemas/Address'
        timetable:
          $ref: '#/components/schemas/Timetable'
        customer:
          $ref: '#/components/schemas/Partner'
        supplier:
          $ref: '#/components/schemas/Partner'
        forwarder:
          $ref: '#/components/schemas/Partner'
        warehouse:
          $ref: '#/components/schemas/Partner'
        carrier:
          type: string
          description: The scac of the shipping company
        vessel_airline:
          type: string
          description: Vessel name (for SEA), Airline (for AIR)
        voyage_no:
          type: string
          description: Voyage number for SEA or AIR
        hbl_hawb:
          type: string
          description: House bill of lading/house airway bill from forwarder
        delivery:
          type: array
          items:
            $ref: '#/components/schemas/Delivery'
        custom_fields:
          type: object
          description: Partner defined fields for a booking
    BookingStatus:
      type: string
      enum:
        - PENDING
        - CONFIRMED
        - REJECTED
        - CANCELLED
        - ARCHIVED
      description: Status of the booking
    Container:
      type: object
      description: Details of the transport unit. It could be e.g. a container for sea shipments or a truck for a truck shipment
      properties:
        uid:
          type: string
          description: Unique ID of the container, generated by forwarder api platform
        reference_no:
          type: string
          description: Internal number of the container in the related OSCA system. Use this field only, if you are going to create a new container (uid will be generated by the forwarder api platform)
        container_no:
          type: string
          description: Container number from forwarder
        seal_no:
          type: string
          description: Seal number
        container_type:
          type: string
          description: Container type. We will map the same container types of the connected OSCA system.
        vendor_load:
          type: boolean
          description: False, if the good has to be load into the container by forwarder
        provision_date:
          type: string
          format: date-time
          description: Plan date on which the container has to be provided at the handover location
        yard_date:
          type: string
          format: date-time
          description: Date on which the container has been provided at the handover location
        handover_location:
          type: string
          description: Full hand-over address
        volume:
          type: number
          description: Current volume load in cbm
        gross_weight:
          type: number
          description: Gross weight in kg
        qty_ctn:
          type: integer
          description: Quantity of cartons in the container
        qty_pallets:
          type: integer
          description: Quantity of pallets
        custom_fields:
          type: object
          description: Partner defined fields for a container
    Address:
      type: object
      description: Details of the address of the pick up location, consignee or notify party
      properties:
        reference_no:
          type: string
          description: Unique ID of the address
        name:
          type: string
          description: Name of the company this address belongs to
        type:
          type: string
          description: Address type. We used the values from the OSCA DC System
          enum:
            - SHIPPER
            - CONSIGNEE
            - NOTIFY PARTY
        street:
          type: string
          description: E.g. Alleestr. 80
        zip:
          type: string
          description: E.g. 44793
        city:
          type: string
          description: E.g. Bochum
        state:
          type: string
          description: E.g. NRW
        country:
          type: string
          description: This shows either the complete country name or the short iso alpha 2 code
        contact_name:
          type: string
          description: Name of the contact person
        email:
          type: string
          description: Email address
        phone:
          type: string
          description: Phone number
        fax:
          type: string
          description: Fax number
        custom_fields:
          type: object
          description: Partner defined fields for an address
    Timetable:
      type: object
      description: Details of the shipment leg
      properties:
        mot:
          type: string
          description: Mode of transportation
          enum:
            - SEA
            - AIR
            - SEA-AIR
            - TRUCK
            - RAIL
            - COURIER
        service:
          type: string
          description: Service of transportation. Those values are only valid in combination with a mode of transport
          enum:
            - REGULAR
            - FAST
            - A-CLASS
            - B-CLASS
            - C-CLASS
            - FLASH
            - NORMAL
            - SPEED
            - EXPRESS
        handover:
          type: string
          format: date-time
          description: Local time that the supplier hands over the goods to the forwarder on as defined by date-time - RFC3339
        pol:
          type: string
          description: UnLocode of the port of loading, e.g. CNSHA for CN = China, SHA = Shanghai
        pol_name:
          type: string
          description: Full name of the port of loading. E.g. Shanghai
        etd:
          type: string
          format: date-time
          description: Estimated local time of delivery as defined by date-time - RFC3339
        poa:
          type: string
          description: UnLocode of the port of arrival, e.g. DEHAM for DE = Germany, HAM = Hamburg
        poa_name:
          type: string
          description: Full name of the port of arrival. E.g. Hamburg
        eta:
          type: string
          format: date-time
          description: Estimated local time of arrival as defined by date-time - RFC3339
        incoterm:
          type: string
          enum:
            - EXW
            - FCA
            - FAS
            - FOB
            - CFR
            - CIF
            - CPT
            - CIP
            - DPU
            - DAP
            - DDP
    Partner:
      type: object
      description: The technical partner for this bookings like customer, supplier, forwarder, etc.
      properties:
        uid:
          type: string
          description: Unique ID of the partner. This id is crucial, if it is necessary to relate to this partner in other messages.
        partner_nr:
          type: string
          description: Partner number of the original system
        short_name:
          type: string
          description: Short name of the partner
        long_name:
          type: string
          description: Long name of the partner
        custom_fields:
          type: object
          description: Partner defined fields for an partner
        address:
          $ref: '#/components/schemas/Address'
    Delivery:
      type: object
      description: Contains all information about the purchase order and the items, which will be transported
      properties:
        uid:
          type: string
          description: Unique ID of the delivery. This id is crucial, if it is necessary to relate to this delivery in other messages.
        version:
          type: integer
          description: Version of the delivery, if exists
        qty_pcs:
          type: integer
          description: Quantity of pieces
        qty_ctn:
          type: integer
          description: Quantity of cartons
        additional_info:
          type: string
          description: Some additional information that might be related to the logistics information
        volume:
          type: number
          description: Volume of the delivery, in cbm
        weight:
          type: number
          description: Chargeable weight of the delivery, in kg
        dispatch_type:
          type: string
          description: Dispatch type enumeration of possible values FLAT, HANGING
        container_uid:
          type: string
          description: Container uid that the order is shipped in. See container.uid
        customer_refno:
          type: string
          description: Human readable identification of the item. The content depends on how the customer wants to communicate about a purchase ordr.
        order_no:
          type: string
          description: Purchase order number
        order_date:
          type: string
          format: date
          description: Order date as defined by full-date RFC3339
        order_type:
          type: string
          description: Order type as defined in the original database
        department:
          type: string
          description: Customers department that is in charge of this order
        origin_country:
          type: string
          description: Country of origin
        item_position:
          type: string
          description: Item position
        item_number:
          type: string
          description: Item number, e.g. article number
        item_description:
          type: string
          description: Item description
        unit:
          type: string
          description: Unit related to ordered quantities. enumeration of possible values PCS, CTN, SET
        customs_tariff_no:
          type: string
          description: Customs tariff number
        factory:
          $ref: '#/components/schemas/Partner'
        custom_fields:
          type: object
          description: Partner defined fields for a delivery
    Acknowledgement:
      type: object
      description: Contains booking acknowledgements
      properties:
        booking:
          type: array
          items:
            $ref: '#/components/schemas/BookingAcknowledgement'
    BookingAcknowledgement:
      type: object
      description: If true, the booking request could import from forwarder
      properties:
        uid:
          type: string
          description: Booking Uid
        success:
          type: boolean
          description: It is 'true' if forwarder receives the booking, else 'false'
    BookingResponse:
      allOf:
        - $ref: '#/components/schemas/ApiResponse'
        - type: object
          properties:
            payload:
              type: array
              items:
                $ref: '#/components/schemas/Booking'
    ApiResponse:
      type: object
      description: Api response for updating a booking request call
      properties:
        error:
          type: array
          items:
            $ref: '#/components/schemas/ErrorResponse'
    ErrorResponse:
      type: object
      description: Describes the and references the the error
      properties:
        pos:
          type: integer
          description: order in the error array
        service:
          type: string
          description: Service name where the error occured
        timestamp:
          type: string
          description: Timestamp in the format "yyyyMMddHHmmss"
        code:
          type: integer
          description: Code for the error
        description:
          type: string
          description: More details about the error
    UnauthorizedResponse:
      type: object
      description: Returned response if the apikey is unkown
      properties:
        message:
          type: string
          description: Details of the error
        request_id:
          type: string
          description: The used request id for this call
  securitySchemes:
    APIKeyHeader:
      type: apiKey
      name: apikey
      in: header
    BasicAuth:
      type: http
      scheme: basic