はじめに

リクエストとエラー

すべての Bitaloka エンドポイントにおける入力の受け取り方と結果の返し方です。一度覚えれば、どこでも使えます。

ベース URL

https://api.bitaloka.io/v1

すべてのエンドポイントは /v1 でバージョン管理され、HTTPS でのみ提供されます。

入力の送信

パス — 識別子は URL に直接含めます。例: GET /v1/nik/{nik}。
JSON ボディ — テキスト系サービスは Content-Type: application/json を受け付けます。
マルチパートフォーム — 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`	依存サービスが一時的に利用できません。指数バックオフで再試行してください。

制限

アップロードは 1 リクエストあたり最大 60 MB です。バッチ解析は 1 回の呼び出しで最大 100 件まで処理できます。

ブラウザからの呼び出し

CORS が許可されているため、Web ページから API を直接呼び出せます。ただし、シークレットキーをフロントエンドのコードに含めないでください。代わりに自社のサーバー経由で呼び出してください。