接 Fishbowl：拉销售单与采购单进来，查库存

把 Integration 指向您自有 Fishbowl Server 的地址，用 Fishbowl 用户名与密码登录，在 Fishbowl 客户端的 Settings → Integrated Apps 里把集成应用 Approve 一次，再测试、配 Mapping、激活。

Fishbowl 连接器连的是您自己运行的 Fishbowl Server，把 Fishbowl Advanced 里的销售单与采购单拉进本系统，还能按料号查库存。范围就是这些：不拉也不推客户，不把库存或任何其他记录推回 Fishbowl。因为服务器是您自己的，它必须能被本系统连到——只在局域网内应答、没有公网或 VPN 通路的服务器，是连不上的。

前置条件#

• 一台正在运行的 Fishbowl Server（Fishbowl Advanced），且其地址能被本系统连到。服务器地址必须能通过公网或 VPN 到达——如果地址只在局域网内能用，先打通通路；通路不通，填什么凭证都连不上。
• 服务器的 Web 地址与端口，例如 http://192.168.1.10:80。80 是常用 Web 端口；如果该机器上 80 已被占用，Fishbowl 改用 2456——先确认您的服务器在哪个端口应答。
• 一个用来登录的 Fishbowl 用户名与密码。建议在 Fishbowl 里为本连接建一个专用集成账号，登录记录容易辨认，密码也能与个人账号分开管理。
• 能打开 Fishbowl 客户端，以便首次登录后在 Settings → Integrated Apps 里 Approve 这个集成应用。少了这一次批准，其他值全对，测试也会报 403。

拿凭证#

1. Fishbowl 没有云端门户、也没有要生成的 Key。凭证就是连接登录用的那个 Fishbowl 用户名与密码——还没有的话，先在 Fishbowl 里建一个专用集成用户。
2. 把 Fishbowl Server 地址按填写步骤需要的形态记下来，例如 http://192.168.1.10:80——就是服务器应答的地址与端口；该机器上 80 被占用时用 2456 代替 80。
3. 现在就定好集成应用名——没有在用的其他名字就用 Docklify Integration。这个名字就是首次登录后在 Fishbowl 客户端 Settings → Integrated Apps 里出现的名字，您要在那里 Approve 的就是它。
4. 首次配置先不管 App ID。App ID 只有在管理员给已批准的应用在 Integrated Apps 里分配了数字 ID 时才存在——还没分配时，没有可找的东西。

填进 Integration#

1. 打开 Integration → 连接器市场 → Fishbowl → 新建连接。
2. server_url——必填，Fishbowl 服务器地址：填您 Fishbowl Server 的地址，例如 http://192.168.1.10:80。该机器上 80 被占用时用 2456 代替 80。这个地址必须能被本系统通过公网或 VPN 连到。
3. username——必填，Fishbowl 用户名：填集成用 Fishbowl 账号的用户名，最好是专用集成账号。
4. password——必填，Fishbowl 密码：填同一个 Fishbowl 账号的密码。这是密码类型字段，作为秘密保存。
5. app_name——必填，集成应用名：填拿凭证一步定好的名字，例如 Docklify Integration。首次登录后，这个名字会出现在 Fishbowl 客户端的 Settings → Integrated Apps 里，您在那里 Approve 它。
6. app_id——可选，应用 ID：首次配置留空。只有管理员已在 Integrated Apps 里给已批准的应用分配了数字 ID 并给到您时，才填它。
7. 然后按正确顺序做批准这一步：保存连接并先跑一次测试连接，让首次登录把应用登记进去；打开 Fishbowl 客户端 → Settings → Integrated Apps，找到您 app_name 的那条并 Approve；再回来重新测试。批准是在 Fishbowl 客户端里做的，不是在 Integration 里。

测试连接#

点测试连接。测试做的是一次真实登录：它把您的 appName、appId、username、password 发到您 Fishbowl Server 的 POST {server_url}/api/login，拿到登录 token 才算测通——结果里会显示应答的是哪台服务器。登录成功后测试会紧接着登出。server_url 缺失时，测试以 MISSING_SERVER_URL 停下；其他必填字段缺失时，以对应的缺失字段错误停下。401 表示用户名或密码被拒。403 会以 MISSING_SCOPE 返回，意思是集成应用可能还没在 Settings → Integrated Apps 里被 Approve。登录 12 秒超时。

配 Mapping / 选模板#

选 Fishbowl 标准 Mapping。它覆盖标准形态的销售单与采购单，以及按料号的库存查询。测试通过后先拉一次，把一个真实销售单对照核对——单号、明细行与数量——采购单同样核一张，再拿一个料号的库存和 Fishbowl 里显示的对一遍，确认后再激活。

激活#

激活后，连接按您设的频率登录您的 Fishbowl Server，把销售单与采购单拉进本系统，查库存时按料号读数量。先在 运行监控 / 日志里盯头几次拉取、和 Fishbowl 对照无误，再放手跑——日后服务器地址或通路有变化，记得更新 server_url 并重新测试。

这个连接不做的事：不拉也不推客户，不把库存、订单或任何其他记录推回 Fishbowl。那些记录仍在 Fishbowl 里管理；本连接只从 Fishbowl 读订单与库存。

常见问题#

测试报 403 / MISSING_SCOPE——集成应用可能还没被 Approve

在本连接里 403 只有一个专属含义：集成应用可能还没在 Fishbowl 客户端的 Settings → Integrated Apps 里被 Approve。服务器收到了登录，但您 app_name 的那个应用还没被批准，登录就不能继续。

打开 Fishbowl 客户端 → Settings → Integrated Apps，找到与您 app_name 同名的那条并 Approve。然后在 Integration 里用同样的值重新测试——其他字段都不用改。

测试报 401——用户名或密码被拒

服务器应答了、应用那关也过了，但 Fishbowl 登录本身被拒：用户名与密码这一对与那台服务器上的账号对不上，或密码多打、少打了字符。

先用同样的用户名与密码自己登录一次 Fishbowl 客户端确认能进，最好用专用集成账号。然后在 Integration 里重填 username、重粘 password，再重新测试。

测试以 MISSING_SERVER_URL 或其他缺失字段错误停下

有必填字段是空的，所以根本没尝试登录。MISSING_SERVER_URL 专指 server_url 为空；其他缺失字段错误会指出 username、password、app_name 里哪个是空的。app_id 是可选的，永远不会引起这种停下。

按填进 Integration 一节把指出的字段补上——server_url 填含端口的完整服务器地址——app_id 除非管理员已分配否则留空，保存后重新测试。

测试超时——服务器根本连不到

登录在 12 秒内没得到任何应答。自托管服务器最常见的原因是可达性：server_url 里的地址只在局域网内应答、本系统没有公网或 VPN 通路过去；或地址里的端口不是服务器应答的端口——80 与 2456 是要核对的两个。

先确认 Fishbowl Server 正在运行，并记下它应答的确切地址与端口。然后让该地址能通过公网或 VPN 从局域网外到达，把 server_url 改到完全一致，再重新测试。改用户名或密码修不了超时。

首次配置前，去哪里找 App ID？

哪里都找不到——首次配置时它通常还不存在。App ID 是管理员在应用已于 Settings → Integrated Apps 里被 Approve 之后，可能给它分配的一个数字 ID；所以在批准之前找它，是在找一个还没生成的东西。

app_id 留空，先把配置与批准做完。只有管理员后来分配了 App ID 并给到您时，才编辑连接、把那个数字填进 app_id、保存并重新测试。

连接成功，但没有客户进来、也没有任何东西写回

这是本连接的能力边界，不是故障：它拉销售单与采购单、按料号读库存。客户记录两个方向都不在范围内，任何记录都不推回 Fishbowl。

客户与库存变更请继续在 Fishbowl 里管理。本连接用来跑订单流——在 运行监控 / 日志里核对一张拉进来的销售单或采购单，即可确认连接在做它的部分。