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

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

本文详解 kintone add record api 调用时出现「cb_va01：必填字段」错误的常见原因（如空值、编码问题、字段名不匹配等），并提供可立即验证的请求示例、调试步骤及最佳实践。

本文详解 kintone add record api 调用时出现「cb_va01：必填字段」错误的常见原因（如空值、编码问题、字段名不匹配等），并提供可立即验证的请求示例、调试步骤及最佳实践。

在使用 Kintone 的 Add Record API（POST /k/v1/record.json）时，即使请求体结构看似正确，仍可能收到如下典型错误响应：

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

该错误明确表示：字段“名”被识别为空或无效值，触发了必填校验失败。值得注意的是，这并非接口权限或 Token 问题（否则会返回 401 Unauthorized 或 403 Forbidden），而是服务端字段校验层的拒绝。

尽管请求体中已包含 "名": {"value": "三宅"}，但以下情况仍会导致 Kintone 认为该字段“未填写”：

字段名拼写或大小写不一致：Kintone API 严格区分字段代码（Field Code），而非字段标签（如“名”）。请务必确认你在 API 请求中使用的 "名" 是该字段的实际字段代码（Field Code），而非显示名称。例如，若字段代码实际为 last_name，则必须写 "last_name": {"value": "三宅"}。
JSON 值为纯空白字符串或仅含不可见字符：如 "value": ""、"value": "　"（全角空格）或 "value": "\n\t "，Kintone 会视作未输入，触发必填校验失败。
Content-Type 缺失或错误：必须显式设置请求头 Content-Type: application/json，且不能带额外空格（如 application/json; charset=utf-8 在某些旧版环境可能引发解析异常）。
中文字符编码问题（罕见但存在）：若请求体未以 UTF-8 编码发送（尤其在 Postman 中误选其他编码），可能导致 JSON 解析后 "三宅" 变为乱码或空值。

确保以下三点全部满足：

POST https://your-domain.cybozu.com/k/v1/record.json

Headers：

Content-Type: application/json
X-Cybozu-API-Token: b7EMUSEfcDCbb0xxxxxxxxxxxxxxxxxx

Body（JSON）：

{
  "app": 123,
  "record": {
    "last_name": {
      "value": "三宅"
    }
  }
}

? 提示：如何确认字段代码？进入 Kintone 应用 →「应用设置」→「字段设置」→ 点击对应字段 → 查看右上角「字段代码」（如 last_name、full_name 等）。切勿依赖界面上显示的“名”“姓名”等中文标签。

启用 Kintone 日志（高级用户）：若拥有管理员权限，可在「系统设置」→「API 日志」中查看原始入参，确认服务端实际接收到的 record 结构是否含空值或字段名错误。
Postman 验证技巧：
- 关闭「Pretty」格式化，切换至「Raw」并确认编码为 UTF-8；
- 在 Body → JSON 模式下粘贴，避免手动输入引号导致隐形字符；
- 使用 {{}} 变量前先检查是否被意外渲染为空。

空值安全处理（开发侧）：前端或脚本中应增加校验逻辑，例如：

const lastName = trim(inputValue) || null;
if (!lastName) throw new Error("字段 'last_name' 不可为空");

CB_VA01 错误本质是字段校验失败，而非网络或认证问题。95% 的案例源于字段代码误用或 value 值为空/空白。请优先核对字段代码、清理字符串前后空白、确保 UTF-8 编码，并通过 Kintone 字段设置页确认唯一标识符。修复后，一次成功提交即可验证。

遵循以上步骤，您将快速定位并解决 Kintone Add Record API 的“必填字段”报错，大幅提升集成开发效率。

大量免费API接口：立即使用
涵盖生活服务API、金融科技API、企业工商API、等相关的API接口服务。免费API接口可安全、合规地连接上下游，为数据API应用能力赋能！