Suqan Logistics Partner SDK

Official JavaScript/Node.js SDK for the Suqan Logistics Partner API — the system-to-system integration surface for freight, LMD, and 3PL partners.

Authentication

Suqan issues each logistics company an API key (lc_...). Send it on every request:

X-API-Key: lc_your_api_key_here

Mobile apps may use Authorization: Bearer <jwt> from PIN login instead.

Installation

npm install @suqan/logistics-sdk

Quick start

import SuqanLogisticsClient from '@suqan/logistics-sdk';

const client = new SuqanLogisticsClient({
  apiKey: process.env.SUQAN_LOGISTICS_API_KEY,
  // baseUrl defaults to https://api.suqan.store/api/v1/logistics
});

// Inbound (freight partner)
const inbound = await client.inbound.listShipments({ status: 'IN_TRANSIT' });

// Outbound (LMD / 3PL)
const outbound = await client.outbound.listShipments({ scope: 'lmd', expressOnly: true });

// Cross-dock
const queue = await client.crossDock.listQueue();

// Shared
const fees = await client.shared.getFeeCatalog();

Namespaces

| Namespace | Base path | Use case | |-----------|-----------|----------| | client.inbound | /inbound/* | Freight, warehouse receipt, evidence, handover, sync | | client.outbound | /outbound/* | LMD/3PL shipments, parcels, scans, zones | | client.crossDock | /cross-dock/* | Cross-dock queue and scans | | client.shared | /fee-catalog, /staff, /webhooks | Partner utilities |

Idempotency

Mutations that support idempotency accept idempotencyKey in the body and/or X-Idempotency-Key header:

await client.inbound.updateStatus(
  shipmentId,
  { status: 'IN_TRANSIT', metadata: {} },
  { idempotencyKey: crypto.randomUUID() }
);

OpenAPI contract

The API contract lives at:

• Repo: docs/api/openapi/logistics.openapi.json
• Live: GET /api/v1/logistics/openapi
• Docs UI: /docs/api/logistics

SDK types in src/generated/contract.ts mirror this spec.

Development

cd packages/suqan-logistics-sdk
npm install
npm test
npm run build

Error handling

import { AuthenticationError, ValidationError } from '@suqan/logistics-sdk';

try {
  await client.outbound.getShipment('invalid-id');
} catch (error) {
  if (error instanceof AuthenticationError) {
    // Invalid or missing API key
  }
}

Support

• Email: [email protected]
• OpenAPI: /api/v1/logistics/openapi