основные — コアコンセプト：ファイル、見積もり、ジョブ

1. 認証とセキュリティ

すべてのエンドポイントでQuote3D APIトークンによる認証が必要です。唯一の例外は、ファイル管理に記載された公開アップロードルートです。外部からの呼び出しにはhttps://api.quote3d.com/v2をベースルートとして使用してください。トークンはAuthorization: Bearer YOUR_TOKENまたはX-API-Tokenとして送信します。トークンはQuote3Dダッシュボードで生成し、秘密に保管してください。

トークンにはスコープを設定できます。フルアクセストークンはすべてのエンドポイントに到達しますが、ウィジェットスコープのトークンは埋め込みウィジェットが必要とするエンドポイントに限定されます。スコープ外の呼び出しは403を返します。トークンのスコープはダッシュボードのトークンページで確認・変更できます。

2. アカウント管理

専用のエンドポイントを通じて、アカウント、アップロード、および使用状況統計を管理します:

• GET /v2/user アカウント情報、プラン、月間割り当てを取得します — quotes_used、quotes_limit、storage_used、storage_limit、reset_dateはここにあります
• GET /v2/user/uploads アカウントにアップロードしたファイルを、最新のものから古いものの順にリスト表示します。
• GET /v2/quota レート制限の割り当てを取得します — グローバル上限に加え、残り呼び出し数とリセット時刻を含むエンドポイント別の内訳、さらに本日・今月・今年・累計のリクエスト数もあわせて返します
• GET /v2/usage エンドポイント統計、材料の使用量、および時間ベースのトレンドを含む、詳細な使用状況分析を取得

3. ファイル管理

3Dモデルファイル（STL、3MF、OBJ形式）のアップロード、ダウンロード、および管理：

• GET /v2/file/upload-id — 新しいファイルをパブリックアップロードルートでアップロードするための、一時的なupload_idを取得します。
• POST /v2/file/public/{upload_id} — このルートは認証を必要としません。クライアント側で使用して、ファイルをストレージに直接アップロードできます。

  パブリックアップロードルートを使用すると、大きなファイルをバックエンドサーバーにルーティングする必要がなくなります。これにより、APIトークンが公開されるのを防ぎ、サーバーの負荷を軽減できます。

• POST /v2/file — サーバー側からファイルをアップロードします（認証が必要です。バックエンドからアップロードしたい場合に利用します）。
• GET /v2/file/{file_id} — file_idを使用してファイルをダウンロードします。
• DELETE /v2/file/{file_id} — 不要になったファイルを削除します。

ファイルが有効なSTL、3MF、OBJモデルでない場合、またはプラットフォームのファイルサイズ上限（既定50MB）を超える場合、アップロードは拒否されます。両方のアップロードルートで同じ検査が適用されます。

ファイルの保存方法

アップロードされたモデルは暗号化されて保存され、公開されることはありません。保存されたファイルを直接配信するリンクは存在しません。レスポンスに含まれる file_path フィールドは、ディスク上の場所ではなく、認証済みのダウンロードパス (GET /v2/file/{file_id}) です。そのため、共有可能な URL ではなく、エンドポイントとして扱ってください。ファイルを削除すると、リストからだけでなく、ストレージからも削除されます。

4. 部品情報と技術分析

モデルが印刷可能かどうかを確認し、部品寸法と高度なテクニカルメトリクスを取得します:

• POST /v2/printability/{file_id} インスタント分析 – 見積もりを生成する前に、寸法、体積、表面積、幾何学的整合性（オープンエッジ/非多様体）を確認します。

Quote3Dは単なる寸法確認に留まりません。モデルの多様体（manifold）としての整合性を分析し、3Dプリントにおいて重要な定着リスクを評価します。これらのメトリクスは、PrintabilityとQuoteの両方のレスポンスで提供されます。

5. 見積もり操作

3Dプリントの見積もりを即座に生成し、見積もり履歴を管理します。

• POST /v2/file/quote/{file_id} — 3Dモデルの非同期見積もり計算を開始します。ジョブIDを返します。ジョブエンドポイントを使用して、完了した結果を取得してください。
• POST /v2/file/quote/{file_id}/async — 別の非同期見積もりエンドポイントです。ステータスを確認し、完了した結果を取得するために使用できるジョブIDを返します。
• GET /v2/jobs/{job_id} — 非同期見積もりジョブのステータスを確認します。進捗率と完了ステータスを返します。
• GET /v2/quotes — ページネーションをサポートして、すべての見積もり履歴を取得します。
• GET /v2/quotes/{quote_id} — 特定の見積もりの詳細情報を取得します。
• DELETE /v2/quotes/{quote_id} — 履歴から見積もりを削除します。

見積もりリクエストパラメータ

見積もりを生成する際に、リクエストボディでカスタム構成を指定できます。指定しないパラメータはすべて、ダッシュボードのスライスプロファイル設定から自動的に取得されます。これにより、他の設定をデフォルトのままにして、見積もりごとに特定の設定を上書きできます。

以下の表は、連携で最も頻繁に上書きされるパラメータを扱っています。これは全リストではありません — 見積もりエンジンはさらに多くのプリンター、材料、価格関連フィールドを受け付け、そのいずれもリクエストごとに送る代わりにダッシュボードのスライスプロファイルで一度設定できます。プロファイルをそこで構成し、見積もりごとに変わる項目だけを送ってください。完全なフィールド一覧はOpenAPIスキーマにあります。

Request Validation

printer_config、material_config、quote_config の数値フィールドは、ジョブがキューに入る前に範囲チェックされます。範囲外の値、有限でない数値（NaN、Infinity）、誤った型、あるいはゼロ以上のみが意味を持つ箇所での負の値は、HTTP 400 と該当フィールド名を含む VALIDATION_ERROR で拒否されます。意味を持つ箇所では 0 も引き続き受け付けられます。ロールごとの速度や加速度の 0 は「プリンターの既定値を使用する」という意味で、OrcaSlicer と同じ規約です。

• 温度の制限: 材料の温度（temperature と bed_temperature。リクエストで送信された場合も、材料プロファイルから読み込まれた場合も対象）は、プリンターの min_hotend_temp / max_hotend_temp および min_bed_temp / max_bed_temp と照合されます。選択したプリンターが供給できる以上の熱を必要とする材料は、見積もりされずに拒否されます。FDM のみが対象です。レジンおよびパウダー系のテクノロジーにはノズルもヒートベッドもありません。プリンター側の制限を未設定のままにすると、このチェックは省略されます。
• 有効なテクノロジー: グローバル設定でテクノロジーを制限している場合、無効化されたテクノロジーに対する見積もりリクエストは拒否されます。この設定を空のままにすると、3 種類すべてが受け付けられます。
• 材料価格のフィールド: 課金に使われる値は price_per_gram です。材料プロファイルを保存すると price_per_kg がそこから自動的に再計算され（キログラム単価のみを指定した場合は price_per_gram が price_per_kg から算出されます）、両者が食い違うことはありません。

ルートパラメータ

数量とバッチ生産のロジック

当社のシステムは、指定された'quantity'に基づいて高度なパッキングアルゴリズムを使用します。

• FDMテクノロジー：パーツは、スペースがある限り、造形板（X軸とY軸）に並べて配置されます。
• SLAテクノロジー：パーツは、レジン槽（X軸とY軸）に並べて配置されます。
• SLSテクノロジー：パーツは、粉末ベッドの容量を最大限に活用するために、すべての軸（X、Y、Z）に積み重ねることができます。

printer_config

プリンター構成パラメータ。すべてのフィールドはオプションであり、指定しない場合はデフォルトのプリンタープロファイルの値が使用されます。

material_config

マテリアル構成パラメータ。すべてのフィールドはオプションであり、指定しない場合はデフォルトのマテリアルプロファイルの値が使用されます。

quote_config

見積価格の構成パラメータ。すべてのフィールドはオプションであり、指定しない場合はデフォルトのグローバル設定の値が使用されます。通貨はデフォルトでダッシュボードの設定になります（例：'USD'、'TRY'、'EUR'）。

6. プリンターと見積もりプロファイル

正確な見積もりを得るために、プリンターの設定と価格を設定します。APIリクエストでパラメータを指定しない場合に自動的に使用されるデフォルトプロファイルは、ダッシュボードのスライスプロファイルセクションで管理できます。

プロファイルタイプ

• プリンタープロファイル - ベッドサイズ、ノズル径、印刷速度、レイヤー高さ、加速度、ジャーク、温度など、実際のプリンターに一致するようにプリンター設定を構成します。これをダッシュボードでデフォルトプロファイルとして設定すると、特定のパラメータを上書きしない限り、すべての見積もりリクエストに使用されます。
• マテリアルプロファイル - 使用する各マテリアルの材料特性（フィラメントタイプ、密度、直径、温度、ファン速度、リトラクション設定、価格）を設定します。APIは、リクエストで指定したfilament_typeに一致するマテリアルプロファイルを自動的に使用します。
• グローバル設定 - 税率、固定料金、エネルギーコスト、デフォルトの通貨など、グローバルな見積もり設定を構成します。これらの設定は、リクエストで上書きされない限り、すべての見積もりに適用されます。

プロファイルのマージ方法

見積もりリクエストを行うと、APIは次の優先順位でリクエストパラメータとダッシュボードプロファイルをマージします。

1. リクエストパラメータ - APIリクエストで明示的に提供する値が最優先されます
2. ユーザープロファイル - ユーザー固有のプロファイルをデフォルトとして設定している場合、次にそれが使用されます
3. グローバルプロファイル - ユーザープロファイルが存在しない場合、システムはグローバルデフォルトにフォールバックします

つまり、ダッシュボードプロファイルの設定を維持しながら、必要なパラメータ（例：layer_heightまたはfill_densityのみ）を上書きできます。

7. Webhooks

アカウントでイベントが発生したときにリアルタイム通知を受け取ります:

• POST /v2/webhooks - 新しいWebhookエンドポイントを作成
• GET /v2/webhooks - すべてのWebhookをリスト表示
• GET /v2/webhooks/{webhook_id} - Webhookの詳細と配信統計を取得
• PUT /v2/webhooks/{webhook_id} - Webhook設定を更新
• DELETE /v2/webhooks/{webhook_id} - Webhookを削除

サポートされているイベント: quote.completed, quote.failed, file.uploaded, file.deleted, job.status_changed, widget.added_to_cart. Webhookには、セキュリティ検証のためのHMAC-SHA256署名が含まれています。

Webhookリファレンス：ペイロード構造、署名検証、再試行、再配信

8. 分析とレポート

APIの使用状況と見積もり統計に関する分析情報をご覧ください。

• GET /v2/analytics/quotes - 総見積もり数、平均価格、材料使用量の傾向など、包括的な見積もり統計を取得できます。
• GET /v2/analytics/popular - 最も人気のある材料とプリンター構成を確認できます。
• GET /v2/analytics/cost-trends - 日次、週次、または月次でグループ化して、経時的なコストトレンドを分析します。
• GET /v2/analytics/export - 見積もりと使用状況データをCSVまたはJSON形式でエクスポートします。

9. レート制限とクォータ

Quote3Dは、公平な利用とシステム安定性を確保するためにレート制限を使用しています。

• レート制限はAPIトークンごとに適用され、エンドポイントによって異なります
• レート制限の情報は、レスポンスヘッダーに含まれています。 X-RateLimit-Limit, X-RateLimit-Remaining, X-RateLimit-Reset, X-RateLimit-Window
• レート制限に達すると、Retry-Afterヘッダーとともに429 Too Many Requestsレスポンスが返されます。
• 見積もりとストレージの月間クォータは、お客様のサブスクリプションプランに基づいています
• 上限はデプロイごとに設定可能なので、ハードコードせず現在の値を読み取ってください。上記のレスポンスヘッダーとこのエンドポイントの両方が値を返します： GET /v2/quota

10. レスポンスとエラー

すべてのJSONレスポンスは同じエンベロープを使用します。成功した呼び出しはsuccess: trueを返し、エンドポイントのペイロードはdataの下に入るため、クライアントはどこでも一貫した構造を読めます。ファイルのダウンロードとCSVエクスポートは例外で、エンベロープではなく生のファイル本文を返します。

{
  "success": true,
  "data": { "...": "endpoint-specific payload" }
}

ページネーションと並べ替え

/v2/quotesや/v2/user/uploadsなどの一覧エンドポイントは、limitとoffsetクエリパラメータでページ分割されます（既定50件、最大100件）。結果と併せてtotal、limit、offset、has_more、page、total_pagesを含むpaginationオブジェクトを返すので、自分で末尾を計算せずhas_moreを使ってください。並べ替えはfield:direction形式の反復可能な単一パラメータを使います。例：?sort=created_at:desc&sort=total_price:asc。アップロードは既定で新しい順です。

エラーレスポンス

失敗時はsuccess: falseと人が読めるエラーメッセージ、対応するHTTPステータスコードを返します。文面は変更される可能性があるため、メッセージ本文ではなく必ずステータスコードで分岐してください。

非同期見積もりは異なります。ジョブの投入は202で成功し、その後に失敗した計算はHTTPエラーではなく、ジョブエンドポイント上でエラーメッセージを伴うfailedステータスとして現れます。開始時に得たステータスコードだけでなく、必ずジョブのステータスを確認してください。

11. RESTfulでバージョン管理されたAPI

• すべてのエンドポイントはバージョン管理されています (例: /v2/)
• 標準的なHTTPメソッドを使用します: GET, POST, PUT, DELETE
• 独自ツールにインポートできるOpenAPI 3.0.3スキーマで記述されています
• 破壊的変更と追加は次に記録されます： API変更履歴