> ## 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

> Unified shipping API for label creation, document retrieval, and shipment tracking

# Flex Forward API

Flex Forward provides a single API for creating shipping labels, retrieving airway bill documents, and tracking shipments. One integration covers multiple courier services with a consistent request format, normalized tracking data, and built-in idempotency.

## Core workflows

<CardGroup cols={3}>
  <Card title="Create Labels" icon="tag" href="/api-reference/labels/create-label">
    Create shipping labels through supported courier services with idempotent requests.
  </Card>

  <Card title="Get Label Documents" icon="file-pdf" href="/api-reference/labels/get-label">
    Retrieve airway bill PDFs or PNGs for your created labels.
  </Card>

  <Card title="Track Shipments" icon="location-dot" href="/api-reference/tracking/get-tracking">
    Get real-time tracking status in a unified format across all couriers.
  </Card>
</CardGroup>

## Get started in 3 steps

<Steps>
  <Step title="Get API access">
    Request your API credentials by contacting the Flex Forward team at [flex-forward.support@returnhelper.com](mailto:flex-forward.support@returnhelper.com). You will receive a Bearer token for authentication.
  </Step>

  <Step title="Create your first label">
    Send a `POST /labels` request with your shipment details. The API returns a label ID and tracking number.
  </Step>

  <Step title="Retrieve documents and track">
    Use the label ID to retrieve the airway bill document (`GET /labels/{id}`) and track the shipment (`GET /tracking/{id}`).
  </Step>
</Steps>

<Card title="Follow the Quickstart guide" icon="rocket" href="/quickstart">
  Step-by-step walkthrough from authentication to your first label.
</Card>

## Integration flow

```mermaid theme={null}
graph LR
    A["Authenticate<br/>(Bearer token)"] --> B["Create Label<br/>POST /labels"]
    B --> C["Retrieve Document<br/>GET /labels/{id}"]
    B --> D["Track Shipment<br/>GET /tracking/{id}"]
    D -->|"Poll for updates"| D
```

## First request example

```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
}
```

## Production scope

Flex Forward is currently enabled for production shipments with YunExpress, supporting global cross-border e-commerce shipping lanes.

| Courier    | Slug         | Regions                        |
| ---------- | ------------ | ------------------------------ |
| YunExpress | `yunexpress` | Global cross-border e-commerce |

Additional carrier enablement is available based on shipping lane requirements and account onboarding. Contact the Flex Forward team to discuss carrier availability for your integration.

## Environments

| Environment | Base URL                          |
| ----------- | --------------------------------- |
| Production  | `https://api.flexforward.com`     |
| Development | `https://sandbox.flexforward.com` |

All API requests must be made over HTTPS. The development environment connects to courier sandbox services for safe testing.

<Card title="Environment details" icon="server" href="/environments">
  Credential separation, environment behavior, and operational notes.
</Card>

## Platform reliability

<CardGroup cols={2}>
  <Card title="Authentication" icon="key" href="/authentication">
    Bearer token authentication with best practices for credential management.
  </Card>

  <Card title="Error Handling" icon="triangle-exclamation" href="/error-handling">
    HTTP status codes, error response formats, and troubleshooting guidance.
  </Card>

  <Card title="Idempotency and Retries" icon="rotate" href="/idempotency-and-retries">
    Prevent duplicate label creation and retry requests safely.
  </Card>

  <Card title="Versioning" icon="code-branch" href="/versioning">
    How the API handles changes and backward compatibility.
  </Card>
</CardGroup>

## OpenAPI specification

<Card title="Download OpenAPI Spec" icon="file-code" href="/flex-forward.yaml">
  Download the OpenAPI 3.1 specification for code generation, client SDKs, and API tooling.
</Card>

## Support

For onboarding, integration support, or carrier availability inquiries, contact the Flex Forward team at [flex-forward.support@returnhelper.com](mailto:flex-forward.support@returnhelper.com).

<Card title="Support and FAQ" icon="circle-question" href="/support">
  Technical support, onboarding guidance, and frequently asked questions.
</Card>