技能 Flexport物流核心流程管理

Flexport物流核心流程管理

v20260423
flexport-core-workflow-a
该工作流用于管理完整的供应链端到端流程。它允许用户通过API程序化地创建采购订单,预订货运(包括海运、空运、卡车),实时跟踪货件里程碑(如预计离港和到达时间),并检索提单等关键运输文件。适用于构建核心物流系统集成。
获取技能
423 次下载
概览

Flexport Core Workflow A: Bookings & Purchase Orders

Overview

The primary Flexport integration path: create purchase orders, book shipments, and track cargo through the supply chain. The API v2 uses RESTful endpoints at https://api.flexport.com with JSON payloads.

Prerequisites

  • Completed flexport-install-auth setup
  • Understanding of Flexport freight types (ocean FCL/LCL, air, trucking)
  • Valid shipper/consignee addresses configured in Flexport Portal

Instructions

Step 1: Create a Purchase Order

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

// POST /purchase_orders — create a PO to track inbound goods
const po = await fetch(`${BASE}/purchase_orders`, {
  method: 'POST',
  headers,
  body: JSON.stringify({
    name: 'PO-2025-001',
    status: 'open',
    buyer: { name: 'Acme Corp', address: { country: 'US' } },
    seller: { name: 'Shanghai Supplier', address: { country: 'CN' } },
    line_items: [
      { sku: 'WIDGET-A', quantity: 500, unit_of_measure: 'pieces' },
      { sku: 'WIDGET-B', quantity: 200, unit_of_measure: 'pieces' },
    ],
    cargo_ready_date: '2025-04-15',
    must_arrive_by: '2025-05-20',
  }),
}).then(r => r.json());

console.log(`PO created: ${po.data.id}`);

Step 2: Create a Booking

// POST /bookings — book freight against a purchase order
const booking = await fetch(`${BASE}/bookings`, {
  method: 'POST',
  headers,
  body: JSON.stringify({
    freight_type: 'ocean',          // ocean, air, trucking
    incoterm: 'FOB',                // FOB, CIF, EXW, DDP, etc.
    origin_port: { code: 'CNSHA' }, // Shanghai
    destination_port: { code: 'USLAX' }, // Los Angeles
    cargo_ready_date: '2025-04-15',
    purchase_order_ids: [po.data.id],
    wants_freight_management: true,
    wants_customs_service: true,
  }),
}).then(r => r.json());

console.log(`Booking: ${booking.data.id} | Status: ${booking.data.status}`);

Step 3: Track Shipment Milestones

// GET /shipments/:id — once booking is confirmed, a shipment is created
// Milestones include: cargo_ready, departed, arrived, customs_cleared, delivered
const shipment = await fetch(
  `${BASE}/shipments/${booking.data.shipment_id}`, { headers }
).then(r => r.json());

console.log(`Shipment ${shipment.data.id}:`);
console.log(`  Status: ${shipment.data.status}`);
console.log(`  ETD: ${shipment.data.estimated_departure_date}`);
console.log(`  ETA: ${shipment.data.estimated_arrival_date}`);
console.log(`  Legs: ${shipment.data.legs?.length ?? 0}`);

Step 4: Retrieve Documents

// GET /shipments/:id/documents — commercial invoices, bills of lading, etc.
const docs = await fetch(
  `${BASE}/shipments/${shipment.data.id}/documents`, { headers }
).then(r => r.json());

docs.data.records.forEach((doc: any) => {
  console.log(`${doc.document_type}: ${doc.file_name} (${doc.url})`);
});

Error Handling

ErrorCauseSolution
422 invalid port codeUnrecognized UN/LOCODEUse standard codes like CNSHA, USLAX
400 missing required fieldIncomplete bookingCheck freight_type, origin_port, destination_port
409 duplicate POPO name already existsUse unique name field or append timestamp
404 shipment not foundBooking not yet confirmedWait for booking confirmation webhook

Examples

List All Purchase Orders with Filters

const pos = await fetch(
  `${BASE}/purchase_orders?status=open&per=25&page=1`, { headers }
).then(r => r.json());

pos.data.records.forEach((po: any) => {
  console.log(`${po.name} | ${po.status} | Ready: ${po.cargo_ready_date}`);
});

Update PO Line Items

await fetch(`${BASE}/purchase_orders/${poId}`, {
  method: 'PATCH',
  headers,
  body: JSON.stringify({
    line_items: [{ sku: 'WIDGET-A', quantity: 750 }],  // Updated quantity
  }),
});

Resources

Next Steps

For customs and invoicing workflow, see flexport-core-workflow-b.

信息
分类 未分类
名称 flexport-core-workflow-a
版本 v20260423
大小 4.94KB
更新时间 2026-04-28
语言