入门

请求与错误

每个 Bitaloka 端点如何接收输入并报告结果——学一次，处处适用。

Base URL

https://api.bitaloka.io/v1

所有端点均在 /v1 下进行版本管理，且仅通过 HTTPS 提供。

发送输入

路径——标识符直接放入 URL，例如 GET /v1/nik/{nik}。
JSON 请求体——文本类服务接受 Content-Type: application/json。
Multipart 表单——PDF 和图像工具接受 multipart/form-data，包含 file（或多个 files），选项以文本字段传入。

返回内容

解析器、查询和 AI 服务返回 JSON。PDF 工具返回处理后的文件（application/pdf，拆分时为 application/zip）——直接将响应体写入磁盘即可。

无效输入不是错误

格式错误的 NIK 仍会得到 HTTP 200，同时返回 valid: false 和说明原因的 errors 列表。请根据 valid 而非状态码进行分支处理。

GET /v1/nik/123 → 200 OK

{
  "valid": false,
  "input": "123",
  "normalized": "123",
  "gender": null,
  "birthDate": null,
  "region": null,
  "serial": null,
  "genderConsistent": false,
  "summary": "",
  "errors": [
    {
      "code": "INVALID_FORMAT",
      "message": "NIK must be exactly 16 digits"
    }
  ],
  "warnings": []
}

错误

真正的失败使用标准 HTTP 状态码，并返回 JSON 响应体 {"error": "…"}。

状态码	含义
`400`	输入缺失或格式错误——例如未提供文件，或页码范围无效。
`401`	API 密钥缺失或无法识别（启用密钥校验后）。
`413`	上传文件超过 60 MB。
`503`	某个依赖服务暂时不可用。请使用指数退避重试。

限制

每个请求最多上传 60 MB。批量解析每次调用最多 100 项。

从浏览器调用

CORS 已开放，网页可直接调用 API。切勿在前端代码中包含私密密钥——请通过您自己的服务器调用。