基本概念

クイックスタートで紹介した用語をさらに詳しく見ていきます。

1. API

プログラム間でデータをやり取りするための通信プロトコルです。

3Min APIでは：

• バックエンドコードなしでAPIを作成
• 標準的なJSONデータを受信
• データは自動的に保存され、Webhookで転送可能

2. エンドポイント

データを受信するAPIアドレスです。1つのAPI = 1つのエンドポイント。

各エンドポイントに含まれるもの：

• 固有のURLパス（自動生成）
• 必須フィールド（任意）
• サンドボックス/本番環境の分離
• 環境別APIキー (tm_test_xxx..., tm_live_xxx...)

3. JSON

3Min APIは標準的なJSONデータを受け付けます。

対応フィールドタイプ：

例（注文情報）：

{
  "order_id": "ORD-2024-001",
  "amount": 45000,
  "items": ["Item A", "Item B"],
  "paid": true,
  "customer": {
    "name": "John Doe",
    "phone": "010-1234-5678"
  }
}

4. 必須フィールド（任意設定）

JSONデータに必ず含めるべきフィールドを指定できます。

必須フィールドを設定すると：

• 必須フィールドが不足しているリクエストは拒否されます（400エラー）
• データ品質を確保できます
• 文字列フィールドはログで検索可能に設定できます

5. サンドボックス vs 本番

• 環境はAPIキーのプレフィックスで判別されます
• Webhookは環境ごとに個別設定が可能です
• 本番にデプロイする前にサンドボックスで十分にテストしてください

6. APIキー

エンドポイント呼び出し時の認証に使用します。オーナーのデフォルトAPIキーはエンドポイント作成時に自動生成され、削除できません。キーが漏洩した場合は再生成できます。

コラボレーションキー

コラボレーションキーを作成し、協力者を招待して、コラボレーションキーごとにログと統計を個別に管理できます。

コラボレーションキーでログをフィルタリングして、コラボレーションキーごとの利用状況を追跡できます。

コラボレーションキーごとに許可する操作（POST/GET/PUT/DELETE）を環境別に個別設定できます。

7. Webhook

データが到着した際に、指定したURLに自動通知を送信します。

2種類のWebhook：

リトライポリシー：失敗時に最大3回リトライ（60秒間隔）

注意：すべてのWebhookリトライが失敗しても、データは安全に保存されています。ログでWebhookのステータスを確認してください。

8. イベント通知（Discord / Slack / Telegram）

Discord、Slack、またはTelegramで重要なイベントの即時通知を受信できます。

設定：ダッシュボード → API → エンドポイント詳細 → 通知設定

対応イベント：

• Webhook配信失敗（該当者のみに通知）
• 月間使用量80%警告（オーナーのみ）
• 月間使用量上限超過（オーナーのみ）
• 新しいデプロイリクエスト（オーナーのみ）
• デプロイ完了（協力者のみ）

注意：通知はベストエフォートです。配信失敗時のリトライや通知履歴の保存は行われません。

9. データアーカイブ

本番データは30日後に自動的にアーカイブされます。アーカイブされたレコードのメタデータ（ステータス、タイムスタンプ、Webhook結果など）は保持され、ペイロード（本文データ）は別のストレージに移動されます。

環境別ポリシー：

アーカイブ後：

• レコードはログ一覧に引き続き表示されます（メタデータ保持）
• ペイロード検索は直近30日間に限定されます
• 個々のレコードのペイロードは「原本を表示」から閲覧可能です

アーカイブのダウンロード：

• 場所：ダッシュボード > アーカイブ
• JSONL.gz：すべてのシステムフィールドを含む完全なレコード（生アーカイブ）
• CSV：ペイロードフィールドのみ、再帰的にフラット化（最大深度5）、Excel互換（UTF-8 BOM）
• 各ファイルには1日分の本番レコードが含まれます
• 有料プランのみ利用可能