# API Penawaran (Deals)

Penawaran adalah satu peluang penjualan di papan [Sales Pipeline](../deals/sales-pipeline.md) 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](authentication.md))
- **Kesalahan & penomoran halaman** — lihat [Kesalahan & Penomoran Halaman](errors-and-pagination.md)

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

```json
{
  "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](#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**

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

**JavaScript**

```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**

```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`)

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

---

## Mendapatkan penawaran

`GET /deals/{dealId}`

```bash
curl "https://api.youraiconnector.com/v1/deals/deal_abc123?apiKey=YOUR_API_KEY"
```

**Respons** (`200`)

```json
{ "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.

```bash
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`)

```json
{ "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.

```bash
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.

```bash
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.**

```bash
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.

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

**Respons** (`200`):

```json
{
  "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"`).

```bash
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](../deals/sales-pipeline.md) — cara kerja tahapan, tag tahapan, beberapa pipeline, dan papan.
- [Tasks API](tasks.md) — tugas dapat ditautkan ke kesepakatan dengan `deal_id`.
- [Automations](../automations/automations.md) — langkah **Find deals** dan **Find deal** membaca data yang sama di dalam alur kerja.