easypost-api

Compare original and translation side by side

🇺🇸

Original

English

🇨🇳

Translation

Chinese

EasyPost API Skill

EasyPost API技能

This skill makes Claude productive at building EasyPost integrations. It covers the full shipping workflow: addresses, parcels, rates, labels, customs, tracking, pickups, scan forms, batches, insurance, claims, reports, webhooks, and the carrier-specific peculiarities that cause most real-world bugs.

It is Node.js-first and defaults to the official

@easypost/api

SDK, but field names and endpoint shapes are the same across languages. When the SDK can't do something, drop to

client.makeApiCall()

or raw HTTPS against the documented REST endpoint.

Source of truth, in this order:

Content of this skill (battle-tested patterns, carrier gotchas).
Official docs: https://docs.easypost.com/
SDK source: https://github.com/easypost/easypost-node

If this skill and the docs disagree about behavior, trust the docs and update the skill afterward.

本技能可帮助Claude高效构建EasyPost集成。它涵盖完整的物流工作流：地址、包裹、费率、标签、报关、追踪、上门取件、扫描单、批量处理、保险、理赔、报告、Webhook，以及导致多数实际场景bug的承运商特有细节。

本技能优先支持Node.js，默认使用官方

@easypost/api

SDK，但字段名称和端点结构在所有编程语言中保持一致。当SDK无法实现某些功能时，可使用

client.makeApiCall()

或直接调用文档中记录的REST端点进行HTTPS请求。

信息优先级如下：

本技能内容（经过实战检验的模式、承运商注意事项）
官方文档：https://docs.easypost.com/
SDK源码：https://github.com/easypost/easypost-node

若本技能与文档在行为描述上存在冲突，请以文档为准，并后续更新本技能。

How to use this skill

如何使用本技能

This skill is deliberately split into focused reference files. Don't load everything — load only the topics you need for the task at hand. Each file is short enough to digest in a single read and ends with pointers to adjacent topics.

Start by identifying the task, then read the matching file(s). If the task touches multiple areas (e.g., "international shipment with insurance"), read each area's file.

本技能被刻意拆分为多个聚焦主题的参考文件。无需加载全部内容，只需加载当前任务所需的主题文件即可。每个文件篇幅较短，可一次性阅读完毕，并在末尾提供相关主题的跳转指引。

首先确定任务类型，然后阅读对应的文件。若任务涉及多个领域（例如“带保险的国际货运”），则需阅读每个相关领域的文件。

Routing table

路由表

For ecommerce integrations, start with

references/ecommerce-flows.md

— it walks the cart → checkout → fulfillment → delivery → returns lifecycle and points at the per-concept files.

If the task is about…	Read
End-to-end ecommerce flow (cart, checkout, fulfillment, returns, notifications)	`references/ecommerce-flows.md`
What EasyPost does NOT do (duties, tax, autocomplete, cutoffs, etc.)	`references/scope-boundaries.md`
Installing the SDK, configuring the client, TypeScript types, test vs. production keys	`references/setup-and-client.md`
SDK helper methods ( `getLowestRate` , `validateWebhook` , `getLowestSmartRate` )	`references/utils.md`
Finding current service levels, predefined packages, supported options at runtime	`references/discovery.md`
Creating a shipment, picking a rate, buying a label, downloading the label	`references/shipments.md`
Address validation, international address quirks	`references/addresses.md`
Parcel dimensions, weight, predefined packages	`references/parcels.md`
Choosing the cheapest/fastest rate, SmartRate, Luma rulesets	`references/rates-and-smartrate.md`
International shipping, customs forms, EEI, incoterms, tax IDs	`references/international.md`
Real-time tracking, tracker statuses, tracking URLs, bulk retrieve	`references/tracking.md`
Webhook setup, HMAC verification, event payloads	`references/webhooks.md`
Return labels, refunding postage	`references/returns-refunds.md`
Bulk label purchase (batches)	`references/batches.md`
End-of-day scan forms / manifests	`references/scan-forms.md`
Scheduling carrier pickups	`references/pickups.md`
Buying insurance, filing claims	`references/insurance-claims.md`
CSV reports (shipment, invoice, cash flow, etc.)	`references/reports.md`
Adding/managing carrier accounts, credentials, metadata	`references/carrier-accounts.md`
Commercial invoice, QR codes, packing slips	`references/forms.md`
Error classes, retries, idempotency, rate limits	`references/errors-and-retries.md`
Listing resources, cursor pagination	`references/pagination.md`
Test API keys, test tracking codes, sandbox behavior	`references/testing.md`
API keys, users, child accounts, billing	`references/api-keys-users.md`
Multi-parcel Orders, EndShippers (resellers/DAP)	`references/orders-endshippers.md`
USPS specifics (flat rate, HazMat, domestic vs. international)	`references/carriers/usps.md`
UPS specifics (weight limits, OAuth, predefined packages)	`references/carriers/ups.md`
UPS Digital Access Program (DAP) rules	`references/carriers/ups-dap.md`
FedEx specifics (BYOCA, SmartPost, Express One Rate, lithium batteries)	`references/carriers/fedex.md`
DHL Express (international only)	`references/carriers/dhl-express.md`
DHL eCommerce (C2C/B2C only, placeholder rates)	`references/carriers/dhl-ecommerce.md`
ePost Global (USPS first mile + international)	`references/carriers/epost-global.md`

对于电商集成，请从

references/ecommerce-flows.md

开始——它涵盖了购物车→结账→履约→配送→退货的完整生命周期，并指向对应概念的文件。

若任务涉及…	阅读文件
端到端电商流程（购物车、结账、履约、退货、通知）	`references/ecommerce-flows.md`
EasyPost不支持的功能（关税、税费、自动补全、截止时间等）	`references/scope-boundaries.md`
SDK安装、客户端配置、TypeScript类型、测试与生产密钥	`references/setup-and-client.md`
SDK辅助方法（ `getLowestRate` 、 `validateWebhook` 、 `getLowestSmartRate` ）	`references/utils.md`
在运行时查找当前服务级别、预定义包裹、支持的选项	`references/discovery.md`
创建运单、选择费率、购买标签、下载标签	`references/shipments.md`
地址验证、国际地址特殊规则	`references/addresses.md`
包裹尺寸、重量、预定义包裹	`references/parcels.md`
选择最便宜/最快的费率、SmartRate、Luma规则集	`references/rates-and-smartrate.md`
国际货运、报关单、EEI、国际贸易术语、税号	`references/international.md`
实时追踪、追踪状态、追踪URL、批量检索	`references/tracking.md`
Webhook设置、HMAC验证、事件负载	`references/webhooks.md`
退货标签、邮资退款	`references/returns-refunds.md`
批量购买标签（批次处理）	`references/batches.md`
每日结束扫描单/清单	`references/scan-forms.md`
预约承运商上门取件	`references/pickups.md`
购买保险、提交理赔申请	`references/insurance-claims.md`
CSV报告（运单、发票、现金流等）	`references/reports.md`
添加/管理承运商账户、凭证、元数据	`references/carrier-accounts.md`
商业发票、二维码、装箱单	`references/forms.md`
错误类、重试、幂等性、速率限制	`references/errors-and-retries.md`
资源列表、游标分页	`references/pagination.md`
测试API密钥、测试追踪码、沙箱行为	`references/testing.md`
API密钥、用户、子账户、账单	`references/api-keys-users.md`
多包裹订单、EndShippers（经销商/DAP）	`references/orders-endshippers.md`
USPS特定规则（平邮、危险品、国内vs国际）	`references/carriers/usps.md`
UPS特定规则（重量限制、OAuth、预定义包裹）	`references/carriers/ups.md`
UPS数字访问计划（DAP）规则	`references/carriers/ups-dap.md`
FedEx特定规则（BYOCA、SmartPost、Express One Rate、锂电池）	`references/carriers/fedex.md`
DHL Express（仅国际）	`references/carriers/dhl-express.md`
DHL eCommerce（仅C2C/B2C，占位费率）	`references/carriers/dhl-ecommerce.md`
ePost Global（USPS首程+国际）	`references/carriers/epost-global.md`

Runnable examples

可运行示例

scripts/

contains minimal, runnable Node.js examples that you can copy wholesale as starting points:

```
scripts/create-shipment.mjs
```
— address → parcel → shipment → buy lowest rate → save label PDF

scripts/verify-address.mjs

— address verification with

createAndVerify

```
scripts/international-shipment.mjs
```
— customs info + items + shipment with tax identifier
```
scripts/track-shipment.mjs
```
— create tracker, poll status

scripts/webhook-handler.mjs

— Express endpoint using

client.Utils.validateWebhook

```
scripts/batch-buy.mjs
```
— create batch, add shipments, purchase, generate combined label
```
scripts/schedule-pickup.mjs
```
— create pickup, buy cheapest pickup rate
```
scripts/smartrate-deliver-by.mjs
```
— pick cheapest rate meeting a delivery deadline

scripts/

目录下包含极简的可运行Node.js示例，可直接复制作为开发起点：

```
scripts/create-shipment.mjs
```
— 地址→包裹→运单→购买最低费率→保存标签PDF

scripts/verify-address.mjs

— 使用

createAndVerify

进行地址验证

```
scripts/international-shipment.mjs
```
— 报关信息+物品+带税号的运单
```
scripts/track-shipment.mjs
```
— 创建追踪器、轮询状态

scripts/webhook-handler.mjs

— 使用

client.Utils.validateWebhook

的Express端点

```
scripts/batch-buy.mjs
```
— 创建批次、添加运单、购买、生成合并标签
```
scripts/schedule-pickup.mjs
```
— 创建取件预约、购买最便宜的取件费率
```
scripts/smartrate-deliver-by.mjs
```
— 选择满足配送期限的最便宜费率

Cardinal rules

核心规则

These apply everywhere and save most of the common footguns:

Always use a test API key during development. Production keys cost real money on every label purchase. Test keys start with
```
test_
```
(or
```
EZTK
```
), production with
```
EZAK
```
.
```
references/testing.md
```
has the full rundown.
Inspect
shipment.messages
whenever
rates
is shorter than expected. Carriers that failed to rate return a message (carrier name + reason) instead of a rate. Silently missing rates is usually a missing field or wrong credential.
For international shipments, customs info is required, not optional. Build
```
CustomsInfo
```
with accurate HS tariff numbers, set
```
customs_certify = true
```
, and set
```
customs_signer
```
. See
```
references/international.md
```
.
Do not trust
lowestRate()
blindly for international or time-critical shipments. Use SmartRate or Luma when delivery guarantees matter (
```
references/rates-and-smartrate.md
```
).
Verify webhook HMAC signatures with
client.Utils.validateWebhook()
. See
```
references/webhooks.md
```
for the exact pattern.
Rates and services differ between test and production. Negotiated discounts only surface in production. Don't use test-mode rates in your analytics.
Phone number and company name reduce address-correction fees on FedEx and UPS. Always pass them when you have them.
Label URLs expire.
```
postage_label.label_url
```
is a signed URL with a TTL. Download the PDF/PNG to your own storage immediately after purchase.
end_shipper_id
is required for UPS DAP and some reseller/partner accounts. If you get a rating error mentioning "end shipper," create an
```
EndShipper
```
and pass its ID at purchase.

Carrier-specific fields belong in
options
, not at the top level. E.g.,

options.hazmat

options.aes_itn

options.incoterm

options.delivery_confirmation

options.label_format

这些规则适用于所有场景，可避免多数常见陷阱：

开发期间务必使用测试API密钥。生产密钥会在每次购买标签时产生真实费用。测试密钥以
```
test_
```
（或
```
EZTK
```
）开头，生产密钥以
```
EZAK
```
开头。详细说明见
```
references/testing.md
```
。
当
rates
数量少于预期时，务必检查
shipment.messages
。未能返回费率的承运商会返回一条消息（承运商名称+原因）而非费率。费率缺失通常是因为缺少字段或凭证错误。
国际货运必须提供报关信息，而非可选。创建
```
CustomsInfo
```
时需填写准确的HS关税编号，设置
```
customs_certify = true
```
，并指定
```
customs_signer
```
。详见
```
references/international.md
```
。
对于国际货运或时间敏感的货运，请勿盲目信任
lowestRate()
。当配送时效有保障要求时，请使用SmartRate或Luma（详见
```
references/rates-and-smartrate.md
```
）。
使用
client.Utils.validateWebhook()
验证Webhook的HMAC签名。具体实现模式见
```
references/webhooks.md
```
。
测试环境与生产环境的费率和服务不同。协商折扣仅在生产环境中显示。请勿在分析中使用测试模式下的费率。
提供电话号码和公司名称可减少FedEx和UPS的地址修正费用。如有相关信息，请务必填写。
标签URL会过期。
```
postage_label.label_url
```
是带有有效期的签名URL。购买后请立即将PDF/PNG下载至您自己的存储系统。
UPS DAP和部分经销商/合作伙伴账户需要
end_shipper_id
。若收到提及“end shipper”的费率错误，请创建一个
```
EndShipper
```
并在购买时传入其ID。

承运商特定字段需放在
options
中，而非顶层。例如：

options.hazmat

、

options.aes_itn

、

options.incoterm

、

options.delivery_confirmation

、

options.label_format

。

Skill-wide conventions for generated code

生成代码时的技能通用约定

When you write EasyPost code for the user, follow these conventions unless the user says otherwise:

Use the SDK (
```
@easypost/api
```
) before raw HTTP. Fall back to
```
client.makeApiCall()
```
only for endpoints the SDK doesn't cover.
In TypeScript, import entity and parameter types from
```
@easypost/api
```
(
```
IShipment
```
,
```
IShipmentCreateParameters
```
, etc.).
Never hardcode an API key — read from
```
process.env.EASYPOST_API_KEY
```
.
Always wrap purchase calls (
```
Shipment.buy
```
,
```
Batch.buy
```
,
```
Pickup.buy
```
,
```
Insurance.create
```
) in try/catch. These are the calls that cost money.
Log the full
```
shipment.messages
```
array when a shipment has fewer rates than expected.
When downloading a label, fetch
```
postage_label.label_url
```
and persist the bytes — don't store just the URL.
When retrying a failed purchase, avoid double-purchasing: look up the shipment first and check whether
```
postage_label
```
is already populated.

Prefer

client.Utils

helpers (

getLowestRate

getLowestSmartRate

validateWebhook

) over rolling your own.

为用户编写EasyPost代码时，除非用户另有说明，请遵循以下约定：

优先使用SDK（
```
@easypost/api
```
）而非原生HTTP请求。仅当SDK未覆盖对应端点时，再使用
```
client.makeApiCall()
```
。
在TypeScript中，从
```
@easypost/api
```
导入实体和参数类型（如
```
IShipment
```
、
```
IShipmentCreateParameters
```
等）。
请勿硬编码API密钥——从
```
process.env.EASYPOST_API_KEY
```
读取。
务必将购买类调用（
```
Shipment.buy
```
、
```
Batch.buy
```
、
```
Pickup.buy
```
、
```
Insurance.create
```
）包裹在try/catch块中。这些调用会产生实际费用。
当运单的费率数量少于预期时，记录完整的
```
shipment.messages
```
数组。
下载标签时，获取
```
postage_label.label_url
```
并持久化字节数据——不要仅存储URL。
重试失败的购买请求时，避免重复购买：先查询运单并检查
```
postage_label
```
是否已填充。

优先使用

client.Utils

辅助方法（

getLowestRate

、

getLowestSmartRate

、

validateWebhook

）而非自行实现。

Writing style when teaching the user

指导用户时的写作风格

When the user is learning EasyPost (e.g., "how do I...?"), prefer showing a minimal runnable snippet over listing every field. Link to the specific reference file for the exhaustive field list. The PDF-style field dump is in the reference files; the top of SKILL.md and scripts are for "the five lines you actually need."

当用户学习EasyPost（例如“我该如何…？”）时，优先展示极简的可运行代码片段，而非列出所有字段。如需完整字段列表，请链接至对应的参考文件。参考文件中包含PDF式的字段详情；SKILL.md顶部和脚本目录提供的是“您实际需要的五行代码”。