# Görevler API'si

Görevler, hesabınıza eklenmiş yapılacak işler ve takiplerdir; isteğe bağlı olarak bir kişi, anlaşma veya kampanya ile ilişkilendirilebilirler. Görev panonuzun (kanban sütunlarınız) **aşamaları** boyunca ilerlerler ve bir **tür** ile **önceliğe** sahiptirler. Bu kılavuz, bunları API üzerinden nasıl yöneteceğinizi 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.

---

## Görev nesnesi

```json
{
  "id": "tsk_abc123",
  "title": "Call Jane about her quote",
  "description": "She asked for pricing on the annual plan.",
  "type": "to_do",
  "priority": "high",
  "stage": "stage-1",
  "due_date": "2026-06-15T09:00:00.000Z",
  "remind_before_minutes": 15,
  "contact": "contacts/uid_whatsapp_15551234567",
  "campaign": "campaigns/abc123",
  "tags": ["sales"],
  "notes": "",
  "source": "api"
}
```

- **`type`** — `to_do`, `faq_update` veya yapılandırılmış görev türleriniz (bkz. [Görev türlerini listele](#list-task-types)).
- **`priority`** — `none`, `low`, `normal`, `high` veya `urgent`.
- **`stage`** — görev panonuzdaki bir aşamanın kimliği (bkz. [Görev aşamalarını listele](#list-task-stages)). Oluşturma sırasında belirtilmezse, görev ilk aşamanıza eklenir.
- **`remind_before_minutes`** — `due_date` öncesinde hatırlatıcının gönderileceği dakika sayısı. `0`, son teslim zamanında anlamına gelir; atlayın veya hatırlatıcı olmaması için `null` gönderin. `0` ile `1440` (1 gün) arasında bir tam sayı olmalıdır; daha büyük değerler reddedilir. Hatırlatıcının tetiklenmesi için bir `due_date` gerekir ve görevin yeniden zamanlanması hatırlatıcıyı da onunla birlikte taşır.

---

## Görev oluşturma

`POST /tasks` — yalnızca `title` zorunludur.

::: note
**Not:** `due_date`, günün saati dahil olmak üzere bir ISO 8601 zaman damgası kabul eder. Hatırlatıcının **Görevler** bildirim ayarlarınızda iletilmesi için bunu `remind_before_minutes` ile eşleştirin. `contact_id`, `deal_id` ve `campaign_id`, görevi ilgili kayıtlara bağlar. `assigned_to`, bir ekip üyesinin kullanıcı kimliğidir.
:::


> **`assigned_to` doğru ayarlamak.** Bu, hesap sahibinin veya aynı hesaptaki aktif bir ekip üyesinin kullanıcı kimliği olmalıdır. Bu uç nokta şu anda bunu kontrol etmemektedir, bu nedenle hiç kimseye ait olmayan bir kimlik kabul edilir ve tam olarak gönderdiğiniz şekilde saklanır — yine de bir `201` alırsınız. Kimliği yeniden yazmak yerine kopyalayın: bu kimlikler `l` ile `L`'ü ve `O` harfi ile `0` rakamını karıştırır ve tek bir yanlış karakter yeterlidir. Gerçekte ne gönderdiğinizi kontrol etmek için panodaki görevi açın: görev kaydındaki **Atanan** alanı, kimseyle eşleşmediğinde ham kimliği göstermeye geri döner ve **Görevi düzenle** içindeki atanan seçici **Atanmamış** gösterir.

**cURL**

```bash
curl -X POST "https://api.youraiconnector.com/v1/tasks?apiKey=YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "title": "Call Jane about her quote",
    "priority": "high",
    "due_date": "2026-06-15T09:00:00.000Z",
    "contact_id": "uid_whatsapp_15551234567",
    "tags": ["sales"]
  }'
```

**JavaScript**

```javascript
const res = await fetch("https://api.youraiconnector.com/v1/tasks", {
  method: "POST",
  headers: { "X-API-Key": "YOUR_API_KEY", "Content-Type": "application/json" },
  body: JSON.stringify({
    title: "Call Jane about her quote",
    priority: "high",
    due_date: "2026-06-15T09:00:00.000Z",
    contact_id: "uid_whatsapp_15551234567",
    tags: ["sales"],
  }),
});
const data = await res.json();
console.log(data.task_id);
```

**Python**

```python
import requests

res = requests.post(
    "https://api.youraiconnector.com/v1/tasks",
    headers={"X-API-Key": "YOUR_API_KEY"},
    json={
        "title": "Call Jane about her quote",
        "priority": "high",
        "due_date": "2026-06-15T09:00:00.000Z",
        "contact_id": "uid_whatsapp_15551234567",
        "tags": ["sales"],
    },
)
print(res.json()["task_id"])
```

**Yanıt** (`201`)

```json
{ "success": true, "task_id": "tsk_abc123", "task": { "title": "Call Jane about her quote", "...": "..." } }
```

---

## Görevleri listeleme

`GET /tasks` — hesabınızdaki görevleri, isteğe bağlı filtrelerle birlikte döndürür.

**Sorgu parametreleri** (hepsi isteğe bağlıdır): `stage`, `priority`, `contact_id`, `deal_id`, `assigned_to`, `due_before`, `due_after` (ISO zaman damgaları).

**cURL**

```bash
curl "https://api.youraiconnector.com/v1/tasks?apiKey=YOUR_API_KEY&stage=stage-1&priority=high"
```

**JavaScript**

```javascript
const res = await fetch("https://api.youraiconnector.com/v1/tasks?stage=stage-1&priority=high", {
  headers: { "X-API-Key": "YOUR_API_KEY" },
});
const { tasks } = await res.json();
```

**Python**

```python
res = requests.get(
    "https://api.youraiconnector.com/v1/tasks",
    headers={"X-API-Key": "YOUR_API_KEY"},
    params={"stage": "stage-1", "priority": "high"},
)
tasks = res.json()["tasks"]
```

**Yanıt** (`200`)

```json
{ "success": true, "tasks": [{ "id": "tsk_abc123", "title": "Call Jane about her quote", "...": "..." }] }
```

---

## Görevleri ara

`POST /tasks/search` — listeleme ile aynı isteğe bağlı filtrelere sahip, başlık ve açıklama üzerinde tam metin eşleşmesi.

```bash
curl -X POST "https://api.youraiconnector.com/v1/tasks/search?apiKey=YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{ "query": "quote", "priority": "high" }'
```

```javascript
const res = await fetch("https://api.youraiconnector.com/v1/tasks/search", {
  method: "POST",
  headers: { "X-API-Key": "YOUR_API_KEY", "Content-Type": "application/json" },
  body: JSON.stringify({ query: "quote", priority: "high" }),
});
```

```python
res = requests.post(
    "https://api.youraiconnector.com/v1/tasks/search",
    headers={"X-API-Key": "YOUR_API_KEY"},
    json={"query": "quote", "priority": "high"},
)
```

---

## Bir görev al

`GET /tasks/{taskId}`

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

```javascript
const res = await fetch("https://api.youraiconnector.com/v1/tasks/tsk_abc123", { headers: { "X-API-Key": "YOUR_API_KEY" } });
```

```python
res = requests.get("https://api.youraiconnector.com/v1/tasks/tsk_abc123", headers={"X-API-Key": "YOUR_API_KEY"})
```

Hesabınızda bulunmayan bir görev `404` döndürür.

---

## Bir görevi güncelle

`PUT /tasks/{taskId}` — yalnızca değiştirmek istediğiniz alanları gönderin (`title`, `description`, `type`, `priority`, `stage`, `due_date`, `remind_before_minutes`, `contact_id`, `deal_id`, `assigned_to`, `tags`, `notes`).

```bash
curl -X PUT "https://api.youraiconnector.com/v1/tasks/tsk_abc123?apiKey=YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{ "priority": "urgent", "notes": "Left a voicemail." }'
```

```javascript
await fetch("https://api.youraiconnector.com/v1/tasks/tsk_abc123", {
  method: "PUT",
  headers: { "X-API-Key": "YOUR_API_KEY", "Content-Type": "application/json" },
  body: JSON.stringify({ priority: "urgent", notes: "Left a voicemail." }),
});
```

```python
requests.put(
    "https://api.youraiconnector.com/v1/tasks/tsk_abc123",
    headers={"X-API-Key": "YOUR_API_KEY"},
    json={"priority": "urgent", "notes": "Left a voicemail."},
)
```

---

## Bir görevi tamamla

`POST /tasks/{taskId}/complete` — görevi panonuzun tamamlanan aşamasına taşır. İsteğe bağlı bir `notes` alanı, bir kapanış notu kaydeder.

```bash
curl -X POST "https://api.youraiconnector.com/v1/tasks/tsk_abc123/complete?apiKey=YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{ "notes": "Closed — customer signed up." }'
```

```javascript
await fetch("https://api.youraiconnector.com/v1/tasks/tsk_abc123/complete", {
  method: "POST",
  headers: { "X-API-Key": "YOUR_API_KEY", "Content-Type": "application/json" },
  body: JSON.stringify({ notes: "Closed — customer signed up." }),
});
```

```python
requests.post(
    "https://api.youraiconnector.com/v1/tasks/tsk_abc123/complete",
    headers={"X-API-Key": "YOUR_API_KEY"},
    json={"notes": "Closed — customer signed up."},
)
```

---

## Taşı ve yeniden sırala (kanban)

**Bir görevi başka bir aşamaya taşıyın** — `POST /tasks/{taskId}/move`, `new_stage_id` (hedef aşama) ve `new_position` (o aşama içindeki sıfır tabanlı yuva; gereklidir, negatif olmayan bir tam sayı olmalıdır) ile:

```bash
curl -X POST "https://api.youraiconnector.com/v1/tasks/tsk_abc123/move?apiKey=YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{ "new_stage_id": "stage-2", "new_position": 0 }'
```

**Bir aşama içindeki görevleri yeniden sıralayın** — `POST /tasks/reorder`, `stage_id` ve görev kimlikleri yeni sıralarıyla:

```bash
curl -X POST "https://api.youraiconnector.com/v1/tasks/reorder?apiKey=YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{ "stage_id": "stage-1", "ordered_task_ids": ["tsk_3", "tsk_1", "tsk_2"] }'
```

```javascript
await fetch("https://api.youraiconnector.com/v1/tasks/reorder", {
  method: "POST",
  headers: { "X-API-Key": "YOUR_API_KEY", "Content-Type": "application/json" },
  body: JSON.stringify({ stage_id: "stage-1", ordered_task_ids: ["tsk_3", "tsk_1", "tsk_2"] }),
});
```

```python
requests.post(
    "https://api.youraiconnector.com/v1/tasks/reorder",
    headers={"X-API-Key": "YOUR_API_KEY"},
    json={"stage_id": "stage-1", "ordered_task_ids": ["tsk_3", "tsk_1", "tsk_2"]},
)
```

---

## Bir kişi için görevler

`GET /tasks/contact/{contactId}` — bir kişiyle bağlantılı her görev.

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

```javascript
const res = await fetch("https://api.youraiconnector.com/v1/tasks/contact/uid_whatsapp_15551234567", { headers: { "X-API-Key": "YOUR_API_KEY" } });
```

```python
res = requests.get("https://api.youraiconnector.com/v1/tasks/contact/uid_whatsapp_15551234567", headers={"X-API-Key": "YOUR_API_KEY"})
```

---

## Görev panosu yapılandırması

### Görev aşamalarını listele

`GET /tasks/stages` — panonuzun sütunları, sıralı bir şekilde. Görev oluştururken veya taşırken bir aşama `id` değerini `stage` alanı olarak kullanın.

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

```json
{ "success": true, "stages": [{ "id": "stage-1", "name": "To Do", "is_completed_stage": false }, { "id": "stage-done", "name": "Done", "is_completed_stage": true }] }
```

### Görev aşamalarını güncelle

`PUT /tasks/stages` — panonuzun aşama yapılandırmasını değiştirin. Tam sıralı `stages` dizisini gönderin.

```bash
curl -X PUT "https://api.youraiconnector.com/v1/tasks/stages?apiKey=YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{ "stages": [
    { "id": "stage-1", "name": "To Do", "is_completed_stage": false },
    { "id": "stage-2", "name": "In Progress", "is_completed_stage": false },
    { "id": "stage-done", "name": "Done", "is_completed_stage": true }
  ] }'
```

### Görev türlerini listele

`GET /tasks/types` — hesabınızda yapılandırılmış görev türleri (`type` alanı olarak kullanılır).

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

---

## Bir SSS önerisini onaylayın

AI botu yeni bir SSS önerdiğinde, `faq_update` türünde bir görev oluşturur. `POST /tasks/{taskId}/approve-faq`, bu öneriyi onu oluşturan AI temsilcisinin bilgi tabanında gerçek bir SSS'ye dönüştürür ve görevi tamamlar. Gövde kısmındaki soru/cevap bölümünü geçersiz kılabilirsiniz.

AI'nın cevabı görevin bağlantılı kişisine anında, o sohbette doğal bir mesaj olarak göndermesini sağlamak için `"send_follow_up": true` ekleyin (bu, uygulamadaki **Cevabı şimdi kişiye gönder** düğmesinin yaptığı işle aynıdır). Yanıt, o kişiyle ilgilenen AI temsilcisi aracılığıyla gönderilir.

```bash
curl -X POST "https://api.youraiconnector.com/v1/tasks/tsk_faq99/approve-faq?apiKey=YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{ "question": "Do you offer refunds?", "answer": "Yes, within 30 days.", "send_follow_up": true }'
```

```json
{ "success": true, "faq_id": "faq_xyz", "task_id": "tsk_faq99", "follow_up_status": "published" }
```

`follow_up_status` size mesaja ne olduğunu bildirir: `not_requested` (bayrak ayarlanmadı), `published` (gönderildi), `queued` (bot o kişiyle yanıt verme aşamasındaydı, cevap biter bitmez gönderilecek), `skipped_no_contact` (görevin bağlantılı olduğu bir kişi yok), `skipped_no_campaign` (o kişi için yanıt verebilecek bir temsilci veya kampanya yok) veya `skipped_error`. SSS her durumda oluşturulur.

Oluşturulan SSS'yi yönetmek için [SSS API](faqs.md) bölümüne bakın.

---

## Bir görevi silin

`DELETE /tasks/{taskId}`

```bash
curl -X DELETE "https://api.youraiconnector.com/v1/tasks/tsk_abc123?apiKey=YOUR_API_KEY"
```

```javascript
await fetch("https://api.youraiconnector.com/v1/tasks/tsk_abc123", { method: "DELETE", headers: { "X-API-Key": "YOUR_API_KEY" } });
```

```python
requests.delete("https://api.youraiconnector.com/v1/tasks/tsk_abc123", headers={"X-API-Key": "YOUR_API_KEY"})
```

---

## Sonraki adımlar

- [Kişiler API'si](contacts.md) — görevleri doğru kişiyle ilişkilendirin
- [Webhooks API](webhooks.md) — `Task Created`, `Task Updated` ve `Task Completed` hakkında bildirim alın
- [API Referansı](reference.md) — tam etkileşimli uç nokta gezgini