コアコンセプト: ファイル、見積もり、ジョブ

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 エンドポイント統計、材料の使用量、および時間ベースのトレンドを含む、詳細な使用状況分析を取得
• GET /v2/config アカウントで有効なテクノロジー、プリンター、色 (在庫の有無を含む) 付きの材料、価格の既定値など、ウィジェットが提供する内容です。ウィジェット用トークンでも読み取れます。

3. ファイル管理

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

• 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、STEP モデルでない場合、またはプラットフォームのファイルサイズ上限 (既定50MB) を超える場合、アップロードは拒否されます。STEP ファイル (.step/.stp) はサーバー上で OrcaSlicer と同じ設定 (線形偏差0.003 mm、角度偏差0.5 rad) でメッシュ化され、アセンブリのすべてのボディが統合され、長さはミリメートルに換算されます。両方のアップロードルートで同じ検査が適用されます。

ファイルの保存方法

アップロードされたモデルは暗号化されて保存され、公開されることはありません。保存されたファイルを直接配信するリンクは存在しません。レスポンスに含まれる 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 のみが対象です。レジンおよびパウダー系のテクノロジーにはノズルもヒートベッドもありません。プリンター側の制限を未設定のままにすると、このチェックは省略されます。
• 有効なテクノロジー: グローバル設定でテクノロジーを制限している場合、無効化されたテクノロジーに対する見積もりリクエストは拒否されます。この設定を空のままにすると、すべてのテクノロジーが受け付けられます。
• 材料価格のフィールド: 課金に使われる値は 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 を削除
• POST /v2/webhooks/{webhook_id}/deliveries/{delivery_id}/resend - 過去の配信を再送します。たとえばエンドポイントを修正した後に使います

サポートされているイベント: quote.completed, quote.failed, file.uploaded, file.deleted, job.status_changed, widget.added_to_cart, usage.alert. 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. カタログと在庫

サーバートークンで、アカウント独自のプリンター、材料、色、色ごとの在庫、価格設定、テクノロジーを管理します。ウィジェットは同じカタログを読むため、変更はすぐに見積フォームに反映されます。ウィジェット用トークンは拒否され、これらの呼び出しは月間リクエスト枠に数えられません:

• GET /v2/store/catalog - アカウントが提供するすべての内容。テクノロジーごとの準備状況と残り少ない色を含みます
• GET /v2/store/catalog/schema - ダッシュボードのプリンター・材料・価格設定フォーム。上下限、単位、指定言語のヘルプテキスト付き
• POST /v2/store/catalog/adopt - グローバルのプリンターと材料を、選んだ色・価格・初期在庫とともにアカウントへコピーします
• POST /v2/store/catalog/materials - 材料を作成します。グローバルの材料をもとにすることもできます
• GET · PATCH · DELETE /v2/store/catalog/materials/{id} - 材料を1件、在庫設定を含めて読み取り・変更・削除します
• PUT /v2/store/catalog/materials/{id}/colors - 材料の色一覧を置き換えます。既存の色の在庫は保持されます
• GET · PATCH · DELETE /v2/store/catalog/printers/{id} - プリンターを1台読み取り・変更・削除します
• GET · PATCH · DELETE /v2/store/catalog/pricing - 価格設定を読み取り・変更・リセットします。通貨を変えるとアカウントの通貨が変わり、金額は換算されません
• GET · PUT /v2/store/catalog/technologies - プランで使えるテクノロジーと、有効になっているテクノロジー
• GET · POST /v2/store/stock/movements - 入庫・棚卸し・廃棄を記録し、在庫履歴を一覧表示します
• POST /v2/store/stock/orders - 支払い済み注文の材料を差し引く・戻す・確認します。見積ごとに最大1回です

PATCH の本文には values と updated_at を含めます。values はカタログ一覧と同じ snake_case のフィールド名を使います (フォームにない名前は400で拒否されます)。読み取った後にプロファイルが変更されていた場合は、error_key stale とともに409が返ります。

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

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

• レート制限は API トークンごとに適用され、エンドポイントによって異なります
• レート制限の情報は、レスポンスヘッダーに含まれています。 X-RateLimit-Limit, X-RateLimit-Remaining, X-RateLimit-Reset, X-RateLimit-Window
• レート制限に達すると、Retry-After ヘッダーとともに429 Too Many Requests レスポンスが返されます。
• プランでは、請求期間ごとにリセットされる見積もり枠と、リセットされずファイルを削除したときにのみ空くストレージ枠が決まります
• 上限はデプロイごとに設定可能なので、ハードコードせず現在の値を読み取ってください。上記のレスポンスヘッダーとこのエンドポイントの両方が値を返します: GET /v2/quota

11. レスポンスとエラー

成功時のレスポンスには2つの形があります。見積、ジョブ、保存済み見積の詳細、Webhook、分析、使用量、クォータ、設定の呼び出しは、内容を success: true で包み、結果を data の下に置きます。ファイル、アップロード ID、ユーザー、アップロード一覧、見積一覧、印刷可能性、カタログと在庫の呼び出しは、フィールドを最上位で返します。各呼び出しの正確なスキーマは API リファレンスを参照してください。ファイルのダウンロードと 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。アップロードは既定で新しい順です。

エラーレスポンス

エラーはすべて同じ形です。パラメーターまたはフィールドを示す detail リスト (loc、msg、code)、AUTH_001のような error_code、error_summary、必要に応じて recovery_suggestions と documentation_url が含まれます。文言は変わる可能性があるため、HTTP ステータスと error_code で分岐してください。

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

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

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