API サービスと課金の説明
登録ユーザーは API キーで HS コード、商品、商品と HS の関連を照会できます。同じアカウント・エンドポイント・対象の初回成功照会は 0.04 USD、再照会は永久無料です。Web と API はパックを共有します。
- 利用範囲
- 登録してメール認証済みのユーザー
- 課金
- 0.04 USD
- 引き落とし順
- パック → 残高
取得できるデータ
| 項目 | 説明 | 課金 |
|---|---|---|
| HS コード検索 | HS コードの現行版名称と輸入税率を照会し、その子コードをツリー構造で返します。 | レコードが見つかった場合 0.04 USD |
| 商品情報の取得 | JAN バーコードまたは商品 ID で商品の基本情報を取得します。HS コードの関連は含みません。 | レコードが見つかった場合 0.04 USD |
| 商品と HS コードの関連の取得 | 商品の基本情報と確認済みの HS コード関連を照会します。 | レコードが見つかった場合 0.04 USD |
読み取り専用です。3 つの API はいずれもレコードが見つかった場合に課金され、コードや商品が存在しない場合は 404 を返して課金しません。枠が不足する場合は 402 を返し、部分的なデータは返しません。
認証
ダッシュボードで API KEY を作成し、Authorization ヘッダーで送信します。キーは作成時に一度だけ表示されるため、安全に保管してください。
Authorization: Bearer mls_xxxxxxxxxxxxxxxx
完全な API アドレスとリクエスト例はワークステーションの「API ドキュメント」で確認できます。
成功した各レスポンスには今回の課金情報(funding、usesCharged、amountCharged、packRemaining、balance、currency)が含まれます。
課金とチャージパック
Web と API はパックと残高を共有し、課金時はパック、残高 0.04 USD の順に消費します。同じアカウント・エンドポイント・対象の API 再照会は永久無料で、残高がなくても利用できます。
| チャージパック | 利用可能回数 | 1 回あたり単価 |
|---|---|---|
| 10.00 USD | 275 | 約 0.036 USD / 回 |
| 50.00 USD | 1,500 | 約 0.033 USD / 回 |
| 100.00 USD | 3,250 | 約 0.031 USD / 回 |
| 500.00 USD | 18,750 | 約 0.027 USD / 回 |
残高への直接チャージも可能で、1 回 0.04 USD で差し引きます。パックと残高はダッシュボードで購入・確認できます。
エラーと制限
- 402 insufficient_credit:チャージパックの回数と残高が不足しています。先にチャージしてください。
- 404 not_found:コードまたは商品が存在しないか、まだ公開されていません。
- 409 ambiguous:バーコードが複数の商品に対応しています。商品 ID で照会してください。
- 1 時間あたり 120 リクエストの基本制限があり、超過時は 429 を返します。
API が返す税率および商品と HS コードの関連は参考情報です。正式な分類・通関判断は日本の税関および所管機関の説明に従ってください。