帮助中心
吉易鸥 AIGEO · 每个功能都有详细操作指引
← 返回平台首页
← 返回帮助列表

对接验收与排错:从"同步失败"到定位原因

小鸥 API · 更新于 2026-10-15 17:10

一、按这个顺序排查,三步定位

  1. 接口在不在:浏览器打开 https://你的环境域名/api/tenant_ingest.php。返回 JSON 里的 ok:true 即为「在」;返回 404 说明我们这边文件没部署到该环境,联系吉易鸥技术;返回 500 且是 HTML,说明服务器报错,同样联系我们。
  2. Key 对不对:带 Authorization: Bearer <Key> 再打开一次,看到 auth:true 即为「对」;返回 401 说明 Key 错、或 Key 与域名不属于同一个环境(测试端与上线端是两套独立数据库,Key 不通用)。
  3. 载荷对不对:POST 一条最小数据试推,看返回的 inserted / errors。

二、常见报错对照表

你看到的真正的原因怎么解决
HTTP 400 message required同步请求打到了聊天接口——通常是「环境域名」被填成了完整接口地址(如 …/api/open_chat.php),地址被拼重成 …/open_chat.php/api/tenant_ingest.php新版已做串门容错会自动转交,无需改动即可同步成功;同时建议把环境域名改回纯域名(只填 https://i.gonglve.com.cn)
HTTP 401 invalid or missing api keyKey 没带 / 带错 / 与域名不是同一环境确认请求头 Authorization: Bearer <Key>;确认 Key 是在同一个环境生成的
HTTP 400 找不到文档数组body 里没有 docs 之类的数组字段把内容放进 {"docs":[ … ]};数组字段名也接受 articles / items / data / list / contents
inserted 少于 total,errors 有内容部分文档缺标题与正文,或触发了「知识库文档数」额度按 errors 逐条修;额度不足请让吉易鸥运营把贵司租户额度调大
HTTP 405 method not allowed用了 GET 去推送(GET 只做自检)推送请用 POST;确认「接口在不在」可以用 GET
推成功了但小鸥还答旧的推送到了另一个环境的租户,或另一个租户核对自检返回的 tenant 是否就是问答用的那个租户

三、自检返回码含义

返回含义
{"ok":true,"service":"tenant_ingest","auth":false}接口已上线,你还没带 Key(正常)
{"ok":true,...,"auth":true,"tenant":N}接口在、Key 有效,可以看到所属租户 ID
{"ok":false,"error":"invalid or missing api key"}Key 无效,检查 Key 与环境
1接口在不在
2Key 对不对
3载荷对不对
4按对照表修
▶对接排错演示(4 步)共 4 步 · 点上方步骤查看画面
aigeo.gonglve.com.cn/api/tenant_ingest.php
开放 API · 快速接入
POST/api/tenant_ingest.php
Authorization: Bearer <你的开放 API Key>
{ "docs": [ {"external_id":"gl-1001","category":"recruit",
  "title":"招聘:本地生活运营专员","content":"…"} ] }
→ {"ok":true,"total":1,"inserted":1,"errors":[]}
GET/api/tenant_ingest.php自检 → auth:true
1浏览器打开接口地址,404 说明没部署到该环境
aigeo.gonglve.com.cn/api/tenant_ingest.php
开放 API · 快速接入
POST/api/tenant_ingest.php
Authorization: Bearer <你的开放 API Key>
{ "docs": [ {"external_id":"gl-1001","category":"recruit",
  "title":"招聘:本地生活运营专员","content":"…"} ] }
→ {"ok":true,"total":1,"inserted":1,"errors":[]}
GET/api/tenant_ingest.php自检 → auth:true
2带 Bearer 再访问,401 说明 Key 或环境不匹配
aigeo.gonglve.com.cn/api/tenant_ingest.php
开放 API · 快速接入
POST/api/tenant_ingest.php
Authorization: Bearer <你的开放 API Key>
{ "docs": [ {"external_id":"gl-1001","category":"recruit",
  "title":"招聘:本地生活运营专员","content":"…"} ] }
→ {"ok":true,"total":1,"inserted":1,"errors":[]}
GET/api/tenant_ingest.php自检 → auth:true
3推一条最小数据,看 inserted 与 errors 逐条原因
aigeo.gonglve.com.cn/api/tenant_ingest.php
开放 API · 快速接入
POST/api/tenant_ingest.php
Authorization: Bearer <你的开放 API Key>
{ "docs": [ {"external_id":"gl-1001","category":"recruit",
  "title":"招聘:本地生活运营专员","content":"…"} ] }
→ {"ok":true,"total":1,"inserted":1,"errors":[]}
GET/api/tenant_ingest.php自检 → auth:true
4对照上面的报错表定位,绝大多数是域名拼接与额度两件事
以上为按步骤自动生成的界面示意图,实际界面以你的账号为准
小贴士把「接口在不在」「Key 对不对」两步做成你们后台的「运行连通性自检」按钮,对接当天就能自己确认通不通,不用来回问我们。