日本海外仓与第三方物流
面向多货主、多仓库业务，由 WMS 根据货主合同、仓库和配送规则选择承运商；生成完成后，将运单号和处理结果写回对应包裹。
INTEGRATION
一个 API，简化日本面单生成。
将 WMS、OMS、ERP 或电商系统连接至 ShippSyS，只需一套请求即可生成多家日本承运商的面单，并将 PDF、运单号和处理结果返回原系统。
免费试用可生成 100 张面单，用于验证接口、打印和结果回传。
60-SECOND OVERVIEW
用四个要点理解 API 集成
- 提交
- 承运商、收件信息、包裹和配送服务
- 验证
- 生成前用
/labels/validate检查同一份数据 - 生成
- 通过
POST /labels批量提交面单生成任务 - 获取
- 处理状态、PDF、运单号和标准化错误
简短请求示例cURL / JSON
curl -X POST \
'https://api.shippsys.com/shippsys-api/label/v1/labels?client_key=YOUR_CLIENT_KEY' \
-H 'Authorization: Bearer YOUR_TOKEN' \
-H 'Content-Type: application/json' \
-d '{ "schema_version": 1, "items": [{ "carrier": "sagawa", "client_reference": "ORDER-10001", "ship_date": "2026-08-23", "service": { "method_code": "1" }, "recipient": { "name1": "株式会社テスト", "phone": "03-1234-5678", "postal_code": "100-0001", "prefecture": "東京都", "city": "千代田区", "address1": "千代田1-1" }, "parcel": { "quantity": 1, "items": [{ "name": "商品" }] }, "payment": { "type": "prepaid" } }] }'为便于阅读，示例省略了可选字段。可用值及各承运商字段请以Quickstart和API Reference为准。
USE CASES
不更换现有系统，也能接入日本面单生成
适合已经使用 WMS、OMS 或 ERP，但仍需登录日本承运商软件、分别制作 CSV、手动回填运单号的企业和仓库。
电商平台与订单管理系统
让运营人员继续使用熟悉的 OMS 或管理后台，无需切换到各承运商系统，即可生成面单并查看 PDF、运单号和错误原因。
中国总部与日本仓库系统
复用总部 ERP 或业务系统中的订单、收件人和商品数据，将日本仓库的面单结果回传总部，减少跨团队 CSV 传递和重复录入。
FIT CHECK
适合采用 API 集成的业务
如果当前业务符合以下多项情况，可重点评估 API 集成。
- 根据订单条件使用多家承运商
- 发货数据已经保存在 WMS、OMS 或 ERP 中
- 仍需分别制作承运商 CSV 或操作承运商软件
- 希望将运单号自动回填至订单或发货数据
- 不同货主或日本仓库使用不同的承运商合同账号
- 希望在系统中保留错误、取消和重新生成记录
如果只使用一家承运商、发货量较少，并且现有承运商软件已经能够完成全部操作，则未必需要开发 API。我们会先了解当前流程，再建议使用 Web 应用（管理页面录入与 CSV 导入）、API 或 Next Engine 对接。通过 API 导入的数据也可在 Web 应用中确认、修改、打印和管理处理记录。
DATA FLOW
从接收发货数据到返回面单结果
ShippSyS 接收发货数据后，按指定承运商和配送服务完成转换与面单生成，再将 PDF、运单号和处理状态返回原系统。
IMPLEMENTATION
上线前需要确认的 5 个步骤
确认合同与服务
确认每个货主使用的承运商、承运商客户编号、配送服务、发件人信息及面单纸张。
梳理业务流程
完成字段映射，并明确订单拆包、配送方式选择、打印状态及运单号回写规则。
开发 API
准备 API 密钥，为每个包裹分配唯一管理编号，并实现提交、状态查询、结果保存和错误展示。
免费验证 100 张面单
使用实际承运商合同、配送服务、纸张和打印机，验证正常生成、输入错误、取消、重印与重新生成。
开始正式运行
确认 Webhook、未完成任务巡检、错误告警和每日结果核对后，再逐步切换正式业务。
RESPONSIBILITY
API 集成后的职责划分
配送规则和现场作业状态由您的系统管理，ShippSyS 负责不同承运商的数据转换、面单生成与结果返回。
配送规则
您的系统
根据订单条件和仓库规则选择承运商及配送服务
ShippSyS
校验指定承运商和配送服务是否可用
生成面单
您的系统
为收件信息和包裹数据添加唯一管理编号并提交
ShippSyS
转换为承运商格式，并返回 PDF、运单号和错误信息
打印与发货后
您的系统
管理打印、贴单、复核、交接等现场作业状态
ShippSyS
提供生成结果及可用的查询、取消和重新生成操作
API CAPABILITIES
通过统一 API 提供面单生成前后的必要功能
虽然不同承运商和配送服务支持的功能有所差异，但可通过统一接口处理数据确认、异步生成、结果获取和运维操作。
提交前检查
- 获取承运商与可用功能
- 地址规范化
- 预先校验面单数据
提交与生成
- 批量接收多条面单数据
- 转换为各承运商所需格式
- 异步生成面单
获取结果
- 确认处理状态和错误
- 获取 PDF 和运单号
- 查询配送跟踪信息
运维与重新处理
- 重新生成、删除及打印指令
- 通过 Webhook 通知结果
- 查询请求和通知历史
OPERATIONS
API 集成还需考虑仓库现场的异常
除正常请求外，面单 API 的业务流程还需妥善处理包裹变化、输入错误、超时、取消和通知失败。
分别管理订单与包裹
一张订单可能拆成多个包裹，一个包裹也可能因重新生成而更换运单号。应在订单号之外保留包裹级唯一管理编号，并记录当前有效运单号。
防止重复生成
发生超时时，不要直接将请求认定为失败并重复提交；应先使用管理编号查询结果，确认未受理后再重新提交。
将错误返回给操作人员
邮编、地址、电话和配送服务等错误，应显示在仓库人员可以判断并修改的位置，而不是只保留在 API 日志中。
区分生成、打印和贴单
PDF 已经生成，不代表面单已经打印并贴到商品上。系统中的生成状态与仓库现场的作业状态需要分别管理。
保留取消和重新生成记录
区分重印同一 PDF 与修改配送条件后重新生成；旧运单号应标记为不可继续使用，同时记录操作人员、原因和处理时间。
避免遗漏异步结果
除 Webhook 外，还应通过 API 重新查询长时间未完成的数据，并监控通知重发及签名验证结果。
可用操作、必填字段和取消方法因承运商及配送服务而异。开发前请查看各承运商支持功能，并使用实际合同、纸张和打印机进行验证。
FAQ
评估和开发 API 前，需要确认这些问题
集中说明承运商合同、100 张免费面单、开发准备和正式运行中的常见问题。
使用 API 前需要与承运商签约吗？
原则上需要。除了与所用承运商签约，还应准备生成面单所需的承运商客户编号和连接信息。具体资料因承运商和配送服务而异。
支持哪些承运商和配送服务？
目前支持佐川急便、雅玛多运输、西浓运输及日本邮政 Click Post 等。服务、字段和可用操作因承运商而异，请通过承运商支持功能确认最新信息。
免费试用包含多少张面单，可以验证什么？
免费试用包含 100 张面单，可验证 API 请求、PDF 生成、实际纸张打印，以及运单号和处理结果回传。建议使用正式运行时采用的承运商合同、配送服务和打印环境。
这100 张免费面单是在沙盒环境中生成吗？
不是。目前没有独立沙盒环境，试用请求会进入实际面单生成流程。测试前请确定测试数据、面单生成后的取消或废弃方法以及内部测试负责人，避免误用于正式发货。
开发前需要准备哪些信息？
请确认承运商和配送服务、合同信息、面单纸张、打印机、发件人、收件人、商品名称等输入字段，以及运单号保存位置。多货主业务还需要明确切换承运商合同信息的单位。
如何获取面单处理结果？
可通过 API 查询处理状态，并在完成后获取面单 PDF、运单号和错误信息。即使使用 Webhook，也建议保留重新查询未收到通知数据的机制。
如何防止同一发货数据重复生成面单？
API 对接时，应为每条发货数据设置唯一管理编号，并能够查询该编号的受理及处理结果。发生超时时，确认请求尚未受理后再重新提交，从而避免重复生成面单。
修改收件地址后重新生成面单，运单号会如何处理？
在上游系统修改内容并重新提交后，系统会生成新的面单和运单号。新运单号将通过 API 或相应对接功能回传并更新至上游系统。重新生成的面单会计入面单生成数量。
如何确认 API 费用？
基本费用及按面单数量计算的费用请查看价格页面。集成开发和运行条件可在了解现有系统结构后另行说明。
可以咨询开发和上线方法吗？
可以。请提供正在使用的 WMS、OMS 或 ERP、承运商、月度面单量、打印环境和当前发货流程；我们会结合 API 是否适用，说明集成范围和上线步骤。
SHIPPSYS DEVELOPERS
从接口文档到首个面单请求
开发者网站提供认证、请求与响应、承运商字段、错误处理、Webhook 和 OpenAPI 规范，并提供 cURL、JavaScript、Python 与 PHP 示例，便于开发人员直接核对实现方式。
QUICKSTART首次 API 请求查看认证至结果确认流程 →OPENAPIAPI Reference查看端点和规格 →CAPABILITIES承运商与支持功能查看支持字段与限制 →GUIDEWebhook查看结果通知和签名验证 →
LEGACY API DOCUMENTATION
查看旧版 API 文档使用旧版 API 的客户
现有系统请通过旧版 API 文档确认对接规格；新项目建议使用上述 ShippSyS 面单 API。
免费试用注意事项：目前没有独立沙盒环境。免费试用期间发送到 API 的内容也会作为实际面单生成任务处理。