DM Champ Docs

取引 API

取引とは、セールスパイプラインボード上の1つの販売機会を指します。これには、タイトル、金額、現在のステージ、およびオプションとして関連付けられた連絡先や担当チームメンバーが含まれます。このガイドでは、APIを介した取引の読み取りと管理について説明します。

以下のすべての例では、cURLでの ?apiKey= クエリ形式と、JavaScriptおよびPythonでの X-API-Key ヘッダーを示しています。どちらの方法もすべてのエンドポイントで使用可能です。

取引オブジェクト 

{
  "id": "deal_abc123",
  "title": "Annual plan – Jane's Clinic",
  "description": "Asked for pricing on the annual plan.",
  "company": "Jane's Clinic",
  "stage": "stage-2",
  "value": 4800,
  "probability": 60,
  "priority": "high",
  "status": "open",
  "source": "whatsapp",
  "position": 0,
  "contact_id": "ctc_9f8e7d",
  "assigned_to": "usr_4a2b",
  "tags": ["clinic"],
  "close_date": "2026-10-01T00:00:00.000Z",
  "created_at": "2026-09-05T09:12:00.000Z",
  "updated_at": "2026-09-05T09:40:00.000Z",
  "stage_entered_at": "2026-09-05T09:40:00.000Z"
}

stage は、パイプラインステージのIDです。パイプライン設定（GET /users/me/pipeline-settings）から取得できます。タイムスタンプはISO 8601形式です。

取引の一覧取得

GET /deals — アカウント上の取引を新しい順に返します。

クエリパラメータ（すべて任意）: stage（ステージID）、contact_id、limit（デフォルトは50、最大200）、cursor（前のページの next_cursor から）。

cURL

curl "https://api.dmchamp.com/v1/deals?apiKey=YOUR_API_KEY&stage=stage-2&limit=50"

JavaScript

const res = await fetch("https://api.dmchamp.com/v1/deals?stage=stage-2&limit=50", {
  headers: { "X-API-Key": "YOUR_API_KEY" },
});
const { deals, next_cursor } = await res.json();

Python

res = requests.get(
    "https://api.dmchamp.com/v1/deals",
    headers={"X-API-Key": "YOUR_API_KEY"},
    params={"stage": "stage-2", "limit": 50},
)
deals = res.json()["deals"]

レスポンス (200)

{ "success": true, "deals": [{ "id": "deal_abc123", "title": "Annual plan – Jane's Clinic", "...": "..." }], "next_cursor": null }

取引を取得する

GET /deals/{dealId}

curl "https://api.dmchamp.com/v1/deals/deal_abc123?apiKey=YOUR_API_KEY"

レスポンス (200)

{ "success": true, "deal": { "id": "deal_abc123", "title": "Annual plan – Jane's Clinic", "...": "..." } }

存在しない取引、または別のアカウントに属する取引を指定した場合、404 が返されます。

取引を作成する

POST /deals — title と stage は必須です。stage には、パイプラインのステージIDのいずれかを指定する必要があります。

curl -X POST "https://api.dmchamp.com/v1/deals?apiKey=YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{ "title": "Annual plan – Jane'"'"'s Clinic", "stage": "stage-1", "value": 4800, "contact_id": "ctc_9f8e7d" }'

レスポンス (201)

{ "success": true, "deal_id": "deal_abc123" }

取引を更新する

PUT /deals/{dealId} — 変更したいフィールドのみを送信してください（title、description、value、stage、status、priority、contact_id など）。value は数値である必要があります。

curl -X PUT "https://api.dmchamp.com/v1/deals/deal_abc123?apiKey=YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{ "value": 5200, "priority": "high" }'

レスポンス (200): { "success": true, "deal_id": "deal_abc123" }

取引を別のステージに移動する

POST /deals/{dealId}/move — 本文 { "new_stage_id": "stage-3", "new_position": 0 }。位置 0 はカードを列の最上部に配置します。

curl -X POST "https://api.dmchamp.com/v1/deals/deal_abc123/move?apiKey=YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{ "new_stage_id": "stage-3", "new_position": 0 }'

レスポンス (200): { "success": true, "deal_id": "deal_abc123", "stage": "stage-3", "position": 0 }

取引を削除する

DELETE /deals/{dealId} — 取引を削除します。この操作は元に戻せません。

curl -X DELETE "https://api.dmchamp.com/v1/deals/deal_abc123?apiKey=YOUR_API_KEY"

レスポンス (200): { "success": true }

次のステップ

  • セールスパイプライン — ステージ、ステージタグ、ボードの仕組みについて。
  • タスクAPI — タスクは deal_id を使用して取引にリンクできます。
  • 自動化 — 取引の検索および取引を検索ステップは、ワークフロー内で同じデータを読み取ります。