API ドキュメント

API の利用を開始する

1. サポートにアカウントの開設を依頼してください。
2. 必要なサービス、アカウント、サーバーの送信元 IP をサポートにお知らせください。
3. その後、API キーと完全な連携ガイドを発行します。キーの有効期間は 1–730 日で、1 つのキーにつき送信元 IP を最大 32 件まで登録できます。

基本仕様

認証

すべてのリクエストに Authorization: Bearer <API キー> を付けて送信

User-Agent

必須です。ないリクエストは Cloudflare にブロックされます（error 1010）

形式

リクエストとレスポンスは UTF-8 の JSON（ファイルのアップロードを除く）

日時

UTC の Unix タイムスタンプ（ミリ秒）

金額

小数点以下最大 8 桁。10 進数型で扱い、小数点以下 2 桁に丸めないでください

連携の流れ

1. サービス一覧と残高を確認し、使用する productId を控えます。
2. データ利用に関する声明を確認し、未承諾の場合は承諾します。
3. 番号ファイルをアップロードし、返された fileId を控えます。
4. productId と fileId で見積もりを取得し、件数、単価、合計金額を確認します。
5. 冪等キーを作成して保存してから注文します。この操作で残高から課金されます。
6. Webhook を設定して注文ステータスの通知を受け取り、取りこぼし防止のため 5–10 分ごとに updatedSince で照合します。
7. 完了したら結果ファイルの一覧を取得し、失敗分を含むすべてのファイルをダウンロードして sha256 を確認します。

curl の例

プレースホルダーを実際の値に置き換えてください。見積もりと注文のすべてのパラメーターは、利用開始時にお渡しするガイドに記載しています。

1. キーを設定してサービスを一覧表示

   コピー

   export CHECKIM_TOKEN='サポートから受け取った API キーに置き換えてください'
   export CHECKIM_BASE='https://api.checkim.ai/openapi/v1'
   
   curl -H "Authorization: Bearer $CHECKIM_TOKEN" "$CHECKIM_BASE/products"

2. 番号ファイルをアップロード

   コピー

   curl -H "Authorization: Bearer $CHECKIM_TOKEN" \
     -F 'file=@./numbers.csv;type=text/csv' \
     "$CHECKIM_BASE/files"

3. 見積もりを取得

   コピー

   curl -H "Authorization: Bearer $CHECKIM_TOKEN" \
     -H 'Content-Type: application/json' \
     -d '{"productId":"<productId>","name":"batch-001","fileId":"<fileId>"}' \
     "$CHECKIM_BASE/orders/check"

4. 注文

   コピー

   # 残高から課金されます。再試行時はキーとリクエスト本文をまったく同じにしてください。
   curl -H "Authorization: Bearer $CHECKIM_TOKEN" \
     -H 'Content-Type: application/json' \
     -H 'Idempotency-Key: partner-request-001' \
     -d '{"quoteId":"<quoteId>","clientOrderId":"partner-batch-001"}' \
     "$CHECKIM_BASE/orders"

5. 注文を確認、または変更時刻で照合

   コピー

   curl -H "Authorization: Bearer $CHECKIM_TOKEN" "$CHECKIM_BASE/orders/<orderId>"
   
   curl -H "Authorization: Bearer $CHECKIM_TOKEN" \
     "$CHECKIM_BASE/orders?updatedSince=<UTC ms>&size=100"

6. 結果を一覧表示・ダウンロードして sha256 を確認

   コピー

   curl -H "Authorization: Bearer $CHECKIM_TOKEN" "$CHECKIM_BASE/orders/<orderId>/results"
   
   curl -H "Authorization: Bearer $CHECKIM_TOKEN" -o result.csv \
     "$CHECKIM_BASE/orders/<orderId>/results/<fileId>/download"
   shasum -a 256 result.csv

エンドポイント

注文の一覧と照合

• 注文は新しい順に返されます。nextCursor があるページでは、それを次の cursor として渡してください。カーソルによるページ送りでは、新しい注文が増えても漏れや重複が起きません。
• status と作成日時（createdFrom、createdTo、UTC ミリ秒）で絞り込めます。clientOrderId で特定の注文を照会することもできます。
• updatedSince は、その時刻以降にステータスが変わった注文だけを、変更の古い順に返します。定期的に取得すれば、Webhook を取りこぼしてもステータスを失いません。

結果のダウンロード

• 結果一覧のすべてのファイルに sha256 があります。ダウンロードの ETag も同じ値なので、ダウンロード後に照合してください。
• Range リクエストでダウンロードを再開できます。先に sha256 が変わっていないか確認し、変わっていればファイルが再生成されたため全体を再取得してください。
• 完全なファイルがすでにある場合は If-None-Match を付けて送信すると、変更がなければ本文なしの 304 が返ります。
• 分割納品の大口注文では、処理中でも完了した分のファイルが一覧に表示されます。完了後の最終ファイルが正式な版です。
• アバター付きのサービス（Telegram・WhatsApp の拡張チェック、性別・年齢チェック）では、結果 CSV の avatar 列に署名付き画像 URL が入ります。結果の保存期間中は Authorization ヘッダーなしで直接 GET 取得でき、If-None-Match にも対応しています。

Webhook

• API で行った注文のステータスが変わると、お客様の HTTPS URL にイベントを POST します。webhook:manage 権限が必要です。
• 各イベントには CheckIM-Signature ヘッダー（t=タイムスタンプ,v1=署名）が付きます。署名シークレットで「t.生のリクエスト本文」の HMAC-SHA256 を計算して検証してください。
• 2xx の応答で配信完了とみなし、失敗時は約 2 日間に 9 回再試行します。同じイベントが複数回届くことがあるため、イベント id で重複を除いてください。
• リクエストは固定の送信元 IP 34.21.195.36 から届くため、このアドレスだけを許可できます。

注文ステータス

制限と注意事項

• 標準の上限は 1 分あたり、送信元 IP ごとに 1,200 リクエスト、アカウントごとに 240、キーごとに 120 です。RateLimit-Limit、RateLimit-Remaining、RateLimit-Reset ヘッダーで今の 1 分間の残り回数がわかります。
• 見積もりとアップロードは時間がかかるため、同時に実行できるのはアカウントごとに 3 件までです。超えると 429 TOO_MANY_CONCURRENT_REQUESTS が返されます。
• 429 または 503 が返されたら、Retry-After の秒数だけ待ってから同じリクエストを再送してください。
• テスト環境はありません。すべての注文は実際に課金されます。
• ポーリングのタイムアウトは注文の失敗を意味しません。再度注文する前に、orderId または clientOrderId で注文を確認してください。

主なエラー

エラーには code、requestId、message と、必要に応じて detail.field が含まれます。処理は code で判断してください。message は Accept-Language に応じた 9 言語のいずれかで、表示専用です。