openapi: 3.1.0
info:
  title: export-booking
  version: '2025-03-20T21:29:00Z'
servers:
  - url: https://export.api.splice-it.com
tags:
  - name: document
    description: Export documents
  - name: booking
    description: Export booking records
  - name: container
    description: Booking container records
paths:
  /doc-proc:
    post:
      tags:
        - document
      summary: Submit a booking document
      description: Submit a booking document for parsing.
      operationId: uploadDoc
      requestBody:
        description: Process booking document
        content:
          multipart/form-data:
            schema:
              type: object
              properties:
                file:
                  type: string
                  format: binary
      responses:
        '201':
          description: successful operation
        '401':
          description: Unauthorized
      security:
        - ApiKeyAuthorizer: []
  /export/bookings:
    get:
      tags:
        - booking
      summary: List of active export booking
      description: Summary list of active export bookings.
      operationId: getBookings
      responses:
        '200':
          description: successful operation
          content:
            application/json:
              schema:
                type: array
                items:
                  $ref: '#/components/schemas/BookingSummary'
        '401':
          description: Unauthorized
      security:
        - ApiKeyAuthorizer: []
    post:
      tags:
        - booking
      summary: Upsert export booking
      description: Upsert an export booking record.
      operationId: upsertBooking
      requestBody:
        description: Booking payload
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/Booking'
      responses:
        '200':
          description: successful operation
        '401':
          description: Unauthorized
      security:
        - ApiKeyAuthorizer: []
  /export/bookings/{id}:
    get:
      tags:
        - booking
      summary: Get export booking
      description: Get a full export booking record.
      operationId: getBooking
      parameters:
        - name: id
          in: path
          required: true
          schema:
            type: string
      responses:
        '200':
          description: successful operation
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/BookingDetails'
        '401':
          description: Unauthorized
        '404':
          description: Booking record not found
      security:
        - ApiKeyAuthorizer: []
    delete:
      tags:
        - booking
      summary: Delete export booking
      description: Delete an export booking record.
      operationId: deleteBooking
      parameters:
        - name: id
          in: path
          required: true
          schema:
            type: string
      responses:
        '201':
          description: successful operation
        '401':
          description: Unauthorized
        '404':
          description: Booking record not found
      security:
        - ApiKeyAuthorizer: []
  /export/bookings/{id}/containers:
    get:
      tags:
        - container
      summary: Get booking containers
      description: Get export booking containers.
      operationId: getContainers
      parameters:
        - name: id
          in: path
          required: true
          schema:
            type: string
      responses:
        '200':
          description: successful operation
          content:
            application/json:
              schema:
                type: array
                items:
                  $ref: '#/components/schemas/Container'
        '400':
          description: Invalid status value
        '401':
          description: Unauthorized
        '404':
          description: Booking record not found
      security:
        - ApiKeyAuthorizer: []
    post:
      tags:
        - container
      summary: Upsert booking container
      description: Upsert an export booking container record.
      operationId: upsertContainer
      parameters:
        - name: id
          in: path
          required: true
          schema:
            type: string
      requestBody:
        description: Container payload
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/Container'
      responses:
        '200':
          description: successful operation
        '401':
          description: Unauthorized
        '404':
          description: Booking record not found
      security:
        - ApiKeyAuthorizer: []
  /export/bookings/{id}/containers/{container}:
    delete:
      tags:
        - container
      summary: Delete booking container
      description: Delete an export booking container record.
      operationId: getContainer
      parameters:
        - name: container
          in: path
          required: true
          schema:
            type: string
        - name: id
          in: path
          required: true
          schema:
            type: string
      responses:
        '201':
          description: successful operation
        '401':
          description: Unauthorized
        '404':
          description: Booking or container record not found
      security:
        - ApiKeyAuthorizer: []
  /export/bookings/{id}/rail-options:
    get:
      tags:
        - rail
      summary: Get booking rail options.
      description: Get all export booking rail options.
      operationId: getRailOptions
      parameters:
        - name: id
          in: path
          required: true
          schema:
            type: string
      responses:
        '200':
          description: successful operation
          content:
            application/json:
              schema:
                type: array
                items:
                  $ref: '#/components/schemas/RailOption'
        '401':
          description: Unauthorized
        '404':
          description: Booking record not found
      security:
        - ApiKeyAuthorizer: []
  /export/booking-webhooks:
    get:
      tags:
        - webhook
      summary: Get webhook endpoints
      description: Get all webhook endpoints.
      operationId: getWebhooks
      responses:
        '200':
          description: successful operation
          content:
            application/json:
              schema:
                type: array
                items:
                  $ref: '#/components/schemas/Webhook'
        '401':
          description: Unauthorized
      security:
        - ApiKeyAuthorizer: []
  /export/booking-webhooks/{type}:
    post:
      tags:
        - webhook
      summary: Create webhook
      description: Create an export event webhook endpoint.
      operationId: createWebhook
      parameters:
        - name: type
          in: path
          required: true
          schema:
            type: string
            enum:
              - export_booking_create
              - export_booking_update
      requestBody:
        description: Webhook payload
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/WebhookEndpoint'
      responses:
        '200':
          description: successful operation
        '401':
          description: Unauthorized
      security:
        - ApiKeyAuthorizer: []
      callbacks:
        # the name `onData` is a convenience locator
        'Booking event':
          '{$request.body#/url}':
            post:
              requestBody:
                description: Webhook payload
                content:
                  application/json:
                    schema:
                      $ref: '#/components/schemas/BookingEvent'
              responses:
                '200':
                  description: |
                    Your server implementation should return this HTTP status code
                    if the data was received successfully
                '202':
                  description: |
                    Your server implementation should return this HTTP status code
                    if the data was received successfully
    delete:
      tags:
        - webhook
      summary: Delete webhook
      description: Delete an export event webhook endpoint.
      operationId: deleteWebhook
      parameters:
        - name: type
          in: path
          required: true
          schema:
            type: string
            enum:
              - EXPORT_BOOKING_CREATE
              - EXPORT_BOOKING_UPDATE
        - name: url
          in: query
          required: true
          schema:
            type: string
            example: http://example.com/webhook-listener
      responses:
        '201':
          description: successful operation
        '401':
          description: Unauthorized
      security:
        - ApiKeyAuthorizer: []
components:
  schemas:
    Source:
      type: object
      properties:
        timestamp:
          type: string
          format: date-time
          description: Timestamp of the field update (ISO 8601 format).
          example: '2022-10-21T12:27:14.113Z'
        source:
          type: string
          description: Source of the field update.
          example: carrier
    Booking:
      allOf:
        - type: object
          required:
            - bookingNumber
          properties:
            bookingNumber:
              type: string
              example: ABRACADABRA
        - $ref: '#/components/schemas/BookingChangeset'
    BookingChangeset:
      type: object
      properties:
        carrier:
          type: string
          nullable: true
          description: Carrier SCAC code
          example: 'Yang Ming'
        createdDate:
          type: string
          nullable: true
          format: date-time
          description: Timestamp of the booking creation (ISO 8601 format)
          example: '2022-10-19T14:55:20.886Z'
        updatedDate:
          type: string
          format: date-time
          description: Timestamp of the last booking update (ISO 8601 format)
          example: '2022-10-05T14:24:43.000Z'
        closedDate:
          type: string
          nullable: true
          format: date-time
          description: Timestamp of the booking cancellation (ISO 8601 format)
          example: '2022-10-05T14:24:43.000Z'
        departingPort:
          type: string
          nullable: true
          description: Name of the departing port
          example: NORFOLK, VA
        departingPortLocode:
          type: string
          nullable: true
          description: Departing port UNLOCODE
          example: USORF
        departingTerminalCode:
          type: string
          nullable: true
          description: Departing port terminal FIRMS code
          example: N195
        vessel:
          type: string
          nullable: true
          description: Vessel name
          example: BOAT BOAT
        vesselImo:
          type: string
          nullable: true
          description: Vessel IMO number
          example: '123456'
        voyage:
          type: string
          nullable: true
          description: Departing voyage code
          example: 123W
        earlyReturnDate:
          type: string
          nullable: true
          format: date-time
          description: Timestamp of the earliest return date (ISO 8601 format). Specified by the carrier or terminal.
          example: '2022-09-21T13:34:06.221Z'
        reeferEarlyReturnDate:
          type: string
          nullable: true
          format: date-time
          description: Timestamp of the refrigerated shipment earliest return date (ISO 8601 format).
          example: '2022-09-21T13:34:06.221Z'
        hazmatEarlyReturnDate:
          type: string
          nullable: true
          format: date-time
          description: Timestamp of the hazardous materials shipment earliest return date (ISO 8601 format).
          example: '2022-09-21T13:34:06.221Z'
        carrierEarlyReturnDate:
          type: string
          nullable: true
          format: date-time
          description: Timestamp of the earliest return date as specified by the carrier (ISO 8601 format).
          example: '2022-09-21T13:34:06.221Z'
        latestReturn:
          type: string
          nullable: true
          format: date-time
          description: Timestamp of the cargo cutoff date (ISO 8601 format). Specified by the carrier or terminal.
          example: '2022-09-28T13:34:14.082Z'
        reeferCutoff:
          type: string
          nullable: true
          format: date-time
          description: Timestamp of the refrigerated cargo cutoff date (ISO 8601 format).
          example: '2022-09-21T13:34:07.817Z'
        hazmatCutoff:
          type: string
          nullable: true
          format: date-time
          description: Timestamp of the hazardous materials cargo cutoff date (ISO 8601 format).
          example: '2022-09-21T13:34:07.817Z'
        docCutoff:
          type: string
          nullable: true
          format: date-time
          description: Timestamp of the documentation cutoff date (ISO 8601 format).
          example: '2022-09-21T13:34:07.817Z'
        vgmCutoff:
          type: string
          nullable: true
          format: date-time
          description: Timestamp of the VGM filing cutoff date (ISO 8601 format).
          example: '2022-09-21T13:34:15.729Z'
        estArrival:
          type: string
          nullable: true
          description: Timestamp of the estimated arrival date (ISO 8601 format).
          example: '2022-10-20T11:00:00.000Z'
        actArrival:
          type: string
          nullable: true
          format: date-time
          description: Timestamp of the actual arrival date (ISO 8601 format).
          example: null
        estDeparture:
          type: string
          nullable: true
          format: date-time
          description: Timestamp of the estimated departure date (ISO 8601 format).
          example: '2022-10-21T13:34:14.082Z'
        actDeparture:
          type: string
          nullable: true
          format: date-time
          description: Timestamp of the actual departure date (ISO 8601 format).
          example: null
        reference:
          type: string
          nullable: true
          description: Customer reference field.
          example: null
        portOfDischarge:
          type: string
          nullable: true
          description: Name of the port of discharge.
          example: null
        estDischargeDate:
          type: string
          nullable: true
          format: date-time
          description: Timestamp of the estimated discharge date (ISO 8601 format).
          example: null
        equipmentQuantity:
          type: string
          nullable: true
          description: Total number of containers included in the booking.
          example: '1'
        equipmentType:
          type: string
          nullable: true
          description: Equipment code(s) included in the booking (ISO 6346 size/type code format; comma delimited).
          example: '45G1'
        equipment:
          type: array
          description: Equipment listing.
          items:
            type: object
            properties:
              equipmentQuantity:
                type: number
                description: Number of pieces of quipment.
                example: 1
              equipmentType:
                type: string
                nullable: true
                description: Equipment code (ISO 6346 format)
                example: '45G1'
        shipper:
          type: string
          nullable: true
          description: Name of the booking shipper
          example: null
        containers:
          type: array
          items:
            type: string
          description: Listing of the container numbers included in the booking (ISO 6346 format; comma delimited).
          example: [ABCU1234567]
        receivingTerminalMode:
          type: string
          nullable: true
          description: Alternate reciving terminal mode [reserved for future use].
          example: null
        railTerminalName:
          type: string
          nullable: true
          description: Name of the rail receiving terminal.
          example: null
        railTerminalLocode:
          type: string
          nullable: true
          description: Rail receiving terminal UNLOCODE.
          example: null
        projectedReceivingDates:
          type: boolean
          nullable: true
          description: Indicates the rail receiving dates are projected Splice Exports calulations.
          example: true
        railTerminalCode:
          type: string
          nullable: true
          description: Rail receiving terminal FIRMS code.
          example: null
        railEarlyReturn:
          type: string
          nullable: true
          format: date-time
          description: Timestamp of the rail earliest return date (ISO 8601 format).
          example: null
        railCutoff:
          type: string
          nullable: true
          format: date-time
          description: Timestamp of the rail cargo cutoff date (ISO 8601 format).
          example: null
        railEstDeparture:
          type: string
          nullable: true
          format: date-time
          description: Timestamp of the rail estimated departure date (ISO 8601 format).
          example: null
        railEstArrival:
          type: string
          nullable: true
          format: date-time
          description: Timestamp of the rail estimated arrival date (ISO 8601 format).
          example: null
        railActDeparture:
          type: string
          nullable: true
          format: date-time
          description: Timestamp of the rail actual departure date (ISO 8601 format).
          example: null
        railActArrival:
          type: string
          nullable: true
          format: date-time
          description: Timestamp of the rail actual arrival date (ISO 8601 format).
          example: null
        ultimateDestination:
          type: string
          nullable: true
          description: Name of the ultimate destination location
          example: null
        estArrivalDestination:
          type: string
          nullable: true
          format: date-time
          description: Timestamp of the estimated arrival date at the ultimate destination (ISO 8601 format).
          example: null
        assignee:
          type: string
          nullable: true
          description: Customer assignee field.
          example: null
    BookingWarnings:
      type: object
      properties:
        earlyReturnDate:
          type: string
          example: 'The early return date falls after the last return date'
        carrierEarlyReturnDate:
          type: string
          example: 'The carrier early return date falls after the last return date'
        departingPortLocode:
          type: string
          example: 'Departing port code is not set'
        vesselImo:
          type: string
          example: 'Vessel IMO not identified'
    BookingSummary:
      allOf:
        - $ref: '#/components/schemas/Booking'
        - type: object
          properties:
            sources:
              type: object
              additionalProperties:
                $ref: '#/components/schemas/Source'
    BookingDetails:
      allOf:
        - $ref: '#/components/schemas/Booking'
        - type: object
          properties:
            sources:
              type: object
              additionalProperties:
                $ref: '#/components/schemas/Source'
            history:
              type: array
              items:
                $ref: '#/components/schemas/Booking'
    BookingEvent:
      type: object
      required:
        - type
        - time
        - data
      properties:
        type:
          type: string
          enum:
            - export_booking_create
            - export_booking_update
        time:
          type: string
          format: date-time
          example: '2022-10-21T12:27:14.113Z'
        data:
          type: object
          required:
            - booking
          properties:
            booking:
              description: The current state of the booking record resulting from a create or update
              $ref: '#/components/schemas/Booking'
            changeset:
              description: For an update event, changeset is the value of the booking's field before the change
              $ref: '#/components/schemas/BookingChangeset'
            warnings:
              description: Potential booking errors by field
              $ref: '#/components/schemas/BookingWarnings'

    Container:
      type: object
      required:
        - containerNumber
      properties:
        containerNumber:
          type: string
          example: ABCU1234567
        equipmentType:
          type: string
          example: 45GP
        loadReference:
          type: string
          example: ABC12
        motorCarrierScac:
          type: string
          example: ZYXW
        chassisNumber:
          type: string
          example: CHAU123456
        cargoLoaded:
          type: boolean
          example: true
        sealNumber:
          type: string
          example: '1234567'
        emptyPickupDate:
          type: string
          format: date-time
          example: '2022-09-20T07:13:06.111Z'
        appointmentDate:
          type: string
          format: date-time
          example: '2022-09-22T09:45:00.000Z'
        terminalReceivedDate:
          type: string
          format: date-time
          example: '2022-09-22T09:52:13.654Z'
        vesselLoadedDate:
          type: string
          format: date-time
          example: '2022-09-27T14:04:18.656Z'
    Webhook:
      type: object
      required:
        - containerNumber
      properties:
        eventType:
          type: string
          enum:
            - EXPORT_BOOKING_CREATE
            - EXPORT_BOOKING_UPDATE
          example: EXPORT_BOOKING_CREATE
        endpoints:
          type: array
          items:
            $ref: '#/components/schemas/Endpoint'
    Endpoint:
      type: object
      required: 
        - url
        - created
        - createdBy
      properties:
        url:
          type: string
          example: http://example.com/webhook-listener
        secret:
          type: string
          example: shared-secret-value
        alias:
          type: string
          example: webhook endpoint 1
        terminalLocalTimestamp:
          type: boolean
          example: true
        created:
          type: string
          format: date-time
          example: '2024-03-07T21:10:58.000Z'
        createdBy:
          type: string
          example: user@ema.il
    WebhookEndpoint:
      type: object
      required:
        - url
      properties:
        url:
          type: string
          example: http://example.com/webhook-listener
        secret:
          type: string
          example: shared-secret-value
        alias:
          type: string
          example: webhook endpoint 1
        terminalLocalTimestamp:
          type: boolean
          example: true
    RailOption:
      type: object
      required:
        - originName
        - originCode
        - destinationName
        - destinationCode
        - departure
        - arrival
        - beginReceive
        - cutoff
      properties:
        originName:
          type: string
          description: "Name of the origin terminal."
          example: "BEDFORD PARK, IL"
        originCode:
          type: string
          description: "FIRMS Code of the origin terminal."
          example: "J470"
        destinationName:
          type: string
          description: "Name of the destination port terminal."
          example: "JAXPORT ICTF, FL"
        destinationCode:
          type: string
          description: "FIRMS Code of the destination port terminal."
          example: "M029"
        departure:
          type: string
          format: date-time
          description: "Scheduled departure timestamp (ISO 8601 format)."
          example: "2025-03-30T16:00:00.000Z"
        arrival:
          type: string
          format: date-time
          description: "Scheduled arrival timestamp (ISO 8601 format)."
          example: "2025-04-03T12:30:00.000Z"
        beginReceive:
          type: string
          format: date-time
          description: "Timestamp of the earliest return date (ISO 8601 format)."
          example: "2025-03-27T16:00:00.000Z"
        cutoff:
          type: string
          format: date-time
          description: "Timestamp of the cargo cutoff date (ISO 8601 format)."
          example: "2025-03-30T12:00:00.000Z"
  securitySchemes:
    ApiKeyAuthorizer:
      type: apiKey
      name: x-api-key
      in: header
