API連携

API連携の技術仕様です。

1. ベースURL

エンドポイントURLはエンドポイント詳細ページに表示されます。

POST GET (list)

https://api.3minapi.com/api/v1/data/{slug}

GET (search)

https://api.3minapi.com/api/v1/data/{slug}/search

GET / PUT / DELETE

https://api.3minapi.com/api/v1/data/{slug}/{record_id}

2. 認証

ヘッダーにAPIキーを含めてください。

ヘッダー	説明	必須
Authorization	`Bearer tm_test_xxx...` / `Bearer tm_live_xxx...`	Yes
Content-Type	`application/json`	Yes
X-Webhook-Callback	Webhook URL	No
X-Webhook-Auth	認証値（例：Bearerトークン）	No
X-Webhook-Auth-Header	認証ヘッダー名	No

3. リクエスト形式

Content-Type: application/jsonのみ
最大サイズ: リクエストあたり100KB
メソッド: POST / GET（単件 + 一覧 + 検索） / PUT / DELETE

CRUDエンドポイント

各エンドポイントは以下のHTTPメソッドに自動対応します：

メソッド	パス	説明
`POST`	`/api/v1/data/{slug}`	新しいレコードを作成（非同期、キュー処理）
`GET`	`/api/v1/data/{slug}/{record_id}`	IDでレコードを取得
`GET`	`/api/v1/data/{slug}`	最近のレコード一覧取得（cursor ページネーション、ページあたりデフォルト10件 / 最大30件）
`GET`	`/api/v1/data/{slug}/search`	payload テキスト検索（q 必須、期間は任意 — 未指定時は直近30日、カーソルページネーション）
`PUT`	`/api/v1/data/{slug}/{record_id}`	IDでレコードを置換（非同期、キュー処理）
`DELETE`	`/api/v1/data/{slug}/{record_id}`	IDでレコードを削除（非同期、キュー処理）

GET（単件）、PUT、DELETEには、以前のPOSTレスポンスで返されたレコードIDが必要です。GET（一覧）と GET（検索）はレコードIDが不要です。

POST — 作成:

curl -X POST https://api.3minapi.com/api/v1/data/{slug} \
  -H "Authorization: Bearer tm_test_xxx" \
  -H "Content-Type: application/json" \
  -d '{
  "order_id": "ORD-2024-001",
  "amount": 45000,
  "items": ["Item A", "Item B"],
  "paid": true
}'

GET — 読み取り:

curl https://api.3minapi.com/api/v1/data/{slug}/rec_abc123 \
  -H "Authorization: Bearer tm_test_xxx"

GET — 一覧:

curl "https://api.3minapi.com/api/v1/data/{slug}?limit=10" \
  -H "Authorization: Bearer tm_test_xxx"

# Next page — pass the next_cursor returned in the previous response
curl "https://api.3minapi.com/api/v1/data/{slug}?limit=10&cursor=<next_cursor>" \
  -H "Authorization: Bearer tm_test_xxx"

GET — 検索:

# q is required (min 3 chars). start/end are optional — defaults to last 30 days.
curl "https://api.3minapi.com/api/v1/data/{slug}/search?q=keyword&limit=10" \
  -H "Authorization: Bearer tm_test_xxx"

# Next page — pass the next_cursor returned in the previous response
curl "https://api.3minapi.com/api/v1/data/{slug}/search?q=keyword&limit=10&cursor=<next_cursor>" \
  -H "Authorization: Bearer tm_test_xxx"

PUT — 更新:

curl -X PUT https://api.3minapi.com/api/v1/data/{slug}/rec_abc123 \
  -H "Authorization: Bearer tm_test_xxx" \
  -H "Content-Type: application/json" \
  -d '{
  "order_id": "ORD-2024-001",
  "amount": 50000,
  "items": ["Item A", "Item B", "Item C"],
  "paid": true
}'

DELETE — 削除:

curl -X DELETE https://api.3minapi.com/api/v1/data/{slug}/rec_abc123 \
  -H "Authorization: Bearer tm_test_xxx"

4. レスポンス形式

成功レスポンス（202）:

{
  "success": true,
  "id": "rec_abc123",
  "message": "Request queued"
}

エラーレスポンス例（400）:

{
  "success": false,
  "error": "Validation failed",
  "details": [
    { "field": "order_id", "error": "Required field is missing" }
  ]
}

エラーレスポンス:

Code	Status	Description
`400`	Bad Request	無効なJSONまたは必須フィールドの不足
`401`	Unauthorized	APIキーが不足・無効、またはオーナーによって無効化されたAPIキー
`403`	Forbidden	エンドポイントが無効、またはサブスクリプションが期限切れ
`415`	Unsupported Media Type	Content-Typeはapplication/jsonである必要があります
`429`	Too Many Requests	月間リクエスト上限を超過
`5xx`	Server Error	サーバー内部エラー（500、502、503など）

5. 協力者Webhook

API協力者が処理結果を直接受信できます。

リトライポリシー: 失敗時に最大3回リトライ（1〜2秒バックオフ）

6. テストツール

本番稼働前にサンドボックスでテストしてください。

組み込みテストページ: エンドポイント詳細ページのテストボタンからアクセス — 追加ツール不要
cURL: コマンドラインからテスト
Postman: APIテストツールを使用

7. 本番コンソール

本番にデプロイ後、エンドポイントオーナーは外部APIツールやコードなしで、ダッシュボードから直接本番データを管理できます。

アクセス方法

エンドポイント詳細 → 本番タブ → 「コンソールを開く」をクリックして新しいタブで開きます。

機能

本番データに対するフルCRUD対応（POST / GET / PUT / DELETE）
本番APIキーは自動的に設定済み — 手動入力は不要
コンソールからのリクエストはWebhookをトリガーしません

オーナー専用

本番コンソールにアクセスできるのはエンドポイントオーナーのみです。協力者は使用できません。