共通ルール

関連ドキュメント：認証 · 商品と注文 · README

#リクエスト

• ベースURL：https://b2b.cardv.net/api/v1（Live）、https://sandbox.cardv.net/api/v1（Sandbox）
• パスの末尾にスラッシュは付けません。/api/v1/orders/ ではなく /api/v1/orders を使ってください。
• JSONの本文はUTF-8で、Content-Type: application/json を付けて送ります。
• 金額は "9.2500" のように文字列で送ります。丸め誤差を防ぐためです。
• AcmeShop-CardV/1.4 のように、送信元がわかる User-Agent を設定してください。

#金額と日時

• 金額は小数点以下4桁の文字列です。例："merchant_price": "9.2500"
• 金額は必ず10進数型（Decimalなど）で扱い、浮動小数点数は使わないでください。
• 支払いはウォレットの通貨で行います（GET/account の default_currency。現在はUSD）。
• face_currency はカードに記載されている通貨です。ウォレットの通貨と異なる場合があります。
• 仕入れ価格の計算には必ず merchant_price を使ってください。price_label などのラベルは表示専用です。
• 日時はすべてUTCで、ISO 8601形式です。例：2026-09-29T08:15:30.123456Z
• 日時の解析には、正式なISO 8601パーサーを使ってください。秒の小数点以下の桁数は一定ではありません。
• 署名に使う X-Timestamp はUnix時間（秒）です。

#ID

• IDは文字列として保存し、中身を解析しないでください。将来、桁数が増える可能性があります。
• 注文には数値の id もありますが、使わないでください。order_id を使ってください。
• 自社の注文番号には A–Z a–z 0–9 - _ . だけを使ってください。

#ページング

ページングがあるのは GET/skus だけです。limit と offset を指定します。

GET /api/v1/skus?limit=100&offset=200

{"count": 1234, "limit": 100, "results": ["..."], "filter_options": {}}

• limit の初期値は100、上限は500です。500を超える値は500として扱われます。
• count は条件に合う件数の合計です。offset が count に達するまで取得を続けてください。
• limit や offset に負の数や数値以外を指定すると、HTTP 400が返ります。
• 存在しない絞り込み条件を指定した場合は、エラーではなく空の一覧が返ります。

#レート制限

• 初期値は、アカウント全体で1分あたり60リクエストです。すべてのAPIキーとPortalユーザーでこの上限を共有します。契約プランによっては上限が異なります。

• 1分の区切りは、時計の :00 秒から始まります。拒否されたリクエストも回数に含まれます。

• 上限を超えると、HTTP 429と Retry-After ヘッダー（待つべき秒数）が返ります。

  JSONCopy

  {"detail": "Merchant API rate limit exceeded. Expected available in 23 seconds."}

• 上限を超えないためには、SKU一覧をキャッシュする、短い間隔でのポーリングではなくWebhookを使う、 429が返るたびに待ち時間を少しずつ長くする、といった工夫をしてください。

#エラー

まずHTTPステータスを確認し、次にJSONの本文を読みます。何が問題だったかは、本文のキーでわかります。メッセージの文言には依存しないでください。

認証、権限、未検出、レート制限のエラーは detail で返ります。

{"detail": "Order not found."}

注文と見積もりのエラーは、問題のあったフィールド名で返ります。

{"balance": "Insufficient available balance."}

注文明細の形式が正しくない場合は、明細ごとにエラーが返ります。並び順は送信した items と同じです。

{"items": [{}, {"quantity": ["Ensure this value is greater than or equal to 1."]}]}

一部のエラーはJSON以外の形式で返ります。

• error code: 1010 のようなプレーンテキストのHTTP 403は、CardVのネットワークの入口で返されたものです。リクエストはCardVのサーバーに届いていません。貴社サーバーのIPアドレスと User-Agent をCardVにお知らせください。
• 存在しないパス（404）やプロキシのエラー（5xx）では、HTMLが返ることがあります。

エラーをログに記録するときも、APIキー、署名、コードは絶対に記録しないでください。

#HTTPステータスコード

POST/orders を再試行するときは、本文と自社の注文番号を必ず同じにしてください。詳しくは安全な再送の手順をご覧ください。

#レスポンス

• brand_logo_url と image_url は、CardVが提供する画像の完全なURL、または "" です。公開されている画像なので、キャッシュして構いません。
• 注文の invoice_url と delivery_file_url は /orders/O-00001234/invoice のようなパス、またはまだ何もない場合は "" です。これらはPortal専用で、APIキーで呼び出すとHTTP 403が返ります。請求書やコードのCSVファイルはPortalで開いてください。

#互換性

• 知らないフィールドは無視してください。CardVはAPIのバージョンを変えずにフィールドを追加します。
• 新しいステータスの値が追加されることがあります。知らないステータスは「まだ完了していない」ものとして扱ってください。
• JSONのキーの順番やメッセージの文言には依存しないでください。