非洲第三方知识库

Appearance

Peleza 肯尼亚 ID 实名信息接口整理 ​

文档信息 ​

  • 供应商：Peleza Verify（数据源：肯尼亚 IPRS）
  • 整理自离线资料包 peleza-materials-20260805（快照 2026-08-05）
  • 厂商页：Peleza

1. 环境信息 ​

项目沙箱 Sandbox生产 Production
状态Active（凭证 1/1 已创建）凭证 0/1 未配置
Base URLhttps://sandbox.peleza.comhttps://verify.peleza.com
数据测试样例数据真实核验
计费测试预付费钱包按次扣费
  • 认证：OAuth 2.0 client credentials，先换 token 再调业务接口。
  • 两套环境各自有独立 Client ID / Secret Key，不可混用。
  • 沙箱测试号：快照中测试 ID 表格未抓取到内容，示例 ID 1028845317 / 1028845318 可先用于联调；如均返回 404，需向 Peleza 索取最新测试号列表。

2. 调用流程 ​

text
① POST {BASE_URL}/api/v1/oauth/token   换 access_token（3600s，需缓存）
② POST {BASE_URL}/api/v1/id/ke         带 Bearer token 查询实名信息

3. 认证接口 ​

  • 沙箱：POST https://sandbox.peleza.com/api/v1/oauth/token
  • 生产：POST https://verify.peleza.com/api/v1/oauth/token

入参（JSON body）：

字段类型必填说明
grant_typestring是固定 client_credentials
client_idstring是控制台 API Management 页获取
client_secretstring是同上，只放后端环境变量 / secret manager

请求示例：

bash
curl -X POST https://sandbox.peleza.com/api/v1/oauth/token \
  -H "Content-Type: application/json" \
  -d "{\"grant_type\": \"client_credentials\", \"client_id\": \"YOUR_SANDBOX_CLIENT_ID\", \"client_secret\": \"YOUR_SANDBOX_CLIENT_SECRET\"}"

成功响应：

json
{
  "access_token": "YOUR_ACCESS_TOKEN",
  "token_type": "Bearer",
  "expires_in": 3600,
  "scope": "api"
}

认证错误码：

错误码说明HTTP
INVALID_CLIENTclient_id / client_secret 错误401
INVALID_TOKENtoken 无效或过期401
INVALID_SCOPEscope 无效400
RATE_LIMIT_EXCEEDED请求过于频繁429

实现要求：token 缓存 3600s，收到 401 INVALID_TOKEN 刷新后重试一次；Secret 严禁进前端代码 / 仓库。

4. 业务接口 ​

4.1 Verify Kenya ID（推荐入口） ​

  • 沙箱：POST https://sandbox.peleza.com/api/v1/id/ke
  • 生产：POST https://verify.peleza.com/api/v1/id/ke
  • Header：Authorization: Bearer <access_token>、Content-Type: application/json
  • 国家由路径 ke 决定，body 不传 country_code。
  • 等价 Legacy 端点：POST /api/v1/national-id（老客户端兼容）。

入参：

字段类型必填说明
id_numberstring是肯尼亚身份证号，6–10 位数字
customer_numberstring否自备业务流水号，用于对账，max 255 字符
scopestring是作用域：basic（基础验证）/ full（完整查询）
consentboolean是用户同意标记 true / false（合规前置，需在采集端取得用户授权）

请求示例：

bash
# 沙箱
curl -X POST https://sandbox.peleza.com/api/v1/id/ke \
  -H "Authorization: Bearer YOUR_ACCESS_TOKEN" \
  -H "Content-Type: application/json" \
  -d "{\"id_number\": \"1028845317\", \"scope\": \"basic\", \"consent\": true, \"customer_number\": \"CUST001\"}"

# 生产
curl -X POST https://verify.peleza.com/api/v1/id/ke \
  -H "Authorization: Bearer YOUR_ACCESS_TOKEN" \
  -H "Content-Type: application/json" \
  -d "{\"id_number\": \"1028845317\", \"customer_number\": \"CUST001\"}"

成功响应：

json
{
  "success": true,
  "response_code": 200,
  "message": "Kenya ID details fetched successfully",
  "country": "ke",
  "data": {
    "id_number": "1028845317",
    "first_name": "JANE",
    "last_name": "DOE",
    "other_name": "W",
    "name": "JANE W DOE",
    "gender": "Female",
    "dob": "1990-01-15",
    "citizenship": "Kenyan",
    "valid": true,
    "status": "Active"
  },
  "request_id": "550e8400-e29b-41d4-a716-446655440000"
}

响应 data 字段：

字段说明
id_number身份证号
first_name / last_name / other_name姓名拆分
name全名
gender性别
dob出生日期（yyyy-MM-dd）
citizenship国籍
valid / status是否有效 / 状态（Active 等）

错误码：

HTTP说明
400参数校验失败（ID 缺失、非数字、不是 6–10 位）
401 / 403token 无效；或该国家/服务无权限
402钱包余额不足（预付费模式）
404ID 在 IPRS 中不存在
429触发限流
503服务暂不可用

错误响应示例：

json
{
  "success": false,
  "response_code": 400,
  "message": "The ID number must be between 6 and 10 digits",
  "data": null,
  "request_id": "..."
}

4.2 Validate（仅校验有效性，不取详情） ​

  • 沙箱：GET https://sandbox.peleza.com/api/v1/national-id/validate/{id_number}
  • 生产：GET https://verify.peleza.com/api/v1/national-id/validate/{id_number}
  • Header：Authorization: Bearer <access_token>
bash
curl -X GET https://sandbox.peleza.com/api/v1/national-id/validate/1028845317 \
  -H "Authorization: Bearer YOUR_ACCESS_TOKEN"
json
{
  "success": true,
  "response_code": 200,
  "message": "National ID Validation Successful",
  "data": {
    "id_number": "1028845317",
    "is_valid": true,
    "status": "Active"
  },
  "request_id": "..."
}

4.3 With Image（需要照片 / 指纹 / 签名时） ​

  • 沙箱：POST https://sandbox.peleza.com/api/v1/national-id-image
  • 生产：POST https://verify.peleza.com/api/v1/national-id-image
  • 请求体同 4.1（id_number 必填，customer_number 可选）。
  • 成功时 data 额外返回：serial_number、photo_url、fingerprint_url、signature_url、has_photo / has_fingerprint / has_signature、is_valid，以及 occupation、place_of_birth、date_of_issue 等可为 null 的扩展字段。
  • 图片为存储服务 URL，有时效性，建议及时转存。
  • 错误码在 4.1 基础上额外包含：408（上游超时）、500/502（上游异常）、503（无法连接核验服务或端点被停用）。

5. 接入注意事项 ​

  1. 先沙箱后生产：生产凭证当前未创建（0/1），上线前需在控制台生成并充值钱包（预付费按次计费）。
  2. request_id 落库：每次响应的 request_id 用于审计、对账、故障排查。
  3. token 管理：单例缓存 + 过期刷新，避免每次请求都换 token。
  4. 402 处理：预付费余额不足直接返回 402，需接入余额监控（GET /api/v1/wallet/balance）并配置告警。
  5. 限流：429 时做退避重试。
  6. 敏感数据：返回的实名信息 + 图片 URL 属敏感数据，注意存储加密与访问控制；Secret Key 只放后端。
  7. HTTPS Only：所有请求走 HTTPS。

接入待确认 ​

  • 生产凭证创建与钱包充值流程、按次计费单价。
  • 沙箱测试 ID 列表（快照缺失测试表格，示例 ID 若 404 需向 Peleza 索取）。
  • With Image 接口返回的照片如何衔接人脸比对链路（如 SmileID SmartSelfie Compare / AWS CompareFaces）。
  • 与 Softnet / YesID / NIDA 等其他身份源的角色分工。