# Fırsatlar API'si Bir fırsat, [Satış Hunisi](../deals/sales-pipeline.md) panonuzdaki bir satış fırsatıdır; bir başlık, bir değer, bulunduğu aşama ve isteğe bağlı olarak ait olduğu kişi ve atandığı ekip üyesinden oluşur. Bu kılavuz, API üzerinden fırsatların okunmasını ve yönetilmesini kapsar. - **Temel URL** — `https://api.youraiconnector.com/v1` - **Kimlik Doğrulama** — API anahtarınız (bkz. [Kimlik Doğrulama](authentication.md)) - **Hatalar ve sayfalama** — bkz. [Hatalar ve Sayfalama](errors-and-pagination.md) Aşağıdaki tüm örnekler cURL'de `?apiKey=` sorgu biçimini ve JavaScript ile Python'da `X-API-Key` başlığını göstermektedir; her ikisi de her uç noktada çalışır. --- ## Fırsat nesnesi ```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`, işlem hattı aşamalarınızdan birinin kimliğidir — bunları `GET /pipelines` ile okuyun (aşağıdaki [İşlem Hatları](#pipelines) bölümüne bakın). Aşama kimlikleri tüm işlem hatlarınızda benzersizdir, bu nedenle `pipeline_id` aşamadan türetilir ve salt okunurdur: `default` ana işlem hattınızdır ve aşama artık mevcut olmadığında `null` olur. Zaman damgaları ISO 8601 formatındadır. Bir anlaşma yalnızca yukarıda gösterilen alanları saklar. Bir anlaşma oluşturduğunuzda veya güncellediğinizde, diğer tüm alanlar bunu belirten bir `400` ile reddedilir, böylece gönderdiğiniz hiçbir şey sessizce kaybolmaz. Ek verileri bağlantılı kişinin özel alanlarında tutun. --- ## Fırsatları listele `GET /deals` — hesabınızdaki fırsatları, en yeniden başlayarak döndürür. **Sorgu parametreleri** (hepsi isteğe bağlıdır): `stage` (bir aşama kimliği), `pipeline_id` (yalnızca o işlem hattındaki anlaşmalar), `contact_id`, `limit` (varsayılan 50, maksimum 200), `cursor` (önceki sayfanın `next_cursor` değerinden). **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"] ``` **Yanıt** (`200`) ```json { "success": true, "deals": [{ "id": "deal_abc123", "title": "Annual plan – Jane's Clinic", "...": "..." }], "next_cursor": null } ``` --- ## Bir fırsatı getir `GET /deals/{dealId}` ```bash curl "https://api.youraiconnector.com/v1/deals/deal_abc123?apiKey=YOUR_API_KEY" ``` **Yanıt** (`200`) ```json { "success": true, "deal": { "id": "deal_abc123", "title": "Annual plan – Jane's Clinic", "...": "..." } } ``` Var olmayan veya başka bir hesaba ait olan bir fırsat, `404` döndürür. --- ## Bir fırsat oluştur `POST /deals` — `title` ve `stage` zorunludur; `stage`, satış huninizin aşama kimliklerinden biri olmalıdır. ```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" }' ``` **Yanıt** (`201`) ```json { "success": true, "deal_id": "deal_abc123" } ``` --- ## Bir fırsatı güncelle `PUT /deals/{dealId}` — yalnızca değiştirmek istediğiniz alanları gönderin (`title`, `description`, `notes`, `value`, `stage`, `status`, `priority`, `contact_id`, …). `value` bir sayı olmalıdır. ```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" }' ``` **Yanıt** (`200`): `{ "success": true, "deal_id": "deal_abc123" }` --- ## Bir anlaşmayı başka bir aşamaya taşıma `POST /deals/{dealId}/move` — gövde `{ "new_stage_id": "stage-3", "new_position": 0 }`. `0` konumu, kartı sütunun en üstüne yerleştirir. ```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 }' ``` **Yanıt** (`200`): `{ "success": true, "deal_id": "deal_abc123", "stage": "stage-3", "position": 0 }` --- ## Bir anlaşmayı silme `DELETE /deals/{dealId}` — anlaşmayı kaldırır. **Bu işlem geri alınamaz.** ```bash curl -X DELETE "https://api.youraiconnector.com/v1/deals/deal_abc123?apiKey=YOUR_API_KEY" ``` **Yanıt** (`200`): `{ "success": true }` --- ## İşlem Hatları Her hesabın bir ana işlem hattı (`id: "default"`) vardır; her biri kendi aşamalarına sahip dokuz tane daha ekleyebilirsiniz. Aşama kimlikleri ve tetikleyici etiketler, hesaptaki tüm işlem hatlarında benzersiz olmalıdır ve her işlem hattı bir aşamayı `won` ve bir aşamayı `lost` sonucu olarak işaretleyebilir. ### İşlem hatlarını listele `GET /pipelines` — her biri aşamaları konuma göre sıralanmış şekilde, ana işlem hattı ilk sırada olmak üzere tüm işlem hatları. ```bash curl "https://api.youraiconnector.com/v1/pipelines?apiKey=YOUR_API_KEY" ``` **Yanıt** (`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" } ] } ] } } ``` ### Bir işlem hattı oluştur `POST /pipelines` — gövde `{ "id"?, "name", "stages"?, "settings"? }`. Bir tane oluşturulması için `id` kısmını boş bırakın. Her aşama, Aşamalar iletişim kutusuyla aynı alanları alır: `id`, `name`, `color`, `position`, isteğe bağlı `trigger_tag` (bir etiket yolu, `users/{uid}/tags/{tagId}`), `default_value`, `auto_move_after_days` + `auto_move_to_stage` (aynı işlem hattının bir aşaması) ve `outcome` (`"won"` veya `"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" } ] }' ``` **Yanıt** (`201`): `{ "success": true, "data": { "pipeline": { ... } } }`. Başka bir işlem hattı tarafından zaten kullanılan bir aşama kimliği veya tetikleyici etiket, o işlem hattını adlandıran bir `400` hatasıdır; zaten var olan bir kimlik ise bir `409` hatasıdır. ### Bir işlem hattını güncelle `PUT /pipelines/{pipelineId}` — gövde `{ "name"?, "stages"?, "settings"? }`. `stages`, Aşamalar iletişim kutusunda olduğu gibi listenin tamamını değiştirir. Ana işlem hattı için `default` kullanın. İşlem hattının kimliği değiştirilemez. ### Bir işlem hattını sil `DELETE /pipelines/{pipelineId}` — fazladan bir işlem hattını kaldırır (ana işlem hattı silinemez). Eğer aşamalarında hala anlaşmalar varsa, çağrı `deal_count` ile `409` yanıtını verir; bu anlaşmaları işlem hattıyla birlikte silmek için `?delete_deals=true` ekleyin. **Bu işlem geri alınamaz.** **Yanıt** (`204`). --- ## Sonraki adımlar - [Satış Hunisi](../deals/sales-pipeline.md) — aşamaların, aşama etiketlerinin, birden fazla huninin ve panonun nasıl çalıştığı. - [Görevler API'si](tasks.md) — görevler `deal_id` ile bir anlaşmaya bağlanabilir. - [Otomasyonlar](../automations/automations.md) — **Anlaşmaları bul** ve **Anlaşma bul** adımları, bir iş akışı içindeki aynı verileri okur.