集成与 API
OptiRoutes 可以与您现有的系统对接。配送单可以来自 Excel 或 CSV 文件、FTP 或 SFTP，或通过安全的文件 API 导入；已签收的送货单、路线导出和报告也通过同样的方式回传。报表 API 为您的 BI 工具提供数据，Web 地址则可以实时接收配送报告和路线导出。
更新于:
OptiRoutes 提供哪些集成？
| 需求 | OptiRoutes 的实现方式 |
|---|---|
| 载入当天的配送单 | Excel 或 CSV 上传，或从 FTP、SFTP 或文件 API 自动载入，支持 CSV、JSON 或定宽 TXT 格式。 |
| 获取已签收的 POD | 按天或按配送单调用文件 API，或每天下载一个 ZIP；副本通过电子邮件发送。 |
| 将路线发送到您的系统 | 路线可导出为 CSV、XLSX、XML、JSON 或 TXT，保存为文件，或发送到您的 FTP、公司文件夹或某个 Web 地址。 |
| 向 BI 或 ERP 提供报表 | 报表 API：配送单、路线、司机、客户、POD 以及每日配送汇总。 |
| 对每一次配送作出响应 | 一个配送报告地址，实时接收每一份上报。 |
| 支付服务费用 | 通过 Stripe Checkout 进行预付充值和自动充值。 |
从文件、FTP 或 SFTP 载入配送单
最简单的集成，就是您的系统已经在导出的文件。在配送单页面上，载入配送单可以读取 Excel 或 CSV 文件；您只需把每个系统字段 — 地址、客户名称、配送单号、数量等 — 与您的列名映射一次，之后的每个文件都会以同样的方式载入。对于定宽 TXT 文件，则填写字符位置而不是列名。可以通过备注中的标记词跳过某些行，第二个标记词可以替换地址；您还可以决定已存在的配送单号是更新还是作为新配送单添加。
如果希望无需人工操作，可以在设置中选择一种自动载入方式：
- OptiRoutes 文件服务器 — 您的系统把以日期命名的每日文件，放入贵公司在 FTP 服务器或加密 SFTP 服务器上的文件夹。
- 您自己的 FTP 服务器 — OptiRoutes 使用您提供的用户连接，并载入以今天日期命名的文件或最近更新的文件。
- 自动导入与导出 — 配送单自动载入，路线也会自动规划，无需任何点击。
- 文件 API — 您的软件通过 HTTPS 上传配送单文件，详见下文。
在客户页面上，一份包含客户编号、名称、地址、停靠时长以及营业开始和结束时间的 Excel 或 CSV 文件，可以创建或更新客户及其时间窗。
文件 API：配送单传入，POD 和报告传出
OptiRoutes 中的每家公司都有自己的专属文件夹：载入的配送单、带照片和签名的已签收送货单、路线导出以及日终报告。文件 API 让您的系统可以通过 HTTPS 直接读写该文件夹，中间无需 FTP 服务器。公司经理可以在设置 → API 与文件中在 FTP 和 API 之间切换，并在那里创建密钥 — 无需联系技术支持，新公司默认使用 API。
| 文件夹 | 内容 | 由谁写入 |
|---|---|---|
| orders_files/ | 每日配送单文件，以及路线导出文件。 | 您（配送单）、OptiRoutes（导出文件） |
| pod/YYYY/MM/DD/ | 当天已签收的 POD：已签收的 PDF、签名和照片。 | OptiRoutes |
| pod/ | 待在司机 App 中签收的原始送货单，每个配送单号一个 PDF。 | 您 |
| reports/YYYY/MM/ | 日终报告和退货报告。 | OptiRoutes |
| podBaseFile/ | POD 基础表单。 | 您 |
| inbox/ | 一个自由文件夹，用于存放您想要移交的文件。 | 您 |
API 调用涵盖：验证密钥、列出文件夹内容、下载、上传（每个文件最大 50 MB）以及删除您上传的文件，按配送单和类型列出某一天的 POD 文件，以及将某一天的所有 POD 文件打包为一个 ZIP 下载。指南附有 Python、C# 和 Node.js 代码示例，以及一个能让您服务器上的文件夹与公司文件夹保持同步的 PowerShell 脚本 — 习惯使用 FTP 的团队可以继续按原来的方式工作。请阅读文件 API 指南。
API 密钥如何保障安全？
- 最小权限 — 每个密钥只授予所需的权限：仅限已签收的 POD、读取所有文件，或上传配送单和收件箱文件。
- 允许的地址 — 密钥可以限制为仅允许您服务器的固定 IP 地址访问。
- 到期与轮换 — 密钥可以设置为若干天后到期；创建新密钥、完成切换，再撤销旧密钥，全程无需停机。
- 即时撤销 — 被撤销的密钥会在 30 秒内失效。
- 审计 — 每一次调用都会记录时间、地址、文件和响应，并向经理展示。
- 安全存储 — OptiRoutes 只保存每个密钥的 SHA-256 指纹；连接采用 TLS 1.2 或更高版本的 HTTPS，每个密钥只能访问其所属公司的文件夹。
限制：每个密钥每分钟 300 次请求，每个文件 50 MB，每家公司 20 个有效密钥，单次文件夹列表最多 5,000 个条目。
报表与推送 API
对于报表工具和 ERP 连接器，位于 api-users.optiroutes.com 的另一个 API 会以报表形式提供贵公司的数据，并接收推送的数据。由 OptiRoutes 为贵公司签发的一个地址和一个令牌，即可覆盖所有调用。在文档页面上粘贴您的令牌，即可查看哪些报表对您开放，以及您账户的列映射：阅读 API 文档。
| 报表 | 返回内容 |
|---|---|
| orders | 配送单和配送情况，附路线和司机。 |
| routes | 路线，附司机和停靠点数量。 |
| drivers | 司机数据。 |
| customers | 客户数据和地址。 |
| pod | 配送凭证文件。 |
| delivery-summary | 按状态汇总的每日摘要。 |
另有两个推送调用方向相反：推送配送单会写入当天的配送单文件并启动自动载入；推送司机、配送线和车辆则会像车队文件一样替换整个车队。由于推送的司机列表被视为完整车队，请务必每次发送全部司机，而不只是发生变化的司机。
路线导出与 Webhook
路线导出会将已标记的路线写入 CSV、XLSX、XML、JSON 或定宽 TXT 文件。列设置表决定导出哪些字段以及使用什么标题，还可以加入配送单文件中的原始列；开启商品管理后，第二个文件会列出每一个商品。导出文件可以保存到您的电脑、您的 FTP 服务器或公司文件夹；选择 JSON 时，还可以发送到某个 Web 地址，发送失败时系统会再重试一次。
如需实时获取每一次配送，请在司机 App 设置中填写配送报告地址：司机的每一份配送报告也会同时发送到该地址，您的其他系统便会自动更新。
电子邮件、支付、地图与消息
- 电子邮件 — 已签收的送货单通过 Google 应用专用密码，从您自己的 Gmail 账户发出；日终托盘报告等报告发送到您的报告邮箱；收款台还会向付款客户发送收据，向司机发送交款确认。
- 支付 — 充值在安全的 Stripe 支付页面完成，可选择保存银行卡用于自动充值。
- 地址与地图 — 地址从 Google 建议中选择，并在规划前于地图上完成核实。
- 导航 — 司机 App 会把每个停靠点按地址或精确坐标交给 Waze，iPhone 上也可以交给 Apple Maps。
- SMS 与 WhatsApp — 向客户发送到达消息和跟踪链接，向管理人员发送提醒，向分包商发送配送线，并通过 WhatsApp 向司机发送路线图片。
常见问题
OptiRoutes 能从我们的 ERP 自动载入配送单吗？
能。您的 ERP 可以把每日文件放到 OptiRoutes 的 FTP 或 SFTP 服务器、您自己的 FTP 服务器上，或通过文件 API 上传，OptiRoutes 会自动载入。
如何把已签收的 POD 导入我们的系统？
通过文件 API：列出并下载某一天的 POD 文件，或将其全部打包为一个 ZIP 下载。系统还会按您的分发规则通过电子邮件发送一份副本。
文件 API 的密钥由谁创建？
由公司经理在“设置 → API 与文件”中创建。密钥可设置权限、可选的允许地址和到期时间，并可随时撤销。
有用于报表的 API 吗？
有。报表 API 使用 OptiRoutes 签发的令牌，返回配送单、路线、司机、客户、POD 以及每日配送汇总。
路线可以导出为哪些文件格式？
CSV、XLSX、XML、JSON 和定宽 TXT，列和标题均可自行选择。