ship-hero

Compare original and translation side by side

🇺🇸

Original

English

🇨🇳

Translation

Chinese

ShipHero API Integration

ShipHero API集成

API Overview

API概述

ShipHero provides a GraphQL API for managing e-commerce fulfillment operations.

Endpoints:

GraphQL:
```
https://public-api.shiphero.com/graphql
```

Auth:

https://public-api.shiphero.com/auth/token

ShipHero 提供用于管理电商履约操作的GraphQL API。

端点：

GraphQL:
```
https://public-api.shiphero.com/graphql
```

身份验证:

https://public-api.shiphero.com/auth/token

Quick Start

快速开始

Authentication

身份验证

Get a JWT token (expires in 28 days):

bash

curl -X POST https://public-api.shiphero.com/auth/token \
  -H "Content-Type: application/json" \
  -d '{"email": "EMAIL", "password": "PASSWORD"}'

Use the token in all requests:

Authorization: Bearer YOUR_ACCESS_TOKEN

For detailed auth patterns including token refresh: See references/authentication.md

获取JWT令牌（有效期28天）：

bash

curl -X POST https://public-api.shiphero.com/auth/token \
  -H "Content-Type: application/json" \
  -d '{"email": "EMAIL", "password": "PASSWORD"}'

在所有请求中使用该令牌：

Authorization: Bearer YOUR_ACCESS_TOKEN

有关包括令牌刷新在内的详细身份验证模式：请参阅 references/authentication.md

Basic Query Pattern

基础查询模式

All queries return

request_id

complexity

, and

data

graphql

query {
  products {
    request_id
    complexity
    data(first: 25) {
      pageInfo { hasNextPage endCursor }
      edges {
        node { id sku name }
      }
    }
  }
}

所有查询返回

request_id

、

complexity

和

data

：

graphql

query {
  products {
    request_id
    complexity
    data(first: 25) {
      pageInfo { hasNextPage endCursor }
      edges {
        node { id sku name }
      }
    }
  }
}

Core Operations

核心操作

Orders

订单

graphql

undefined

graphql

undefined

Create order

创建订单

mutation { order_create(data: { order_number: "ORD-123" shop_name: "my-shop" shipping_address: { first_name: "John", last_name: "Doe", address1: "123 Main St", city: "NYC", state: "NY", zip: "10001", country: "US" } line_items: [{ sku: "SKU-001", quantity: 1, price: "29.99", product_name: "Widget" }] }) { order { id order_number } } }

undefined

undefined

Inventory

库存

graphql

undefined

graphql

undefined

Add inventory

添加库存

mutation { inventory_add(data: { sku: "SKU-001" warehouse_id: "WAREHOUSE_UUID" quantity: 50 reason: "Restocking" }) { warehouse_product { on_hand } } }


For complete operations: See [references/graphql-operations.md](references/graphql-operations.md)

mutation { inventory_add(data: { sku: "SKU-001" warehouse_id: "WAREHOUSE_UUID" quantity: 50 reason: "Restocking" }) { warehouse_product { on_hand } } }


完整操作请参阅：[references/graphql-operations.md](references/graphql-operations.md)

Rate Limits & Query Optimization

速率限制与查询优化

Credits:

Starting: 4,004 credits
Restore rate: 60 credits/second
Max operation cost: 4,004 credits
Hard limit: 7,000 requests per 5 minutes

Optimization tips:

Always specify
```
first
```
or
```
last
```
parameter (default 100 is expensive)
Use
```
analyze: true
```
to preview query cost before executing
Request only needed fields
Use filters (
```
created_at_min
```
,
```
updated_at_min
```
) to narrow results

graphql

undefined

积分：

初始额度：4004积分
恢复速率：60积分/秒
最大操作成本：4004积分
硬限制：每5分钟7000次请求

优化技巧：

始终指定
```
first
```
或
```
last
```
参数（默认100条成本较高）
使用
```
analyze: true
```
在执行前预览查询成本
仅请求所需字段
使用过滤器（
```
created_at_min
```
、
```
updated_at_min
```
）缩小结果范围

graphql

undefined

Preview query cost

预览查询成本

query { orders(analyze: true) { complexity # Returns estimated cost without executing } }

undefined

query { orders(analyze: true) { complexity # 返回估算成本但不执行查询 } }

undefined

Webhooks

Webhook

graphql

mutation {
  webhook_create(data: {
    name: "Shipment Update"  # Must match exactly
    url: "https://your-endpoint.com/webhook"
    shop_name: "api"
  }) {
    webhook { shared_signature_secret }  # Save this!
  }
}

Available webhooks: Inventory Update, Inventory Change, Shipment Update, Order Canceled, Order Packed Out, Return Update, PO Update, and more.

For full webhook reference: See references/webhooks.md

注册Webhook以接收实时事件：

graphql

mutation {
  webhook_create(data: {
    name: "Shipment Update"  # 必须完全匹配
    url: "https://your-endpoint.com/webhook"
    shop_name: "api"
  }) {
    webhook { shared_signature_secret }  # 请保存这个密钥！
  }
}

可用Webhook： 库存更新、库存变更、运单更新、订单取消、订单打包完成、退货更新、采购单更新等。

完整Webhook参考请参阅：references/webhooks.md

3PL Operations

3PL运营

For 3PL accounts managing multiple customers:

Option 1: Use customer's credentials directly

Option 2: Add

customer_account_id

to requests:

graphql

query {
  orders(customer_account_id: "CUSTOMER_UUID") {
    data(first: 25) { ... }
  }
}

对于管理多个客户的3PL账户：

选项1： 直接使用客户的凭据

选项2： 在请求中添加

customer_account_id

：

graphql

query {
  orders(customer_account_id: "CUSTOMER_UUID") {
    data(first: 25) { ... }
  }
}

Converting Legacy IDs

旧版ID转换

Convert legacy integer IDs to UUIDs:

graphql

query {
  uuid(legacy_id: 12345, entity_type: "order") {
    uuid
  }
}

将旧版整数ID转换为UUID：

graphql

query {
  uuid(legacy_id: 12345, entity_type: "order") {
    uuid
  }
}

Error Handling

错误处理

Capture

request_id

from all responses for debugging:

graphql

{
  orders {
    request_id  # Always include for support
    data { ... }
  }
}

Common error codes: 3 (Invalid Argument), 5 (Not Found), 16 (Unauthenticated)

从所有响应中捕获

request_id

用于调试：

graphql

{
  orders {
    request_id  # 请始终包含此字段以获取支持
    data { ... }
  }
}

常见错误代码：3（无效参数）、5（未找到）、16（未授权）

Python Client Example

Python客户端示例

python

from gql import gql, Client
from gql.transport.requests import RequestsHTTPTransport

transport = RequestsHTTPTransport(
    url="https://public-api.shiphero.com/graphql",
    headers={"Authorization": f"Bearer {token}"}
)
client = Client(transport=transport)

result = client.execute(gql("""
    query { products { data(first: 10) { edges { node { sku } } } } }
"""))

python

from gql import gql, Client
from gql.transport.requests import RequestsHTTPTransport

transport = RequestsHTTPTransport(
    url="https://public-api.shiphero.com/graphql",
    headers={"Authorization": f"Bearer {token}"}
)
client = Client(transport=transport)

result = client.execute(gql("""
    query { products { data(first: 10) { edges { node { sku } } } } }
"""))

Reference Files

参考文件

references/graphql-operations.md: Complete query/mutation examples for orders, products, inventory, shipments, returns, purchase orders
references/webhooks.md: Webhook types, registration, verification, best practices
references/authentication.md: Token management, refresh patterns, 3PL auth

references/graphql-operations.md：订单、产品、库存、运单、退货、采购单的完整查询/变更示例
references/webhooks.md：Webhook类型、注册、验证、最佳实践
references/authentication.md：令牌管理、刷新模式、3PL身份验证