Marico's space

最近折腾了电商网站的物流对接，踩了几个坑，这篇把 Shiprocket API（应用程序接口）集成到 Node.js 和 React 项目里的完整流程说清楚。重点不是简单跑通一个接口，而是把认证、发货、物流轨迹和 Webhook（Webhook 回调）这些容易掉链子的环节一起处理好。

订单量起来之后，物流处理很容易变成瓶颈。创建订单之后，还要手动处理发货、生成面单、分配快递公司、跟踪包裹，每一步都离不开复制粘贴和表格核对。

Shiprocket API 提供了一套与物流相关的接口，可以把创建运单、分配快递、生成面单、查询物流轨迹等能力直接接入电商平台。

下面用一个 React.js 前端 + Node.js/Express 后端 演示集成思路。React 只调用自己的后端，Shiprocket 的认证信息和访问令牌全部留在服务端。

Shiprocket API 是什么

Shiprocket 提供了一组面向物流业务的接口，电商开发者可以用它完成运单创建、快递公司分配、物流面单生成以及物流状态查询。

接入之后，线上商城的订单数据可以直接进入物流流程，不需要让用户手工完成每个环节。

准备工作

开始之前，需要准备下面这些内容：

• 掌握基本的 JavaScript 和 REST API（表述性状态传递应用程序接口）知识
• 安装 Node.js 和 npm（Node.js 包管理器）
• 一个可运行的 React.js 应用
• 一个 Node.js/Express 后端项目
• 一个拥有 API 访问权限的 Shiprocket 账号
• 对应的 Shiprocket API 凭证

特别注意：API 凭证必须放在后端。不要把认证信息或私有令牌写进 React 前端代码，否则构建产物一旦被下载，密钥就可能直接暴露。

第 1 步：搭建 Node.js 后端

创建项目目录并安装依赖：

mkdir shiprocket-integration
cd shiprocket-integration
npm init -y
npm install express axios dotenv cors

新建 index.js，配置 Express 服务：

const express = require("express");
const axios = require("axios");
require("dotenv").config(); const app = express(); app.use(express.json()); app.get("/", (req, res) => { res.send("Shiprocket integration server is running");
}); app.listen(5000, () => { console.log("Server running on port 5000");
});

至此，一个负责电商应用与 Shiprocket 通信的基础后端就搭好了。

第 2 步：配置环境变量

在后端项目中创建 .env 文件：

SHIPROCKET_EMAIL=your_registered_email
SHIPROCKET_PASSWORD=your_password
PORT=5000

同时把 .env 加进 .gitignore，避免凭证被提交到代码仓库。

生产环境不要只依赖本地文件，应该使用可靠的密钥管理服务，并遵循所在团队的凭证处理规范。

第 3 步：认证 Shiprocket

后端在发起有权限的 API 请求之前，需要先拿到认证令牌。

下面是用 Axios 发起登录请求的示例：

async function getShiprocketToken() { const response = await axios.post( "https://apiv2.shiprocket.in/v1/external/auth/login", { email: process.env.SHIPROCKET_EMAIL, password: process.env.SHIPROCKET_PASSWORD, } ); return response.data.token;
}

这个函数会把配置好的账号密码发送到认证接口，再从响应中取出令牌。

实际业务里还要处理认证失败、令牌过期和凭证错误。Shiprocket 的认证要求可能会调整，接入前应以最新的 Shiprocket API 文档为准。

第 4 步：创建运单

认证完成后，后端就可以把订单信息发送给 Shiprocket。

一个典型的运单流程通常需要下面这些数据：

• 客户姓名和联系方式
• 收货地址和 PIN code（印度邮政编码）
• 订单 ID 和下单日期
• 商品信息、数量和价格
• 包裹尺寸和重量
• 支付信息和发货信息

可以先写一个 Express 路由把流程跑起来：

app.post("/api/shipments", async (req, res) => { try { const token = await getShiprocketToken(); // Validate and prepare the order data before // sending it to the Shiprocket API. const orderData = req.body; const response = await axios.post( "https://apiv2.shiprocket.in/v1/external/orders/create/adhoc", orderData, { headers: { Authorization: `Bearer ${token}`, "Content-Type": "application/json", }, } ); res.status(201).json(response.data); } catch (error) { console.error( "Shipment creation failed:", error.response?.data || error.message ); res.status(500).json({ message: "Unable to create shipment", }); }
});

这个路由放到生产环境之前：必须校验客户端请求，按照 Shiprocket 当前的 API 数据结构构造请求体，完成用户身份认证，并确认订单确实属于当前应用。不要把客户端传过来的任意订单数据不加判断地转发给物流平台。

第 5 步：连接 React 前端

React 应用调用自己的后端接口，触发运单创建：

async function createShipment(orderData) { const response = await fetch( "http://localhost:5000/api/shipments", { method: "POST", headers: { "Content-Type": "application/json", }, body: JSON.stringify(orderData), } ); if (!response.ok) { throw new Error("Failed to create shipment"); } return response.json();
}

订单校验通过后，可以在结账流程或订单管理流程中调用这个函数。

正式部署时，需要换成正确的后端地址，补上登录认证和权限校验，并在界面上给出明确的成功或错误提示。

第 6 步：处理快递分配和物流面单

订单或运单创建之后，通常还要支持一组后续操作：

• 查询可用快递服务
• 分配快递公司
• 生成或获取空运单（AWB，Air Waybill）
• 生成物流面单
• 预约上门揽收

这些操作通常要继续调用 API，并且是否可用会受运单状态、揽收安排、服务覆盖范围和账号配置影响。

比较稳妥的做法，是把每项操作拆成独立的后端服务或路由，并按照最新的 Shiprocket API 文档使用对应的接口和请求格式。

第 7 步：增加物流跟踪

客户需要知道订单走到哪一步了，也要能大致判断什么时候送达。

可以在电商应用中增加一个物流跟踪页面，通过后端查询 Shiprocket 的物流状态，再把页面真正需要的字段展示出来。

例如，后端可以暴露下面这样的应用接口：

app.get("/api/shipments/:shipmentId/tracking", async (req, res) => { try { // Verify the user's access to this shipment. // Retrieve tracking information through the // appropriate Shiprocket API endpoint. // Return only the relevant tracking details. res.json({ message: "Implement tracking using the current Shiprocket API", shipmentId: req.params.shipmentId, }); } catch (error) { res.status(500).json({ message: "Unable to retrieve tracking information", }); }
});

这只是路由结构示例，不是完整的物流跟踪实现。需要把占位逻辑替换成文档中规定的物流查询接口，并传入要求的参数。

第 8 步：处理 Webhook 和运单状态更新

反复轮询外部 API，不一定是更新运单状态最高效的方式。

如果当前 Shiprocket 账号和 API 配置支持 Webhook，应用可以通过它接收运单相关的事件通知。

一个可靠的 Webhook 实现应该做到：

• 按照服务商支持的验证机制校验事件来源
• 更新数据库里对应的运单记录
• 安全处理重复事件，避免重复执行
• 记录失败日志，并在合适的情况下支持重试
• 避免在日志中暴露客户敏感信息

Webhook 的配置方式和验证要求同样可能变化，落地前需要查看当前 Shiprocket 文档。

第 9 步：上线前完成测试

部署之前，要把完整业务链路跑一遍，而不是只验证“接口能返回 200”。

• 检查认证和令牌处理逻辑
• 分别测试合法与非法的订单数据
• 检查快递服务覆盖范围和运单创建结果
• 测试面单生成与物流跟踪
• 处理 API 错误、超时和速率限制
• 确认重复请求不会创建出多余的运单
• 保护客户信息和 API 凭证

另外，关键物流操作还应该配套结构化日志、监控、重试策略和自动化测试。

集成 Shiprocket API 能带来什么

把物流能力接入电商网站后，企业通常能获得几方面收益：

自动化物流流程：减少处理订单时重复、琐碎的手工操作。

提高订单状态透明度：让客户和客服都能更方便地查看物流信息。

降低运营成本：在统一的应用中管理关键的物流操作。

改善客户体验：为用户提供更连贯的下单、发货和物流跟踪流程。

总结

将 Shiprocket 接入电商网站，可以简化从订单处理到物流跟踪的一系列关键流程。

React.js 前端加 Node.js 后端，是落地这类集成的一套实用架构。凭证留在服务端、订单数据严格校验、API 异常妥善处理，再跟上最新的 Shiprocket 文档，才能把物流体验做得稳定。

Scode Software Solutions 目前提供 Web、移动端、云端和 AI（人工智能）领域的软件解决方案，帮助企业优化运营流程并构建实用的数字产品。

如果正在规划电商应用，或者需要定制物流集成，那么先把 API 工作流设计清楚，往往就是提升运营效率最直接的一步。