openapi: 3.1.0
info:
  title: Navis N4 Terminal Operating System REST API
  description: >-
    NAVIS N4 provides terminal operating system APIs for container port operations.
    APIs enable container tracking, vessel planning, berth scheduling, yard management,
    and gate operations for port terminals and intermodal facilities. Now operated by
    Kaleris, serving 650+ organizations across 95+ countries.
  version: 2.0.0
  contact:
    name: Kaleris Support
    url: https://kaleris.com/support/
  license:
    name: Proprietary
    url: https://kaleris.com/terms-and-conditions/
externalDocs:
  description: Kaleris N4 Documentation
  url: https://kaleris.com/
servers:
  - url: https://{terminal}.navis.example.com/apex/n4/api/v2
    variables:
      terminal:
        default: yourterminal
        description: Your N4 terminal instance hostname
security:
  - BasicAuth: []
  - APIKey: []
paths:
  /units:
    get:
      operationId: searchUnits
      summary: Search container units
      description: >-
        Search for container units (TEUs, cargo units) in the terminal yard.
        Returns current position, status, hazmat class, and associated visit.
      tags:
        - Units
      parameters:
        - name: unitNbr
          in: query
          schema:
            type: string
          description: Container number (ISO 6346 format, e.g., MSCU1234567)
        - name: equipmentType
          in: query
          schema:
            type: string
            enum: [CTR, TRL, GENSET, CHASSIS]
        - name: category
          in: query
          schema:
            type: string
            enum: [IMPORT, EXPORT, TRANSSHIP, EMPTY]
        - name: freightKind
          in: query
          schema:
            type: string
            enum: [FCL, LCL, MTY]
        - name: positionLocType
          in: query
          schema:
            type: string
            enum: [YARD, VESSEL, TRUCK, RAIL, DOCK]
        - name: lineOperator
          in: query
          schema:
            type: string
          description: Shipping line SCAC code
        - name: vesselVisit
          in: query
          schema:
            type: string
          description: Vessel visit identifier
        - name: limit
          in: query
          schema:
            type: integer
            default: 100
            maximum: 1000
        - name: offset
          in: query
          schema:
            type: integer
            default: 0
      responses:
        '200':
          description: Container units matching the query
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/UnitListResponse'
        '401':
          $ref: '#/components/responses/Unauthorized'
  /units/{unitId}:
    get:
      operationId: getUnit
      summary: Get container unit details
      description: Retrieve full details of a container unit including position, status, holds, and event history.
      tags:
        - Units
      parameters:
        - name: unitId
          in: path
          required: true
          schema:
            type: string
          description: N4 unit identifier or ISO 6346 container number
      responses:
        '200':
          description: Container unit details
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Unit'
        '404':
          $ref: '#/components/responses/NotFound'
  /vessel-visits:
    get:
      operationId: listVesselVisits
      summary: List vessel visits
      description: >-
        Retrieve vessel visits (port calls) including vessel name, Lloyd's number,
        service, arrival/departure times, and berth assignment.
      tags:
        - Vessel Visits
      parameters:
        - name: vesselName
          in: query
          schema:
            type: string
        - name: status
          in: query
          schema:
            type: string
            enum: [INBOUND, WORKING, COMPLETE, DEPARTED]
        - name: arrivalFrom
          in: query
          schema:
            type: string
            format: date-time
        - name: arrivalTo
          in: query
          schema:
            type: string
            format: date-time
        - name: limit
          in: query
          schema:
            type: integer
            default: 50
      responses:
        '200':
          description: Vessel visits list
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/VesselVisitListResponse'
  /vessel-visits/{visitId}:
    get:
      operationId: getVesselVisit
      summary: Get vessel visit details
      description: Retrieve full vessel visit including bay plan, stow plan, and cargo manifest summary.
      tags:
        - Vessel Visits
      parameters:
        - name: visitId
          in: path
          required: true
          schema:
            type: string
      responses:
        '200':
          description: Vessel visit details
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/VesselVisit'
        '404':
          $ref: '#/components/responses/NotFound'
  /vessel-visits/{visitId}/units:
    get:
      operationId: getVesselVisitUnits
      summary: Get units for a vessel visit
      description: List all container units associated with a vessel visit (inbound and outbound).
      tags:
        - Vessel Visits
      parameters:
        - name: visitId
          in: path
          required: true
          schema:
            type: string
        - name: category
          in: query
          schema:
            type: string
            enum: [IMPORT, EXPORT, TRANSSHIP]
        - name: limit
          in: query
          schema:
            type: integer
            default: 500
      responses:
        '200':
          description: Units for the vessel visit
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/UnitListResponse'
  /gate-transactions:
    get:
      operationId: listGateTransactions
      summary: List gate transactions
      description: >-
        Retrieve in-gate and out-gate transactions. Returns truck visits,
        container gate-ins, and gate-outs with timestamps and driver information.
      tags:
        - Gate
      parameters:
        - name: transactionType
          in: query
          schema:
            type: string
            enum: [IN_GATE, OUT_GATE, TROUBLE]
        - name: containerNbr
          in: query
          schema:
            type: string
        - name: truckId
          in: query
          schema:
            type: string
        - name: fromDate
          in: query
          schema:
            type: string
            format: date-time
        - name: toDate
          in: query
          schema:
            type: string
            format: date-time
        - name: limit
          in: query
          schema:
            type: integer
            default: 100
      responses:
        '200':
          description: Gate transactions
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/GateTransactionListResponse'
  /work-queues:
    get:
      operationId: getWorkQueues
      summary: Get active work queues
      description: Retrieve current crane and equipment work queues showing pending moves.
      tags:
        - Operations
      parameters:
        - name: craneId
          in: query
          schema:
            type: string
        - name: status
          in: query
          schema:
            type: string
            enum: [QUEUED, IN_PROGRESS, COMPLETE]
      responses:
        '200':
          description: Work queues
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/WorkQueueListResponse'
  /holds:
    get:
      operationId: listHolds
      summary: List active holds on units
      description: >-
        Retrieve active holds (customs, line, port authority) on container units
        that prevent release or loading.
      tags:
        - Holds
      parameters:
        - name: unitNbr
          in: query
          schema:
            type: string
        - name: holdType
          in: query
          schema:
            type: string
        - name: limit
          in: query
          schema:
            type: integer
            default: 100
      responses:
        '200':
          description: Active holds
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/HoldListResponse'
components:
  securitySchemes:
    BasicAuth:
      type: http
      scheme: basic
    APIKey:
      type: apiKey
      in: header
      name: X-API-Key
  responses:
    Unauthorized:
      description: Authentication required
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/ErrorResponse'
    NotFound:
      description: Resource not found
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/ErrorResponse'
  schemas:
    Unit:
      type: object
      description: A container or cargo unit in the terminal
      properties:
        unitNbr:
          type: string
          description: ISO 6346 container number
        unitId:
          type: integer
          description: N4 internal unit identifier
        category:
          type: string
          enum: [IMPORT, EXPORT, TRANSSHIP, EMPTY]
        freightKind:
          type: string
          enum: [FCL, LCL, MTY]
        equipmentType:
          type: string
        equipmentLength:
          type: integer
          description: Length in feet (20, 40, 45, 48)
        lineOperator:
          type: string
          description: Shipping line SCAC code
        currentPosition:
          $ref: '#/components/schemas/YardPosition'
        arrivalVesselVisit:
          type: string
        departureVesselVisit:
          type: string
        holds:
          type: array
          items:
            $ref: '#/components/schemas/Hold'
        hazardous:
          type: boolean
        imdgClass:
          type: string
          description: IMDG hazardous goods class
        reefer:
          type: boolean
        temperature:
          type: number
          description: Required temperature for reefer units (Celsius)
        weight:
          type: number
          description: Gross weight in kg
        inGateDate:
          type: string
          format: date-time
        outGateDate:
          type: string
          format: date-time
    YardPosition:
      type: object
      properties:
        locType:
          type: string
          enum: [YARD, VESSEL, TRUCK, RAIL, DOCK, VESSEL_BUFFER]
        blockName:
          type: string
        bayNbr:
          type: integer
        rowNbr:
          type: integer
        tierNbr:
          type: integer
        slotName:
          type: string
          description: Full slot identifier (e.g., A01-01-01)
    UnitListResponse:
      type: object
      properties:
        units:
          type: array
          items:
            $ref: '#/components/schemas/Unit'
        totalCount:
          type: integer
        limit:
          type: integer
        offset:
          type: integer
    VesselVisit:
      type: object
      properties:
        visitId:
          type: string
        vesselName:
          type: string
        vesselLloyd:
          type: string
          description: Lloyd's Register vessel number
        mmsi:
          type: string
        imo:
          type: string
        lineOperator:
          type: string
        service:
          type: string
          description: Shipping service / string code
        berth:
          type: string
        status:
          type: string
          enum: [INBOUND, WORKING, COMPLETE, DEPARTED]
        eta:
          type: string
          format: date-time
        ata:
          type: string
          format: date-time
        etd:
          type: string
          format: date-time
        atd:
          type: string
          format: date-time
        plannedMoves:
          type: integer
        completedMoves:
          type: integer
        remainingMoves:
          type: integer
    VesselVisitListResponse:
      type: object
      properties:
        vesselVisits:
          type: array
          items:
            $ref: '#/components/schemas/VesselVisit'
        totalCount:
          type: integer
    GateTransaction:
      type: object
      properties:
        transactionId:
          type: string
        transactionType:
          type: string
          enum: [IN_GATE, OUT_GATE, TROUBLE]
        containerNbr:
          type: string
        truckId:
          type: string
        driverLicense:
          type: string
        transactionTime:
          type: string
          format: date-time
        laneId:
          type: string
        appointmentNbr:
          type: string
        lineOperator:
          type: string
    GateTransactionListResponse:
      type: object
      properties:
        transactions:
          type: array
          items:
            $ref: '#/components/schemas/GateTransaction'
        totalCount:
          type: integer
    WorkQueue:
      type: object
      properties:
        workQueueId:
          type: string
        craneId:
          type: string
        moveType:
          type: string
          enum: [LOAD, DISCH, SHIFT, DRAY, RECV]
        fromPosition:
          type: string
        toPosition:
          type: string
        containerNbr:
          type: string
        priority:
          type: integer
        status:
          type: string
          enum: [QUEUED, IN_PROGRESS, COMPLETE]
        assignedTo:
          type: string
          description: Equipment ID assigned to the move
    WorkQueueListResponse:
      type: object
      properties:
        queues:
          type: array
          items:
            $ref: '#/components/schemas/WorkQueue'
        totalCount:
          type: integer
    Hold:
      type: object
      properties:
        holdId:
          type: string
        holdType:
          type: string
          description: Type of hold (CUSTOMS, LINE, PORT, FREIGHT, etc.)
        holdStatus:
          type: string
          enum: [ACTIVE, RELEASED, EXPIRED]
        appliedBy:
          type: string
        appliedDate:
          type: string
          format: date-time
        releasedDate:
          type: string
          format: date-time
        reason:
          type: string
    HoldListResponse:
      type: object
      properties:
        holds:
          type: array
          items:
            $ref: '#/components/schemas/Hold'
        totalCount:
          type: integer
    ErrorResponse:
      type: object
      properties:
        errorCode:
          type: string
        errorMessage:
          type: string
        requestId:
          type: string
tags:
  - name: Gate
    description: Truck gate transactions
  - name: Holds
    description: Container hold management
  - name: Operations
    description: Work queues and crane operations
  - name: Units
    description: Container and cargo unit tracking
  - name: Vessel Visits
    description: Vessel port call management and planning