CPF 验证

通过模 11 算法验证 CPF 号码的格式和校验位。

端点

POST /api/external/cpf/validate

请求头

头	类型	必填	描述
Authorization	String	是	ApiKey {client_id}:{client_secret}（Basic 格式 + base64 也被接受 -- 见 身份验证）
Content-Type	String	是	application/json
hmac	String	是	body 的 HMAC-SHA512 签名,十六进制小写（详见此处）
X-Key-Case	String	否	camelCase -- 将 params/response 在 snake_case ↔ camelCase 之间转换。如果发送 camelCase,请以 camelCase 签名 body（见 HMAC-SHA512）
Idempotency-Key	String	否	唯一键以避免重复处理（最多 256 字符）。提供时,服务器在响应中回显 Idempotency-Key,并在重放时添加 X-Idempotent-Replay: true

API Key 需要权限：account:read。没有该权限,请求在执行验证之前被拒绝,返回 403 API key lacks permission: account:read。

请求体

字段	类型	必填	描述	示例
cpf	String	是	CPF 号码（可带或不带格式化符号）	"12345678909" 或 "123.456.789-09"

别名

也接受字段 document_number 作为别名。

示例

必需 HMAC

此端点需要 hmac 头,即使 body 只有一个字段。无此头的请求在到达控制器之前返回 401 Missing HMAC header。

# Body 只有 1 个字段 — 已经是"字母排序"的
BODY='{"cpf":"12345678909"}'

# 使用 client_secret 作为密钥计算 HMAC-SHA512
HMAC=$(echo -n "$BODY" | openssl dgst -sha512 -hmac "$CLIENT_SECRET" | awk '{print $2}')

curl -X POST https://api.owem.com.br/api/external/cpf/validate \
  -H "Authorization: ApiKey $CLIENT_ID:$CLIENT_SECRET" \
  -H "Content-Type: application/json" \
  -H "hmac: $HMAC" \
  -d "$BODY"

成功响应 -- CPF 有效 (200)

{
  "worked": true,
  "valid": true,
  "formatted": "123.456.789-09"
}

成功响应 -- CPF 无效 (200)

{
  "worked": true,
  "valid": false,
  "detail": "CPF inválido"
}

当 valid: false 时 detail 的可能消息：

detail	原因
"CPF deve ter 11 digitos"	移除非数字字符后,号码不恰好是 11 位
"CPF invalido"	所有 11 位数字都相同（例：111.111.111-11）
"CPF invalido (digito verificador)"	校验位在模 11 算法中失败

字段	类型	描述
worked	Boolean	true 表示验证已执行（不保证 CPF 有效）
valid	Boolean	如果 CPF 通过模 11 算法有效则 true,否则 false
formatted	String	格式化后的 CPF（XXX.XXX.XXX-XX）。仅在 valid: true 时出现
detail	String	解释拒绝的消息。仅在 valid: false 时出现

为什么 valid: false 时是 200 OK 而不是 400？

CPF 无效是验证的一个合法结果 -- 不是请求错误。API 成功处理了请求,告知该号码未通过模 11。客户端必须始终检查 valid 字段（而不仅仅是 HTTP 状态）以决定下一步。同样的 {worked: true, ...} 模式也出现在 GET /balance（返回 worked: true, balance: N）和 POST /webhooks（返回 worked: true, id: "..."）中。

执行的验证

1. 检查 CPF 是否恰好包含 11 位数字
2. 拒绝所有数字相同的 CPF（例：111.111.111-11）
3. 使用模 11 算法计算并验证 2 位校验位

错误响应

400 -- 字段 cpf 缺失（FallbackController）

当 body 不包含字段 cpf（也没有别名 document_number）时,FallbackController 在执行模 11 验证之前拒绝请求：

{
  "errors": {
    "bad_request": {
      "cpf": ["is required"]
    }
  }
}

CPF 无效返回 HTTP 200,而不是 400

到达控制器但未通过模 11 的 CPF（校验位错误、所有数字相同,或少于 11 位）返回 HTTP 200 及 {"worked": true, "valid": false, "detail": "CPF inválido"}。不要与上述 400 混淆 -- 400 仅用于 body 中缺少 cpf 字段的情况。

401 -- HMAC 缺失或无效（HMAC plug）

{
  "worked": false,
  "detail": "Missing HMAC header"
}

{
  "worked": false,
  "detail": "Invalid HMAC signature"
}

401 有两种不同的格式

HMAC 验证层返回的 401（上面）与 API Key 层返回的 401（{"error": {status, message}}）结构不同。参见 身份验证 -- 错误响应 了解三层的详细信息。

用途

此端点仅对 CPF 执行数学验证（模 11 算法）。不会查询巴西联邦税务局,也不会验证证件的注册状态。