Fırsatlar API’si

Bir fırsat, Satış Hunisi 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)
Hatalar ve sayfalama — bkz. Hatalar ve Sayfalama

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

{
  "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ı 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

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

Yanıt (200)

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

Bir fırsatı getir

GET /deals/{dealId}

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

Yanıt (200)

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

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)

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

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.

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.

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ı.

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

Yanıt (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" }
        ]
      }
    ]
  }
}

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").

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 — aşamaların, aşama etiketlerinin, birden fazla huninin ve panonun nasıl çalıştığı.
Görevler API’si — görevler deal_id ile bir anlaşmaya bağlanabilir.
Otomasyonlar — Anlaşmaları bul ve Anlaşma bul adımları, bir iş akışı içindeki aynı verileri okur.

Fırsatlar API’si #

Fırsat nesnesi #

Fırsatları listele #

Bir fırsatı getir #

Bir fırsat oluştur #

Bir fırsatı güncelle #

Bir anlaşmayı başka bir aşamaya taşıma #

Bir anlaşmayı silme #

İşlem Hatları #

İşlem hatlarını listele #

Bir işlem hattı oluştur #

Bir işlem hattını güncelle #

Bir işlem hattını sil #

Sonraki adımlar #