接 Brightpearl：拉订单进来，查库存

先在 Brightpearl 开发者门户的您的应用里拿到 app_ref 和 dev_ref，再对您的账号走 OAuth 授权拿到 access token，并从令牌响应里拿到 datacenter 要用的 api_domain，把五项全填进 Integration，测试、配 Mapping、激活——销售订单拉进来，库存可查。

Brightpearl 连接器把 Brightpearl 里的销售订单拉进本系统，还能查 Brightpearl 里的产品库存可用量。它是从 Brightpearl 读数据：不从 Brightpearl 拉客户，也不把库存或任何其他变化推回 Brightpearl。这里顺序很重要——datacenter 的值不是从列表里选的，它是 OAuth 令牌响应里以 api_domain 返回的，所以要先走完授权、再回来填连接。

前置条件#

• 一个 Brightpearl 账号，以及它的账户代码：就是您 Brightpearl 网址的子域名部分。例如 acme.brightpearl.com 里的账户代码就是 acme。
• 能访问 developer.brightpearl.com 的 Brightpearl 开发者门户，且那里有一个给本集成用的应用——您需要它的应用引用名和您的开发者引用名。
• 您能对该 Brightpearl 账号走完 OAuth2 Authorization Code 授权流程，授权入口见拿凭证一节给出的地址。
• 您理解 datacenter 的反直觉顺序：它在授权之后、从令牌响应里以 api_domain 拿到。不要猜，也不要把账号子域名填到那里。

拿凭证#

1. 先记下账户代码：您 Brightpearl 网址的子域名部分，例如 acme.brightpearl.com 里的 acme。
2. 打开 developer.brightpearl.com 的 Brightpearl 开发者门户，打开您的应用，记下它的应用引用名。这就是 app_ref 的值；同一个应用引用名在 OAuth 流程里也用作 client_id。
3. 同时记下您的开发者引用名。这就是 dev_ref 的值——每次请求都会以 brightpearl-dev-ref 头发送它，正如 app_ref 以 brightpearl-app-ref 头发送一样。
4. 从 https://oauth.brightpearl.com/authorize/{account} 对您的账号发起 OAuth 授权——把 {account} 换成您自己的账户代码——走完 Authorization Code Grant 流程，拿到 access token。
5. 在同一次令牌响应里记下两个值：access_token 本身，以及 api_domain 的值。api_domain，例如 use1.brightpearlconnect.com，正是填进 datacenter 字段的内容——从响应里复制，不要自己拼。

填进 Integration#

1. 打开 Integration → 连接器市场 → Brightpearl → 新建连接。下面五个字段全部必填。
2. account——必填，Brightpearl 账户代码：您 Brightpearl 网址的子域名部分，例如 acme。
3. datacenter——必填，API 数据中心域名：填 OAuth 令牌响应里返回的 api_domain，例如 use1.brightpearlconnect.com。不要把账号子域名填到这里。
4. app_ref——必填，应用引用名：developer.brightpearl.com 的 Brightpearl 开发者门户里您的应用的应用引用名。
5. dev_ref——必填，开发者引用名：您的 Brightpearl 开发者引用名。每次请求都会以 brightpearl-dev-ref 头发送它。
6. access_token——必填，OAuth2 访问令牌：粘贴从 Authorization Code Grant 流程拿到的 access token。这是密码类型字段，作为秘密保存。

测试连接#

点测试连接。测试先逐项检查五个字段——account、datacenter、app_ref、dev_ref、access_token——任一缺失都会停下并报告缺失字段、不发请求。否则它会带三个头去读订单状态参考数据：Authorization: Bearer 加您的令牌、brightpearl-dev-ref、brightpearl-app-ref，地址为 GET https://{datacenter}/public-api/{account}/order-service/order-status，其中 {datacenter} 和 {account} 换成您自己的值。这是 Brightpearl 里最轻的只读校验。返回 200 表示连接通。返回 401 指向令牌问题。返回 403 指向权限问题。测试 12 秒超时。

配 Mapping / 选模板#

选 Brightpearl 标准 Mapping。销售订单先经 Brightpearl 订单服务搜索找到、再完整读回，库存查询从仓库服务读产品可用量。测试通过后先拉一次，把一个真实订单对照核对——订单号、订单上显示的客户名、明细行与数量——再拿一个产品的可用量和 Brightpearl 里显示的对一遍，确认后再激活。如果您订单上的某个字段不同，在 Mapping 里调整那个字段，不要去改 Brightpearl 里的记录。

激活#

激活后，连接按您设的频率把 Brightpearl 的销售订单拉进本系统，库存查询从 Brightpearl 读当前产品可用量。先在 运行监控 / 日志里盯头几次拉取、和 Brightpearl 对照无误，再放手跑。当 access token 失效时，对同一账号重新走一遍 OAuth 授权，然后用新令牌响应里的值把 access_token 和 datacenter 一起更新。

这个连接不做的事：不从 Brightpearl 拉客户，也不把库存、订单状态或履约结果推回 Brightpearl。这些事请继续在 Brightpearl 里处理，或在实际作业的系统里处理。

常见问题#

测试报 401——令牌有问题

Brightpearl 没有接受测试带去的 access token。access_token 字段里的令牌填错、没粘全，或不是对本账号经 Authorization Code Grant 流程拿到的——测试以 Bearer 令牌方式读订单状态参考数据，Brightpearl 接受不了的令牌会先在这里失败。

从 https://oauth.brightpearl.com/authorize/{account} 用您自己的账户代码重新发起授权，走完 Authorization Code Grant 流程，把新的 access token 完整粘贴进去，并从同一次令牌响应里按 api_domain 重新复制 datacenter。保存后重新测试。

测试报 403——权限问题

这和 401 不同：令牌被接受了，但它背后的应用或账号不被允许读测试用的订单状态参考数据。用同一个应用、同一套访问再走授权，仍会返回 403。

在 Brightpearl 里检查 app_ref 对应的应用对本账号被允许访问什么，并核对 dev_ref 与 app_ref 是与令牌配套的那一对。给该应用放开本连接所需的读取权限，或改用一个已有权限的应用，然后重新授权，用新令牌响应更新字段，再重新测试。

测试没发请求就停下，并报告缺失字段

五个必填字段——account、datacenter、app_ref、dev_ref、access_token——里有一个是空的。测试先查全五项，因为请求地址需要 account 和 datacenter，请求头需要 app_ref、dev_ref 和令牌。

把缺失字段从它自己的来源补齐：account 来自您的 Brightpearl 网址，app_ref 和 dev_ref 来自开发者门户，access_token 和 datacenter 来自 OAuth 令牌响应。保存后重新测试。

我把账号子域名填成了 datacenter，测试失败

account 和 datacenter 是两个形态不同的值。account 是您 Brightpearl 网址的子域名，例如 acme。datacenter 是 OAuth 令牌响应里返回的 api_domain，形态如 use1.brightpearlconnect.com。把 account 的值填进 datacenter 字段，测试请求就会发到错误的地址。

回到您 OAuth 授权的令牌响应，把 api_domain 的值原样复制进 datacenter 字段，account 只留子域名，保存后重新测试。

连接成功，但没有销售订单拉进来

连接是通的——测试已成功读到订单状态参考数据——只是没有新单可拉：Brightpearl 在拉单范围内、本账号下没有新的销售订单，或那些订单在与连接里账户代码不同的另一个账号下。

在 Brightpearl 里、在与连接相同的账户代码下新建或确认一个销售订单，再手动拉一次，在预览或 运行监控 / 日志里确认订单出现。

查库存时某个产品没有可用量返回

连接能读 Brightpearl 的产品可用量，但那个产品没有可读的对应可用量记录，或 Mapping 里的产品编码与 Brightpearl 里的产品对不上。测试能通过，单个产品仍可能没有可返回的可用量。

先在 Brightpearl 里检查该产品及其可用量，再检查 Mapping 里该项的产品编码，改成与 Brightpearl 一致，然后只对该产品重新查一次库存。