接 Cin7：拉订单与客户进来，查库存
在 go.cin7.com 的 Cin7 Omni 里打开一个 API 连接，记下它的用户名和密码，只把这两个字段填进 Integration，测试、配 Mapping、激活——销售订单与客户拉进来，库存可查。
Cin7 连接器把 Cin7 Omni 里的销售订单与客户拉进本系统，还能查 Cin7 里的库存数量，包括可用量与在手量。它是从 Cin7 读数据：不把库存变化推回 Cin7，也不把订单或客户回写 Cin7。没有地址字段要填——连接器固定使用 Cin7 官方 API 地址。一个连接对应 Cin7 里一个 API 连接。
前置条件#
- 一个能在 go.cin7.com 登录的 Cin7 Omni 账号。
- 在 Cin7 里有打开或新建 API 连接的权限。本集成的用户名和密码就来自这个 API 连接。
- 开始前最重要的一点：API 用户名和 API 密码不是您的 Cin7 登录账号。填登录 Cin7 用的邮箱和密码是连不上的。
- 规划拉取频率时留意 Cin7 API 限流：每秒 3 次、每分钟 60 次、每天 5,000 次请求。
拿凭证#
- 在 go.cin7.com 登录 Cin7 Omni。
- 打开 API 连接区域，打开要给本集成用的那个 API 连接，或新建一个。
- 记下那个 API 连接的用户名。这个用户名是为 API 连接生成的、用于 Basic 认证——不是您的 Cin7 登录名。
- 记下同一个 API 连接上设置的 API 密码。用户名和密码必须来自同一个 API 连接——不要混用两个不同连接的值。
填进 Integration#
- 打开 Integration → 连接器市场 → Cin7 → 新建连接。
- username——必填，Cin7 API 用户名：填 Cin7 里那个 API 连接的用户名，字段的提示文字是 API username。
- password——必填，Cin7 API 密码：填同一个 API 连接上设置的 API 密码。这是密码类型字段，作为秘密保存。
- 没有其他要填的了。本连接没有地址字段：它固定连接官方地址 https://api.cin7.com/api，不用再找改地址的地方。
测试连接#
点测试连接。如果 username 或 password 缺失，测试会先停下并报告缺失字段、不发请求，因为 Basic 认证两个值缺一不可。否则测试会带 Basic 认证去读分支列表：GET https://api.cin7.com/api/v1/Branches——这是 Cin7 里最轻的读取。返回 200 表示连接通。返回 401 表示凭证无效。返回 403 表示凭证被接受、但这个 API 连接没有该资源的权限——401 和 403 的修法不同，改任何值之前先看清代码。测试 12 秒超时。
配 Mapping / 选模板#
选 Cin7 标准 Mapping。销售订单读 Cin7 的销售订单数据，客户读 Cin7 的联系人数据，库存查询读 Cin7 的库存数据。测试通过后先拉一次，把一个真实订单对照核对——订单号、客户、明细行与数量——再核对一条客户记录，并拿一个产品的数量和 Cin7 里显示的对一遍，确认后再激活。如果您订单上的某个字段不同，在 Mapping 里调整那个字段，不要去改 Cin7 里的记录。
激活#
激活后，连接按您设的频率把 Cin7 的销售订单与客户拉进本系统——注意 Cin7 限流：每秒 3 次、每分钟 60 次、每天 5,000 次请求——库存查询从 Cin7 读当前数量。先在 运行监控 / 日志里盯头几次拉取、和 Cin7 对照无误，再放手跑。
这个连接不做的事：不把库存变化推回 Cin7，也不把订单、客户或履约结果回写 Cin7。这些事请继续在 Cin7 里处理，或在实际作业的系统里处理。
常见问题#
测试报 401——凭证无效
Cin7 拒绝了 Basic 认证。用户名或密码与 Cin7 里任何一个 API 连接都对不上——最常见的原因是填成了 Cin7 登录邮箱和密码，或用户名与密码来自两个不同的 API 连接。
在 go.cin7.com 的 Cin7 Omni 里打开那个 API 连接，把它的用户名原样复制进 username 字段，把同一连接上的 API 密码设置好或复制进 password 字段，保存后重新测试。不要用您的 Cin7 登录密码。
测试报 403——这个 API 连接没有该资源的权限
这和 401 不同：Cin7 接受了凭证，但这个 API 连接不被允许读测试用的分支列表。再改密码也修不好 403。
在 Cin7 里检查这个 API 连接被授予的访问范围，放开它读本连接所需资源的权限，或改用一个已有该权限的 API 连接。用户名和密码仍用同一个连接的一对，保存后重新测试。
测试没发请求就停下，并报告缺失字段
username 或 password 有空缺。测试做 Basic 认证需要两个值都齐，所以它会停下来，而不是发一个注定被 Cin7 拒绝的请求。
把两个字段都用 Cin7 里同一个 API 连接的值补齐——用户名来自该连接，密码是同一连接上设置的密码——保存后重新测试。
我填的是 Cin7 登录账号，但连不上
登录账号和 API 连接凭证在 Cin7 里是两回事。本连接只用 API 连接的用户名和密码认证，所以登录账号本身完全正确，在这里仍然会失败。
到 Cin7 Omni 的 go.cin7.com → API 连接，打开或新建一个 API 连接，把它的用户名和 API 密码填进 Integration，替代登录信息，然后重新测试。
连接成功，但没有销售订单拉进来
连接是通的——测试已成功读到分支列表——只是没有新单可拉：Cin7 在拉单范围内没有新的销售订单，或那里的记录不是销售订单。
在 Cin7 里新建或确认一个销售订单，再手动拉一次，在预览或 运行监控 / 日志里确认订单出现。拉取频率保持在上文的限流范围内。
查库存时某个产品没有数量返回
连接能读 Cin7 的库存，但那个产品没有可读的对应库存记录，或 Mapping 里的产品编码与 Cin7 里的产品对不上。测试能通过，单个产品仍可能没有可返回的数量。
先在 Cin7 里检查该产品及其库存记录，再检查 Mapping 里该项的产品编码，改成与 Cin7 一致，然后只对该产品重新查一次库存。