DM Champ Docs

API Penawaran (Deals)

Penawaran adalah satu peluang penjualan di papan Sales Pipeline Anda — terdiri dari judul, nilai, tahap di mana penawaran tersebut berada, serta opsional kontak pemiliknya dan anggota tim yang ditugaskan. Panduan ini mencakup cara membaca dan mengelola penawaran melalui API.

Semua contoh di bawah ini menunjukkan formulir kueri ?apiKey= dalam cURL dan header X-API-Key dalam JavaScript dan Python — keduanya berfungsi di setiap endpoint.

Objek penawaran 

{
  "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 adalah id dari salah satu tahap pipeline Anda — baca tahap tersebut dari pengaturan pipeline Anda (GET /users/me/pipeline-settings). Stempel waktu menggunakan format ISO 8601.

Mencantumkan penawaran

GET /deals — mengembalikan daftar penawaran di akun Anda, diurutkan dari yang terbaru.

Parameter kueri (semuanya opsional): stage (id tahap), contact_id, limit (default 50, maks 200), cursor (dari next_cursor halaman sebelumnya).

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"]

Respons (200)

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

Mendapatkan penawaran

GET /deals/{dealId}

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

Respons (200)

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

Penawaran yang tidak ada, atau milik akun lain, akan mengembalikan 404.

Membuat penawaran

POST /deals — title dan stage wajib diisi; stage harus berupa salah satu id tahap pipeline Anda.

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" }'

Respons (201)

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

Memperbarui penawaran

PUT /deals/{dealId} — kirimkan hanya kolom yang ingin Anda ubah (title, description, value, stage, status, priority, contact_id, …). value harus berupa angka.

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" }'

Respons (200): { "success": true, "deal_id": "deal_abc123" }

Memindahkan kesepakatan ke tahap lain

POST /deals/{dealId}/move — isi { "new_stage_id": "stage-3", "new_position": 0 }. Posisi 0 menempatkan kartu di bagian atas kolom.

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 }'

Respons (200): { "success": true, "deal_id": "deal_abc123", "stage": "stage-3", "position": 0 }

Menghapus kesepakatan

DELETE /deals/{dealId} — menghapus kesepakatan. Tindakan ini tidak dapat dibatalkan.

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

Respons (200): { "success": true }

Langkah berikutnya

  • Sales Pipeline — cara kerja tahap, tag tahap, dan papan kerja.
  • API Tugas — tugas dapat ditautkan ke kesepakatan dengan deal_id.
  • Otomatisasi — langkah Cari kesepakatan (Find deals) dan Cari kesepakatan (Find deal) membaca data yang sama di dalam alur kerja.