Kimai API中客户ID与客户编号的正确使用方式

概述

在使用Kimai时间跟踪系统的API时，开发人员经常会混淆客户ID(customer ID)和客户编号(customer number)这两个概念。本文将详细解释这两者的区别，并提供正确的API使用方法。

客户ID与客户编号的区别

在Kimai系统中，每个客户实体有两个重要标识符：

1. 客户ID：由系统自动生成的唯一数字标识符，不可更改
2. 客户编号：用户自定义的可编辑字符串，用于业务标识

这两个标识符在API中的使用场景完全不同，混淆使用会导致数据关联错误。

创建客户时的API使用

通过POST方法创建新客户时，可以指定客户编号(number)，但不能指定客户ID。系统会自动生成ID并返回在响应中。

示例请求体：

{
  "name": "示例客户",
  "number": "CUST001",
  "visible": true,
  "billable": true,
  "currency": "USD",
  "country": "US",
  "timezone": "America/New_York",
  "email": "[e-mail]"
}

响应中将包含系统生成的ID：

{
  "id": 123,
  "number": "CUST001",
  ...
}

创建项目时的正确关联方式

当需要为客户创建项目时，必须使用客户ID而非客户编号进行关联。

错误示例（使用客户编号）：

{
  "customer": "CUST001",
  "name": "错误示例项目"
}

正确示例（使用客户ID）：

{
  "customer": 123,
  "name": "正确示例项目"
}

常见问题解决方案

1. 如何获取客户ID？

   • 创建客户后从API响应中获取
   • 通过GET /customers接口查询现有客户列表

2. 特殊字符处理

   • 在API令牌中包含特殊字符时，需要进行URL编码
   • 未来版本将提供自动生成的API令牌以避免此问题

3. 错误排查

   • 400错误通常表示使用了无效的客户ID
   • 403错误可能由身份验证问题引起

最佳实践建议

1. 创建客户后立即保存返回的ID
2. 在代码中明确区分ID和number的概念
3. 实现错误处理逻辑，特别是针对400和403状态码
4. 考虑使用API客户端库简化请求处理

通过正确理解和使用Kimai API中的客户标识符，可以避免数据关联错误，确保系统数据的完整性和一致性。