# HF Connector API — for machines / agents

Prefer this file + `openapi-v1.yaml` over human prose. Human guide: https://honestfulphilment.com/ai-integration/

## Identity

- Product: Honest FulPhilment (HF), China sourcing and eCommerce fulfilment for Shopify and WooCommerce stores
- Auth header: `x-key: <API key>` (create at https://app.honestfulphilment.com/setting/access-key)
- Production base: `https://api.honestfulphilment.com`
- Path prefix: `/connector/v1` (not `/api/v1`)
- Rate limit: 60 req/min per key; pay endpoint 10/min; HTTP 429 on exceed (`Retry-After: 60`)
- Page size max: 100
- OpenAPI 3: https://honestfulphilment.com/ai/openapi-v1.yaml

## Scopes (comma-separated on key)

| Scope | Methods |
|-------|---------|
| `orders:read` | `GET /connector/v1/orders`, `GET /connector/v1/orders/{id}` |
| `inventory:read` | `GET /connector/v1/inventory`, `GET /connector/v1/inventory/{sku}` |
| `balance:read` | `GET /connector/v1/balance`, `GET /connector/v1/billing` |
| `rates:read` | `GET /connector/v1/shipping-rates` |
| `orders:pay` | `POST /connector/v1/orders/{id}/pay` |

Default keys omit `orders:pay`. Do not pay without explicit user intent and that scope.

## Response envelope

`{ status, data, errorCode, errorMessage, pageIndex, pageSize, totalCount }`. Treat non-2xx or a failed `status` as an error; `429` = back off.

## Orders

- `{id}` accepts the HF order id or the order number (`orderNo`)
- Amounts are returned in **USD** (`currency` is always `USD`); `confirmAmount` on pay must match the USD total
- Public status: `NOT_PAID` · `PROCESSING` · `SHIPPED` · `CANCEL` · `REFUND` · `PARTIALLY_PAID` · `UNKNOWN`
- List filter `status`: `ALL` / `NOT_PAID` / `NOT_HANDLE` / `SENDED` / `CANCEL` / `REFUND` / `PARTIALLY_PAID`
- Items include Shopify/WooCommerce order numbers and item/variant ids; `shipmentNo` is the main tracking number, `transferNo` the last-mile number when available

## Shipping rates

- Query: `countryCode` (required), optional `postCode` (recommended for AU/CA), `items=SKU1:2,SKU2:1`
- Weight comes from the HF catalog (do not pass weight)
- Prices are USD, the same as the HF web app shipping calculator

## Pay rules

- Body JSON: `{ "idempotencyKey": "<unique>", "confirmAmount": optional number }`
- Always send a unique `idempotencyKey` per payment attempt; the key is bound to one order
- Success / replay: check the response; do not retry with a new key after success
- Insufficient balance: business code `006`

## MCP

Package: https://honestfulphilment.com/ai/hf-claude-mcp.zip (stdio, Node.js 18+). Env: `HF_API_KEY` (required), `HF_BASE_URL` (optional).
Tools map 1:1 to the REST paths above: `list_orders`, `get_order`, `list_inventory`, `get_inventory`, `get_balance`, `list_billing`, `list_shipping_rates`, `pay_order`.