Kintone 添加记录 API 返回“必填字段”错误的排查与解决-php教程-PHP中文网

Kintone 添加记录 API 返回“必填字段”错误的排查与解决

本文详解 Kintone Add Record API 调用中出现 CB_VA01 错误（提示“必须填写”）的常见原因，重点指出看似已赋值却仍报错的关键陷阱——空字符串 "" 被 Kintone 视为未填写，并提供可立即验证的调试方案与正确请求示例。

本文详解 kintone add record api 调用中出现 `cb_va01` 错误（提示“必须填写”）的常见原因，重点指出看似已赋值却仍报错的关键陷阱——空字符串 `""` 被 kintone 视为未填写，并提供可立即验证的调试方案与正确请求示例。

在使用 Kintone 的 Add Record API 时，即使请求体中已显式声明字段并赋值，仍可能收到如下典型错误：

{
  "code": "CB_VA01",
  "message": "入力内容が正しくありません。",
  "errors": {
    "record.名.value": {
      "messages": ["必須です。"]
    }
  }
}

该错误明确表示字段「名」未通过必填校验。但请注意：Kintone 对“必填字段”的判定逻辑极为严格——不仅拒绝 null，也拒绝空字符串 "" 和仅含空白字符（如 " "）的值。这意味着以下写法均会触发 CB_VA01：

// ❌ 全部无效：Kintone 将其视作“未填写”
"名": { "value": "" }
"名": { "value": "   " }
"名": { "value": null }  // JSON 中实际无法直接写 null，但程序生成时可能出错

✅ 正确做法是确保 value 为非空、去首尾空格后的有效字符串：

{
  "app": 123,
  "record": {
    "名": {
      "value": "三宅"  // ✅ 非空、无多余空白
    }
  }
}

此外，请同步检查以下关键配置项（常被忽略但直接影响请求有效性）：

Header 必须包含：
- Content-Type: application/json（注意无空格、大小写不敏感但建议小写）
- X-Cybozu-API-Token: （确认 Token 未过期、权限覆盖目标应用、且未误粘贴空格或换行）
App ID 必须为数字类型（非字符串）：
若 Postman 或代码中误写 "app": "123"（带引号），部分环境可能静默失败。请确保为 "app": 123。
字段标识符需完全匹配：
检查 API 请求中的字段名（如 "名"）是否与 Kintone 应用设置中的「字段代码（Field Code）」一致（而非仅显示名称）。若字段代码实际为 last_name，则必须使用 "last_name": { "value": "三宅" }。

? 快速自检步骤：

在 Postman 中手动输入 "名": { "value": "三宅" }（避免从变量/脚本复制导致隐藏空格）；
使用 console.log(JSON.stringify(payload))（前端）或 print(json.dumps(payload))（Python）打印最终请求体，确认无意外空值；
临时将字段设为「非必填」测试——若此时成功，则 100% 确认为值校验问题。