# API-ul de sarcini

Sarcinile sunt activitățile și acțiunile de follow-up atașate contului tău — opțional legate de un contact, o tranzacție sau o campanie. Acestea trec prin **etapele** panoului tău de sarcini (coloanele tale kanban) și au un **tip** și o **prioritate**. Acest ghid acoperă gestionarea lor prin intermediul API-ului.

- **URL de bază** — `https://api.youraiconnector.com/v1`
- **Autentificare** — cheia ta API (vezi [Autentificare](authentication.md))
- **Erori și paginare** — vezi [Erori și paginare](errors-and-pagination.md)

Toate exemplele de mai jos arată forma de interogare `?apiKey=` în cURL și antetul `X-API-Key` în JavaScript și Python — oricare dintre ele funcționează pe fiecare endpoint.

---

## Obiectul sarcină

```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` sau tipurile de sarcini configurate de tine (vezi [List task types](#list-task-types)).
- **`priority`** — `none`, `low`, `normal`, `high` sau `urgent`.
- **`stage`** — id-ul unei etape de pe panoul de sarcini (vezi [List task stages](#list-task-stages)). Dacă este omis la creare, sarcina va fi plasată în prima etapă.
- **`remind_before_minutes`** — numărul de minute înainte de `due_date` pentru trimiterea unui memento. `0` înseamnă la ora scadentă; omite-l sau trimite `null` pentru a nu primi niciun memento. Trebuie să fie un număr întreg de la `0` la `1440` (1 zi) — orice valoare mai mare va fi respinsă. Mementoul are nevoie de un `due_date` pentru a fi declanșat, iar reprogramarea sarcinii va muta și mementoul odată cu aceasta.

---

## Crearea unei sarcini

`POST /tasks` — doar `title` este obligatoriu.

::: note
**Notă:** `due_date` acceptă un marcaj temporal ISO 8601, incluzând ora din zi. Asociază-l cu `remind_before_minutes` pentru a primi mementoul conform setărilor de notificare pentru **Sarcini**. `contact_id`, `deal_id` și `campaign_id` leagă sarcina de acele înregistrări. `assigned_to` este id-ul de utilizator al unui membru al echipei.
:::


> **Configurarea corectă a `assigned_to`.** Acesta trebuie să fie ID-ul de utilizator al proprietarului contului sau al unui membru activ al echipei din același cont. Acest endpoint nu verifică acest lucru în prezent, așa că un ID care nu aparține nimănui este acceptat și stocat exact așa cum l-ați trimis — veți primi totuși un `201`. Copiați ID-ul în loc să îl tastați din nou: aceste ID-uri combină `l` cu `L` și litera `O` cu cifra `0`, iar un singur caracter greșit este suficient. Pentru a verifica ce ați trimis efectiv, deschideți sarcina în tabloul de bord: câmpul **Assignee** (Responsabil) din înregistrarea sarcinii revine la afișarea ID-ului brut atunci când acesta nu corespunde nimănui, iar selectorul de responsabili din **Edit task** (Editare sarcină) afișează **Unassigned** (Neatribuit).

**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"])
```

**Răspuns** (`201`)

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

---

## Listarea sarcinilor

`GET /tasks` — returnează sarcinile pentru contul tău, cu filtre opționale.

**Parametri de interogare** (toți opționali): `stage`, `priority`, `contact_id`, `deal_id`, `assigned_to`, `due_before`, `due_after` (marcaje temporale ISO).

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

**Răspuns** (`200`)

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

---

## Căutare sarcini

`POST /tasks/search` — potrivire text integral în titlu și descriere, cu aceleași filtre opționale ca la listare.

```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"},
)
```

---

## Obținerea unei sarcini

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

O sarcină care nu există în contul tău returnează `404`.

---

## Actualizarea unei sarcini

`PUT /tasks/{taskId}` — trimite doar câmpurile pe care dorești să le modifici (`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."},
)
```

---

## Finalizarea unei sarcini

`POST /tasks/{taskId}/complete` — mută sarcina în etapa de finalizare a panoului tău. Un câmp opțional `notes` înregistrează o notă de închidere.

```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."},
)
```

---

## Mutare și reordonare (kanban)

**Mută o sarcină într-o altă etapă** — `POST /tasks/{taskId}/move` cu `new_stage_id` (etapa de destinație) și `new_position` (poziția bazată pe zero în cadrul acelei etape; obligatoriu, trebuie să fie un număr întreg non-negativ):

```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 }'
```

**Reordonează sarcinile în cadrul unei etape** — `POST /tasks/reorder` cu `stage_id` și ID-urile sarcinilor în noua lor ordine:

```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"]},
)
```

---

## Sarcini pentru un contact

`GET /tasks/contact/{contactId}` — fiecare sarcină legată de un contact.

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

---

## Configurarea panoului de sarcini

### Listează etapele sarcinilor

`GET /tasks/stages` — coloanele panoului tău, în ordine. Folosește un `id` de etapă ca și câmp `stage` atunci când creezi sau muți sarcini.

```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 }] }
```

### Actualizează etapele sarcinilor

`PUT /tasks/stages` — înlocuiește configurația etapelor panoului tău. Trimite matricea completă și ordonată `stages`.

```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 }
  ] }'
```

### Listează tipurile de sarcini

`GET /tasks/types` — tipurile de sarcini configurate în contul tău (folosite ca și câmp `type`).

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

---

## Aprobă o sugestie pentru Întrebări frecvente (FAQ)

Atunci când botul AI propune o nouă întrebare frecventă (FAQ), acesta creează o sarcină de tip `faq_update`. `POST /tasks/{taskId}/approve-faq` transformă acea sugestie într-o întrebare frecventă reală în baza de cunoștințe a agentului AI care a generat-o și finalizează sarcina. Puteți suprascrie întrebarea/răspunsul în corpul mesajului.

Adăugați `"send_follow_up": true` pentru a face ca AI-ul să trimită răspunsul direct către contactul asociat sarcinii, sub forma unui mesaj natural în acel chat (același lucru pe care îl face comutatorul **Trimite răspunsul către contact acum** din aplicație). Răspunsul este transmis prin intermediul agentului AI care gestionează acel contact.

```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` vă indică ce s-a întâmplat cu mesajul: `not_requested` (indicatorul nu este setat), `published` (trimis), `queued` (botul era în plin proces de răspuns către acel contact, răspunsul este trimis imediat ce termină), `skipped_no_contact` (sarcina nu are niciun contact asociat), `skipped_no_campaign` (niciun agent sau campanie nu a putut răspunde pentru acel contact) sau `skipped_error`. Întrebarea frecventă este creată în fiecare caz.

Consultă [API-ul pentru Întrebări frecvente](faqs.md) pentru a gestiona întrebarea frecventă rezultată.

---

## Șterge o sarcină

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

---

## Pașii următori

- [API Contacte](contacts.md) — asociază sarcinile cu persoana de contact potrivită
- [API Webhooks](webhooks.md) — primește notificări despre `Task Created`, `Task Updated` și `Task Completed`
- [Referință API](reference.md) — exploratorul complet și interactiv al endpoint-urilor