openapi: 3.1.0
info:
  title: Norfolk Southern Shipment Status API
  description: >-
    The Norfolk Southern Shipment Status API provides real-time visibility into
    rail shipment status, including current location, ETA, commodity details,
    origin, and destination. Part of the Norfolk Southern API Resource Platform
    (ApiHub).
  version: 1.0.0
  contact:
    name: Norfolk Southern CS Help Desk
    email: CSHelpDesk@NSCORP.COM
    url: https://developer.nscorp.com/
  license:
    name: Proprietary
    url: https://www.norfolksouthern.com/
servers:
  - url: https://api.nscorp.com
    description: Production
paths:
  /shipments/status:
    get:
      operationId: getShipmentStatus
      summary: Get Shipment Status
      description: >-
        Retrieve the current status of a rail shipment including location, ETA,
        commodity, origin, and destination details.
      tags:
        - Shipment Status
      parameters:
        - name: shipmentId
          in: query
          required: true
          description: The unique identifier for the shipment.
          schema:
            type: string
      responses:
        '200':
          description: Shipment status returned successfully.
          content:
            application/json:
              schema:
                type: object
                properties:
                  shipmentId:
                    type: string
                  status:
                    type: string
                  currentLocation:
                    type: string
                  eta:
                    type: string
                    format: date-time
                  origin:
                    type: string
                  destination:
                    type: string
                  commodity:
                    type: string
        '401':
          description: Unauthorized.
        '404':
          description: Shipment not found.
  /shipments/tripplan:
    get:
      operationId: getTripPlan
      summary: Get Trip Plan
      description: >-
        Track a shipment's progress on its planned route with current ETA,
        future movements, and completed movements.
      tags:
        - Trip Plan
      parameters:
        - name: shipmentId
          in: query
          required: true
          description: The unique identifier for the shipment.
          schema:
            type: string
      responses:
        '200':
          description: Trip plan returned successfully.
          content:
            application/json:
              schema:
                type: object
                properties:
                  shipmentId:
                    type: string
                  eta:
                    type: string
                    format: date-time
                  completedMovements:
                    type: array
                    items:
                      type: object
                      properties:
                        location:
                          type: string
                        timestamp:
                          type: string
                          format: date-time
                        event:
                          type: string
                  futureMovements:
                    type: array
                    items:
                      type: object
                      properties:
                        location:
                          type: string
                        estimatedTime:
                          type: string
                          format: date-time
                        event:
                          type: string
        '401':
          description: Unauthorized.
        '404':
          description: Shipment not found.
  /gatereceipts:
    get:
      operationId: getGateReceipts
      summary: Get Gate Receipts
      description: >-
        Access gate receipt data, terminal and driver information, and pickup
        numbers for equipment.
      tags:
        - Gate Receipts
      parameters:
        - name: terminalId
          in: query
          required: false
          description: The terminal identifier.
          schema:
            type: string
        - name: equipmentId
          in: query
          required: false
          description: The equipment identifier.
          schema:
            type: string
      responses:
        '200':
          description: Gate receipts returned successfully.
          content:
            application/json:
              schema:
                type: object
                properties:
                  gateReceipts:
                    type: array
                    items:
                      type: object
                      properties:
                        receiptId:
                          type: string
                        terminal:
                          type: string
                        driverInfo:
                          type: object
                          properties:
                            name:
                              type: string
                            id:
                              type: string
                        pickupNumber:
                          type: string
                        equipmentId:
                          type: string
                        timestamp:
                          type: string
                          format: date-time
        '401':
          description: Unauthorized.
tags:
  - name: Shipment Status
    description: Real-time shipment location and status tracking.
  - name: Trip Plan
    description: Shipment route progress and ETA tracking.
  - name: Gate Receipts
    description: Terminal gate receipt data and equipment information.