> ## Documentation Index
> Fetch the complete documentation index at: https://openapidocs.flexforwardship.com/llms.txt
> Use this file to discover all available pages before exploring further.

# 简介

> 开始使用 Flex Forward 配送 API

# Flex Forward API

Flex Forward 提供单一 API 来创建配送标签、获取运单文件，以及追踪货件。通过统一的请求格式、规范化的追踪数据与内建幂等性，一次集成即可对接多个物流商。

## 核心工作流程

<CardGroup cols={3}>
  <Card title="创建标签" icon="tag" href="/zh-hans/api-reference/labels/create-label">
    通过支持的物流商创建配送标签，支持幂等请求。
  </Card>

  <Card title="获取标签文件" icon="file-pdf" href="/zh-hans/api-reference/labels/get-label">
    获取已创建标签的运单 PDF 或 PNG。
  </Card>

  <Card title="货件追踪" icon="location-dot" href="/zh-hans/api-reference/tracking/get-tracking">
    以统一格式获取所有物流商的实时追踪信息。
  </Card>
</CardGroup>

## 三步骤开始

<Steps>
  <Step title="获取 API 访问权限">
    联系 Flex Forward 团队 [flex-forward.support@returnhelper.com](mailto:flex-forward.support@returnhelper.com) 申请 API 认证信息。您将收到用于身份验证的 Bearer 令牌。
  </Step>

  <Step title="创建您的第一个标签">
    发送包含配送信息的 `POST /labels` 请求。API 将返回标签 ID 和追踪号码。
  </Step>

  <Step title="获取文件并追踪">
    使用标签 ID 获取运单文件（`GET /labels/{id}`）并追踪货件（`GET /tracking/{id}`）。
  </Step>
</Steps>

<Card title="按照快速入门指南操作" icon="rocket" href="/zh-Hans/quickstart">
  从身份验证到创建第一个标签的逐步指南。
</Card>

## 集成流程

```mermaid theme={null}
graph LR
    A["身份验证<br/>(Bearer 令牌)"] --> B["创建标签<br/>POST /labels"]
    B --> C["获取文件<br/>GET /labels/{id}"]
    B --> D["追踪货件<br/>GET /tracking/{id}"]
    D -->|"轮询更新"| D
```

## 第一个请求示例

```bash theme={null}
curl -X POST https://api.flexforward.com/labels \
  -H "Authorization: Bearer YOUR_API_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "idempotencyKey": "ord-20250301-abc123",
    "courier": "yunexpress",
    "service": {
      "productCode": "HKMUZXR"
    },
    "shipment": {
      "shipFrom": {
        "contact": { "firstName": "Sender", "lastName": "Name", "phone": "+81-90-1234-5678" },
        "address": { "countryCode": "JP", "city": "Tokyo", "postalCode": "100-0001", "streetLines": ["1-1 Marunouchi"] }
      },
      "shipTo": {
        "contact": { "firstName": "Recipient", "lastName": "Name", "phone": "+1-555-0100" },
        "address": { "countryCode": "US", "city": "Los Angeles", "state": "CA", "postalCode": "90001", "streetLines": ["123 Main St"] }
      },
      "parcels": [{
        "weight": 0.5,
        "items": [{
          "descriptionEn": "T-Shirt",
          "descriptionLocal": "T恤",
          "quantity": 2,
          "unitPrice": { "amount": 25.00, "currency": "USD" },
          "unitWeight": 0.25
        }]
      }]
    }
  }'
```

```json 201 Created theme={null}
{
  "id": "a1b2c3d4-e5f6-7890-abcd-ef1234567890",
  "status": "created",
  "courier": "yunexpress",
  "courierOrderNumber": "YT2503010001",
  "courierTrackingNumber": "YT2503010001CN",
  "error": null
}
```

## 生产环境支持范围

Flex Forward 目前支持通过 YunExpress 进行生产环境的配送，涵盖全球跨境电商物流。

| 物流商        | 代码           | 服务区域   |
| ---------- | ------------ | ------ |
| YunExpress | `yunexpress` | 全球跨境电商 |

可根据物流路线需求及账户设置来启用额外的物流商。如需了解物流商的可用性，请联系 Flex Forward 团队。

## 环境

| 环境 | 基础 URL                            |
| -- | --------------------------------- |
| 生产 | `https://api.flexforward.com`     |
| 开发 | `https://sandbox.flexforward.com` |

所有 API 请求必须通过 HTTPS 发送。开发环境连接至物流商的沙盒服务，可安全进行测试。

<Card title="环境详情" icon="server" href="/zh-Hans/environments">
  认证信息分离、环境行为与运维注意事项。
</Card>

## 平台可靠性

<CardGroup cols={2}>
  <Card title="身份验证" icon="key" href="/zh-Hans/authentication">
    Bearer 令牌验证与认证信息管理最佳实践。
  </Card>

  <Card title="错误处理" icon="triangle-exclamation" href="/zh-Hans/error-handling">
    HTTP 状态码、错误响应格式与故障排除指南。
  </Card>

  <Card title="幂等性与重试" icon="rotate" href="/zh-Hans/idempotency-and-retries">
    防止重复创建标签并安全地重试请求。
  </Card>

  <Card title="版本管理" icon="code-branch" href="/zh-Hans/versioning">
    API 如何处理变更与向后兼容性。
  </Card>
</CardGroup>

## OpenAPI 规格

<Card title="下载 OpenAPI 规格" icon="file-code" href="/flex-forward.yaml">
  下载 OpenAPI 3.1 规格以用于代码生成、客户端 SDK 和 API 工具。
</Card>

## 支持

如需部署协助、集成支持或物流商可用性咨询，请联系 Flex Forward 团队：[flex-forward.support@returnhelper.com](mailto:flex-forward.support@returnhelper.com)

<Card title="支持与常见问题" icon="circle-question" href="/zh-Hans/support">
  技术支持、部署指南与常见问题。
</Card>