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.

URL Dasar — https://api.youraiconnector.com/v1
Autentikasi — kunci API Anda (lihat Autentikasi)
Kesalahan & penomoran halaman — lihat Kesalahan & Penomoran Halaman

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",
  "notes": "Prefers a call after 5pm.",
  "stage": "stage-2",
  "pipeline_id": "default",
  "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 dengan GET /pipelines (lihat Pipelines di bawah). Id tahap bersifat unik di semua pipeline Anda, jadi pipeline_id diturunkan dari tahap tersebut dan bersifat hanya-baca: default adalah pipeline utama Anda, dan nilainya adalah null ketika tahap tersebut tidak lagi ada. Stempel waktu menggunakan format ISO 8601.

Kesepakatan hanya menyimpan kolom-kolom yang ditampilkan di atas. Saat Anda membuat atau memperbarui kesepakatan, kolom lain apa pun akan ditolak dengan 400 yang menyebutkan nama kolom tersebut, sehingga tidak ada data yang Anda kirim akan hilang tanpa pemberitahuan. Simpan data tambahan pada kolom kustom kontak yang ditautkan.

Mencantumkan penawaran

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

Parameter kueri (semua opsional): stage (id tahap), pipeline_id (hanya kesepakatan pada pipeline tersebut), contact_id, limit (default 50, maks 200), cursor (dari next_cursor halaman sebelumnya).

cURL

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

JavaScript

const res = await fetch("https://api.youraiconnector.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.youraiconnector.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.youraiconnector.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.youraiconnector.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} — kirim hanya kolom yang ingin Anda ubah (title, description, notes, value, stage, status, priority, contact_id, …). value harus berupa angka.

curl -X PUT "https://api.youraiconnector.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.youraiconnector.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.youraiconnector.com/v1/deals/deal_abc123?apiKey=YOUR_API_KEY"

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

Pipelines

Setiap akun memiliki pipeline utama (id: "default"); Anda dapat menambahkan hingga sembilan pipeline lagi, masing-masing dengan tahapannya sendiri. Id tahap dan tag pemicu harus unik di semua pipeline pada akun tersebut, dan setiap pipeline dapat menandai satu tahap sebagai won dan satu tahap sebagai hasil lost.

Daftar pipeline

GET /pipelines — setiap pipeline, dimulai dari yang utama, masing-masing dengan tahapan yang diurutkan berdasarkan posisi.

curl "https://api.youraiconnector.com/v1/pipelines?apiKey=YOUR_API_KEY"

Respons (200):

{
  "success": true,
  "data": {
    "pipelines": [
      {
        "id": "default",
        "name": "Sales",
        "position": 0,
        "is_default": true,
        "settings": { "sync_stage_tags": false },
        "stages": [
          { "id": "stage-1", "name": "New lead", "color": "#3B82F6", "position": 0, "trigger_tag": null },
          { "id": "won", "name": "Won", "color": "#10B981", "position": 1, "outcome": "won" }
        ]
      }
    ]
  }
}

Membuat pipeline

POST /pipelines — body { "id"?, "name", "stages"?, "settings"? }. Kosongkan id agar id dibuatkan secara otomatis. Setiap tahap menggunakan bidang yang sama dengan dialog Tahapan: id, name, color, position, opsional trigger_tag (jalur tag, users/{uid}/tags/{tagId}), default_value, auto_move_after_days + auto_move_to_stage (tahap dari pipeline yang sama) dan outcome ("won" atau "lost").

curl -X POST "https://api.youraiconnector.com/v1/pipelines?apiKey=YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "id": "reviews",
    "name": "Review requests",
    "stages": [
      { "id": "rv_asked", "name": "Asked", "color": "#3B82F6", "position": 0 },
      { "id": "rv_done", "name": "Review posted", "color": "#10B981", "position": 1, "outcome": "won" }
    ]
  }'

Respons (201): { "success": true, "data": { "pipeline": { ... } } }. Id tahap atau tag pemicu yang sudah digunakan oleh pipeline lain akan menghasilkan 400 yang menyebutkan pipeline tersebut; id yang sudah ada akan menghasilkan 409.

Memperbarui pipeline

PUT /pipelines/{pipelineId} — body { "name"?, "stages"?, "settings"? }. stages menggantikan seluruh daftar, seperti pada dialog Tahapan. Gunakan default untuk pipeline utama. Id pipeline itu sendiri tidak dapat diubah.

Menghapus pipeline

DELETE /pipelines/{pipelineId} — menghapus pipeline tambahan (pipeline utama tidak dapat dihapus). Jika masih ada kesepakatan di tahapannya, panggilan akan menjawab 409 dengan deal_count; tambahkan ?delete_deals=true untuk menghapus kesepakatan tersebut bersama dengan pipeline-nya. Tindakan ini tidak dapat dibatalkan.

Respons (204).

Langkah berikutnya

Sales Pipeline — cara kerja tahapan, tag tahapan, beberapa pipeline, dan papan.
Tasks API — tugas dapat ditautkan ke kesepakatan dengan deal_id.
Automations — langkah Find deals dan Find deal membaca data yang sama di dalam alur kerja.

API Penawaran (Deals) #

Objek penawaran #

Mencantumkan penawaran #

Mendapatkan penawaran #

Membuat penawaran #

Memperbarui penawaran #

Memindahkan kesepakatan ke tahap lain #

Menghapus kesepakatan #

Pipelines #

Daftar pipeline #

Membuat pipeline #

Memperbarui pipeline #

Menghapus pipeline #

Langkah berikutnya #