Trabex Shipments API

openapi: 3.2.0
info:
  title: Trabex Trade Compliance Shipments API
  description: The Trabex Trade Compliance API provides programmatic access to export compliance automation including shipment data submission, export documentation generation, Automated Export System (AES) filing, and restricted party screening (RPS).
  version: '1.0'
  contact:
    name: Trabex Support
    url: https://support.trabex.io/support/home
  termsOfService: https://trabex.io
servers:
- url: https://api.trabex.io
  description: Production Server
security:
- apiKeyAuth: []
tags:
- name: Shipments
  description: Submit and manage export shipment data for compliance processing, AES filing, and documentation generation.
paths:
  /v1/shipments:
    get:
      operationId: getShipments
      summary: Get Shipments
      description: Retrieves a list of shipments submitted to the Trabex platform for compliance processing. Supports filtering by status, date range, and other criteria.
      tags:
      - Shipments
      parameters:
      - name: status
        in: query
        description: Filter by shipment compliance status.
        required: false
        schema:
          type: string
          enum:
          - Pending
          - Processing
          - Approved
          - Flagged
          - Filed
      - name: page
        in: query
        description: Page number for paginated results.
        required: false
        schema:
          type: integer
          minimum: 1
      - name: pageSize
        in: query
        description: Number of records per page.
        required: false
        schema:
          type: integer
          minimum: 1
          maximum: 100
      - name: fromDate
        in: query
        description: Filter shipments created on or after this date (ISO 8601).
        required: false
        schema:
          type: string
          format: date
      - name: toDate
        in: query
        description: Filter shipments created on or before this date (ISO 8601).
        required: false
        schema:
          type: string
          format: date
      responses:
        '200':
          description: Successfully retrieved shipments
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ShipmentsListResponse'
        '401':
          description: Unauthorized - invalid or missing API key
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
    post:
      operationId: createShipment
      summary: Create Shipment
      description: Submits a new export shipment for compliance processing. Triggers automated restricted party screening, AES filing eligibility assessment, and export documentation generation.
      tags:
      - Shipments
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/ShipmentRequest'
      responses:
        '201':
          description: Shipment successfully created and queued for processing
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Shipment'
        '400':
          description: Invalid shipment data
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
        '401':
          description: Unauthorized
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
  /v1/shipments/{shipmentId}:
    get:
      operationId: getShipment
      summary: Get Shipment
      description: Retrieves details of a specific shipment including compliance status, screening results, AES filing status, and generated documents.
      tags:
      - Shipments
      parameters:
      - $ref: '#/components/parameters/ShipmentId'
      responses:
        '200':
          description: Successfully retrieved shipment
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Shipment'
        '401':
          description: Unauthorized
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
        '404':
          description: Shipment not found
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
    put:
      operationId: updateShipment
      summary: Update Shipment
      description: Updates an existing shipment with corrected information before or during compliance processing. Triggers re-screening and re-evaluation of the updated shipment data.
      tags:
      - Shipments
      parameters:
      - $ref: '#/components/parameters/ShipmentId'
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/ShipmentRequest'
      responses:
        '200':
          description: Shipment successfully updated
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Shipment'
        '400':
          description: Invalid shipment data
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
        '401':
          description: Unauthorized
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
        '404':
          description: Shipment not found
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
components:
  schemas:
    Error:
      type: object
      description: Standard error response from the Trabex API.
      properties:
        code:
          type: string
          description: Error code identifier.
        message:
          type: string
          description: Human-readable error description.
        details:
          type: array
          description: Additional error detail messages.
          items:
            type: string
    Party:
      type: object
      description: A trading party for restricted party screening.
      properties:
        name:
          type: string
          description: Full legal name of the party.
        address:
          type: string
          description: Street address.
        city:
          type: string
          description: City.
        state:
          type: string
          description: State or province.
        country:
          type: string
          description: ISO 3166-1 alpha-2 country code.
        postalCode:
          type: string
          description: Postal or zip code.
    ExportLineItem:
      type: object
      description: A line item in an export shipment.
      properties:
        description:
          type: string
          description: Description of the commodity.
        scheduleBNumber:
          type: string
          description: Schedule B or HTS classification number.
        quantity:
          type: number
          description: Export quantity.
        unitOfMeasure:
          type: string
          description: Unit of measure code.
        valueUSD:
          type: number
          format: double
          description: Value in US dollars.
        countryOfOrigin:
          type: string
          description: ISO 3166-1 alpha-2 country of origin code.
        eccnNumber:
          type: string
          description: Export Control Classification Number if applicable.
    Shipment:
      type: object
      description: An export shipment with compliance status and results.
      properties:
        shipmentId:
          type: string
          description: Unique Trabex identifier for the shipment.
        status:
          type: string
          description: Current compliance processing status.
          enum:
          - Pending
          - Processing
          - Approved
          - Flagged
          - Filed
        screeningStatus:
          type: string
          description: Restricted party screening result.
          enum:
          - Clear
          - Review
          - Blocked
        aesStatus:
          type: string
          description: AES filing status.
          enum:
          - NotRequired
          - Pending
          - Accepted
          - Fatal
          - Rejected
        itn:
          type: string
          description: Internal Transaction Number (ITN) from AES upon successful filing.
        createdAt:
          type: string
          format: date-time
          description: Timestamp when the shipment was created.
        updatedAt:
          type: string
          format: date-time
          description: Timestamp of last update.
        shipper:
          $ref: '#/components/schemas/Party'
        consignee:
          $ref: '#/components/schemas/Party'
        destinationCountry:
          type: string
        lineItems:
          type: array
          items:
            $ref: '#/components/schemas/ExportLineItem'
    ShipmentRequest:
      type: object
      description: Request body for creating or updating an export shipment.
      required:
      - shipper
      - consignee
      - destinationCountry
      - lineItems
      properties:
        shipper:
          $ref: '#/components/schemas/Party'
        consignee:
          $ref: '#/components/schemas/Party'
        freightForwarder:
          $ref: '#/components/schemas/Party'
        destinationCountry:
          type: string
          description: ISO 3166-1 alpha-2 destination country code.
        exportDate:
          type: string
          format: date
          description: Planned or actual export date.
        carrier:
          type: string
          description: Carrier name or SCAC code.
        trackingNumber:
          type: string
          description: Shipment tracking or bill of lading number.
        lineItems:
          type: array
          description: List of commodity line items in the shipment.
          items:
            $ref: '#/components/schemas/ExportLineItem'
        referenceNumber:
          type: string
          description: Internal reference or order number.
    ShipmentsListResponse:
      type: object
      description: Paginated list of export shipments.
      properties:
        total:
          type: integer
          description: Total number of matching shipments.
        page:
          type: integer
        pageSize:
          type: integer
        shipments:
          type: array
          items:
            $ref: '#/components/schemas/Shipment'
  parameters:
    ShipmentId:
      name: shipmentId
      in: path
      required: true
      description: The unique identifier of the shipment.
      schema:
        type: string
  securitySchemes:
    apiKeyAuth:
      type: apiKey
      in: header
      name: X-API-Key
      description: Trabex API key for authenticating requests. Obtain your API key from the Trabex customer portal at support.trabex.io.
externalDocs:
  description: Trabex API Documentation
  url: https://apidocs.trabex.io/