技能 编程开发 Flexport API快速上手指南

Flexport API快速上手指南

v20260423
flexport-hello-world
本指南提供了一个与Flexport REST API v2交互的最小化工作示例。它演示了核心物流操作,如列出货运单、获取详细的运输里程碑和列出关联集装箱。适用于刚开始接入Flexport系统、进行API连接测试或学习基础API开发模式的开发者。
获取技能
167 次下载
概览

Flexport Hello World

Overview

List shipments and retrieve tracking milestones using the Flexport REST API v2. Flexport has no npm SDK -- you call https://api.flexport.com directly with bearer token auth and a Flexport-Version: 2 header.

Prerequisites

  • FLEXPORT_API_KEY environment variable set
  • Completed flexport-install-auth setup
  • Node.js 18+ (uses native fetch)

Instructions

Step 1: List Your Shipments

// src/flexport/hello.ts
const BASE = 'https://api.flexport.com';
const headers = {
  'Authorization': `Bearer ${process.env.FLEXPORT_API_KEY}`,
  'Flexport-Version': '2',
  'Content-Type': 'application/json',
};

// List shipments with pagination
const res = await fetch(`${BASE}/shipments?per=5&page=1`, { headers });
const { data } = await res.json();

data.records.forEach((shipment: any) => {
  console.log(`${shipment.id} | ${shipment.status} | ${shipment.freight_type}`);
  console.log(`  Origin: ${shipment.origin_port?.name ?? 'N/A'}`);
  console.log(`  Dest:   ${shipment.destination_port?.name ?? 'N/A'}`);
});

Step 2: Get Shipment Details with Milestones

// Retrieve a single shipment with tracking milestones
const shipmentId = data.records[0].id;
const detail = await fetch(`${BASE}/shipments/${shipmentId}`, { headers }).then(r => r.json());

console.log(`\nShipment ${detail.data.id}:`);
console.log(`  Status: ${detail.data.status}`);
console.log(`  Cargo ready: ${detail.data.cargo_ready_date}`);
console.log(`  Containers: ${detail.data.containers?.length ?? 0}`);

Step 3: List Containers on a Shipment

// Get container details for ocean freight shipments
const containers = await fetch(
  `${BASE}/shipments/${shipmentId}/containers`, { headers }
).then(r => r.json());

containers.data.records.forEach((c: any) => {
  console.log(`Container ${c.container_number} | ${c.container_type} | ${c.status}`);
});

Output

shp_abc123 | in_transit | ocean
  Origin: Shanghai Port
  Dest:   Los Angeles Port

Shipment shp_abc123:
  Status: in_transit
  Cargo ready: 2025-03-01
  Containers: 2

Container MSKU1234567 | 40ft_hc | in_transit

Error Handling

ErrorCauseSolution
401 UnauthorizedInvalid API keyCheck FLEXPORT_API_KEY env var
404 Not FoundWrong shipment IDVerify ID from /shipments list
422 UnprocessableBad query paramsCheck per/page are integers
Empty records arrayNo shipments yetCreate a booking first or use sandbox

Examples

Python Quick Start

import os, requests

BASE = 'https://api.flexport.com'
headers = {
    'Authorization': f'Bearer {os.environ["FLEXPORT_API_KEY"]}',
    'Flexport-Version': '2',
}

shipments = requests.get(f'{BASE}/shipments', headers=headers, params={'per': 5}).json()
for s in shipments['data']['records']:
    print(f"{s['id']} | {s['status']} | {s['freight_type']}")

cURL One-Liner

curl -s -H "Authorization: Bearer $FLEXPORT_API_KEY" \
     -H "Flexport-Version: 2" \
     https://api.flexport.com/shipments?per=3 | jq '.data.records[] | {id, status, freight_type}'

Resources

Next Steps

Proceed to flexport-local-dev-loop for development workflow setup.

信息
分类 编程开发
名称 flexport-hello-world
版本 v20260423
大小 3.92KB
更新时间 2026-04-26
语言