Gate Transactions

Gate transaction endpoints provide access to vehicle and container processing records from Gate OS. Use these endpoints to query transaction history, retrieve detailed inspection results, and override automated decisions.

GET /api/v1/transactions

List gate transactions with filtering and pagination.

Request

curl "https://api.turqoa.com/v1/transactions?status=flagged&gate=gate_1&per_page=20" \
  -H "Authorization: Bearer $TURQOA_API_KEY"

Query Parameters

Response

{
  "data": [
    {
      "id": "txn_20260406_001",
      "gate": "gate_1",
      "status": "flagged",
      "decision": "manual_review",
      "created_at": "2026-04-06T08:15:32Z",
      "completed_at": null,
      "vehicle": {
        "plate": "ABC 1234",
        "plate_confidence": 0.97,
        "type": "truck",
        "carrier": "Maersk Line"
      },
      "container": {
        "id": "MSCU1234567",
        "ocr_confidence": 0.94,
        "iso_type": "22G1",
        "size": "20ft",
        "seal": {
          "number": "SL98765",
          "status": "intact",
          "confidence": 0.91
        }
      },
      "inspection": {
        "damage_detected": false,
        "ocr_match": true,
        "seal_verified": true,
        "anomalies": [
          {
            "type": "weight_discrepancy",
            "message": "Declared weight 18,200 kg, estimated 22,400 kg",
            "severity": "medium"
          }
        ]
      },
      "risk_score": 45,
      "processing_time_ms": 1230,
      "operator": null
    }
  ],
  "meta": {
    "request_id": "req_def456",
    "timestamp": "2026-04-06T10:00:00Z"
  },
  "pagination": {
    "page": 1,
    "per_page": 20,
    "total_items": 847,
    "total_pages": 43,
    "has_next": true,
    "has_previous": false
  }
}

Code Examples

Python

import requests

response = requests.get(
    "https://api.turqoa.com/v1/transactions",
    headers={"Authorization": f"Bearer {api_key}"},
    params={
        "status": "flagged",
        "gate": "gate_1",
        "start_date": "2026-04-06T00:00:00Z",
        "per_page": 20,
    },
)

transactions = response.json()["data"]
for txn in transactions:
    print(f"{txn['id']}: {txn['container']['id']} - {txn['status']}")

Node.js

const response = await fetch(
  "https://api.turqoa.com/v1/transactions?" +
    new URLSearchParams({
      status: "flagged",
      gate: "gate_1",
      start_date: "2026-04-06T00:00:00Z",
      per_page: "20",
    }),
  {
    headers: { Authorization: `Bearer ${apiKey}` },
  }
);

const { data: transactions } = await response.json();
transactions.forEach((txn) => {
  console.log(`${txn.id}: ${txn.container.id} - ${txn.status}`);
});

GET /api/v1/transactions/:id

Retrieve a single transaction with full detail including the complete inspection report, evidence images, and audit trail.

Request

curl https://api.turqoa.com/v1/transactions/txn_20260406_001 \
  -H "Authorization: Bearer $TURQOA_API_KEY"

Response

{
  "data": {
    "id": "txn_20260406_001",
    "gate": "gate_1",
    "status": "flagged",
    "decision": "manual_review",
    "created_at": "2026-04-06T08:15:32Z",
    "completed_at": null,
    "vehicle": {
      "plate": "ABC 1234",
      "plate_confidence": 0.97,
      "plate_image_url": "https://evidence.turqoa.com/txn_001/plate.jpg",
      "type": "truck",
      "carrier": "Maersk Line",
      "driver_id": "DRV-5521",
      "appointment_id": "APT-2026040608-003"
    },
    "container": {
      "id": "MSCU1234567",
      "ocr_confidence": 0.94,
      "ocr_image_url": "https://evidence.turqoa.com/txn_001/container_id.jpg",
      "iso_type": "22G1",
      "size": "20ft",
      "weight_declared_kg": 18200,
      "weight_estimated_kg": 22400,
      "seal": {
        "number": "SL98765",
        "status": "intact",
        "confidence": 0.91,
        "seal_image_url": "https://evidence.turqoa.com/txn_001/seal.jpg"
      }
    },
    "inspection": {
      "damage_detected": false,
      "damage_regions": [],
      "ocr_match": true,
      "seal_verified": true,
      "anomalies": [
        {
          "type": "weight_discrepancy",
          "message": "Declared weight 18,200 kg, estimated 22,400 kg",
          "severity": "medium",
          "confidence": 0.88
        }
      ],
      "images": [
        {
          "type": "front",
          "url": "https://evidence.turqoa.com/txn_001/front.jpg",
          "captured_at": "2026-04-06T08:15:30Z"
        },
        {
          "type": "left_side",
          "url": "https://evidence.turqoa.com/txn_001/left.jpg",
          "captured_at": "2026-04-06T08:15:31Z"
        },
        {
          "type": "right_side",
          "url": "https://evidence.turqoa.com/txn_001/right.jpg",
          "captured_at": "2026-04-06T08:15:31Z"
        },
        {
          "type": "rear",
          "url": "https://evidence.turqoa.com/txn_001/rear.jpg",
          "captured_at": "2026-04-06T08:15:32Z"
        }
      ]
    },
    "risk_score": 45,
    "risk_factors": [
      { "factor": "weight_discrepancy", "score": 35, "weight": 0.30 },
      { "factor": "first_visit_carrier", "score": 20, "weight": 0.15 },
      { "factor": "off_peak_arrival", "score": 15, "weight": 0.10 }
    ],
    "processing_time_ms": 1230,
    "audit_trail": [
      {
        "action": "transaction_created",
        "timestamp": "2026-04-06T08:15:32Z",
        "actor": "system"
      },
      {
        "action": "inspection_completed",
        "timestamp": "2026-04-06T08:15:33Z",
        "actor": "system",
        "details": "1 anomaly detected"
      },
      {
        "action": "flagged_for_review",
        "timestamp": "2026-04-06T08:15:33Z",
        "actor": "decision_engine",
        "rule": "weight_discrepancy_review"
      }
    ]
  }
}

POST /api/v1/transactions/:id/override

Override an automated gate decision. Requires transactions:write scope. Used when an operator reviews a flagged transaction and makes a manual decision.

Request

curl -X POST https://api.turqoa.com/v1/transactions/txn_20260406_001/override \
  -H "Authorization: Bearer $TURQOA_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "decision": "approved",
    "reason": "Weight discrepancy within acceptable range after manual check",
    "operator_id": "op_jsmith",
    "notes": "Verified with shipping manifest. Discrepancy due to dunnage weight."
  }'

Request Body

Response

{
  "data": {
    "id": "txn_20260406_001",
    "status": "overridden",
    "previous_decision": "manual_review",
    "new_decision": "approved",
    "overridden_by": "op_jsmith",
    "overridden_at": "2026-04-06T08:20:15Z",
    "reason": "Weight discrepancy within acceptable range after manual check",
    "gate_action": "open",
    "gate_action_executed": true
  }
}

Override Constraints

• Only transactions with status flagged or held can be overridden
• Overriding a rejected transaction requires admin scope
• All overrides are logged in the audit trail and cannot be deleted
• Override reason is required and must be at least 10 characters

Error Responses

Transaction already completed:

{
  "error": {
    "code": "resource_conflict",
    "message": "Transaction txn_20260406_001 is already in status 'approved' and cannot be overridden.",
    "request_id": "req_xyz789"
  }
}

Response Schema

Transaction Object