冪等性

書き込みリクエストは Idempotency-Key ヘッダーを受け取るため、リトライしたリクエストが二重に適用されることはありません。

curl -X POST https://api.fabhub.app/v1/items \
  -H "X-API-Key: $FABHUB_API_KEY" \
  -H "Idempotency-Key: 0b9c4a2e-2f1d-4c7a-9b3e-2a1f5c8d7e6b" \
  -H "Content-Type: application/json" \
  -d '{"name":"Widget","itemType":"product"}'

ルール

• 論理的な書き込みごとに一意のキーを生成します（UUID が適しています）。
• 同じキーは、その書き込みの正確なリトライの場合にのみ再利用します。
• 異なるペイロード間でキーを再利用しないでください。再利用すると code: "CONFLICT" とともに 409 が返されます。
• キーは 24 時間有効です。

適用される箇所

Idempotency-Key は、品目、注文、連絡先、在庫ドキュメント、Webhook に対するすべての POST および PATCH 書き込みで必須です。DELETE 操作は本質的に冪等なため、このヘッダーは不要です。

SDK での利用

SDK は、すべての書き込みメソッドで idempotencyKey オプションを受け取ります。

await fabhub.createItem(
  { name: 'Widget', itemType: 'product' },
  { idempotencyKey: crypto.randomUUID() },
);