TOS Integration

Turqoa integrates with Terminal Operating Systems (TOS) to validate appointments, retrieve container data, and report gate decisions. The TOS adapter supports Navis N4, TOPS Expert, and Tideworks with a unified interface.

Overview

The TOS integration serves as the data backbone for gate transactions. When a truck arrives at a gate lane, Turqoa queries the TOS to:

• Validate the appointment against the trucking company and container
• Retrieve expected container attributes (size, type, weight, hazmat class)
• Confirm hold status and customs clearance
• Report the gate decision back to the TOS upon transaction completion

Navis N4 Configuration

Navis N4 is connected via its REST API (N4 v3.8+) or legacy Web Services interface.

# turqoa-config.yaml
integrations:
  tos:
    provider: navis-n4
    base_url: https://n4.terminal.example.com/apex/api/v1
    auth:
      method: oauth2
      client_id: ${N4_CLIENT_ID}
      client_secret: ${N4_CLIENT_SECRET}
      token_url: https://n4.terminal.example.com/oauth/token
    options:
      facility_id: "USLAX"
      polling_interval_ms: 5000
      timeout_ms: 10000
      retry_attempts: 3

Required N4 API Scopes

TOPS Expert Integration

TOPS Expert uses a SOAP-based interface. Turqoa wraps the XML envelope automatically.

integrations:
  tos:
    provider: tops-expert
    wsdl_url: https://tops.terminal.example.com/GateService?wsdl
    auth:
      method: basic
      username: ${TOPS_USERNAME}
      password: ${TOPS_PASSWORD}
    options:
      terminal_code: "T18"
      soap_version: "1.2"
      connection_pool_size: 10

Tideworks Integration

Tideworks Mainsail connects via REST API with API key authentication.

integrations:
  tos:
    provider: tideworks
    base_url: https://api.tideworks.example.com/v2
    auth:
      method: api_key
      header: X-API-Key
      key: ${TIDEWORKS_API_KEY}
    options:
      terminal_id: "SEA-T5"
      batch_size: 50

Appointment Validation Flow

When a truck enters a gate lane, Turqoa runs the following validation sequence against the TOS:

1. Identify truck --- OCR reads the license plate and container number from camera feeds.
2. Query appointment --- Turqoa sends the container number and direction (inbound/outbound) to the TOS.
3. Validate attributes --- The TOS response is compared against detected attributes (container size, chassis type).
4. Check holds --- Any active holds (customs, USDA, freight) are flagged for operator review.
5. Return decision --- The Decision Engine produces an approve/reject/refer decision.
6. Report to TOS --- The final decision and transaction metadata are written back to the TOS.

Truck arrives → OCR capture → TOS query → Attribute match
                                              ↓
                              Decision Engine evaluation
                                              ↓
                              Approve / Reject / Refer
                                              ↓
                              Write-back to TOS

Error Handling

The TOS adapter implements resilient error handling to prevent gate lane downtime:

Note: In degraded mode, Turqoa continues processing transactions using cached TOS data. All transactions processed during degraded mode are flagged for reconciliation once the TOS connection is restored.