# API pentru oportunități (Deals)

O oportunitate (deal) reprezintă o șansă de vânzare pe panoul [Sales Pipeline](../deals/sales-pipeline.md) — un titlu, o valoare, etapa în care se află și, opțional, contactul căruia îi aparține și membrul echipei căruia îi este atribuită. Acest ghid acoperă citirea și gestionarea oportunităților 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 deal

```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` este id-ul uneia dintre etapele fluxului tău de lucru — citește-le cu `GET /pipelines` (vezi [Fluxuri de lucru](#pipelines) mai jos). Id-urile etapelor sunt unice pentru toate fluxurile tale de lucru, deci `pipeline_id` este derivat din etapă și este doar pentru citire: `default` este fluxul tău de lucru principal și este `null` atunci când etapa nu mai există. Marcajele temporale sunt în format ISO 8601.

O tranzacție stochează doar câmpurile afișate mai sus. Când creați sau actualizați una, orice alt câmp este refuzat cu o `400` care îl numește, astfel încât nimic din ceea ce trimiteți nu se pierde în mod silențios. Păstrați datele suplimentare în câmpurile personalizate ale contactului asociat.

---

## Listarea oportunităților

`GET /deals` — returnează oportunitățile din contul tău, începând cu cele mai recente.

**Parametri de interogare** (toți opționali): `stage` (un id de etapă), `pipeline_id` (doar tranzacțiile din acel flux de lucru), `contact_id`, `limit` (implicit 50, maxim 200), `cursor` (din `next_cursor` al paginii anterioare).

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

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

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

---

## Obținerea unei oportunități

`GET /deals/{dealId}`

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

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

```json
{ "success": true, "deal": { "id": "deal_abc123", "title": "Annual plan – Jane's Clinic", "...": "..." } }
```

O oportunitate care nu există sau care aparține altui cont va returna `404`.

---

## Crearea unei oportunități

`POST /deals` — `title` și `stage` sunt obligatorii; `stage` trebuie să fie unul dintre id-urile etapelor fluxului tău de vânzări.

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

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

```json
{ "success": true, "deal_id": "deal_abc123" }
```

---

## Actualizarea unei oportunități

`PUT /deals/{dealId}` — trimiteți doar câmpurile pe care doriți să le modificați (`title`, `description`, `notes`, `value`, `stage`, `status`, `priority`, `contact_id`, …). `value` trebuie să fie un numă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" }'
```

**Răspuns** (`200`): `{ "success": true, "deal_id": "deal_abc123" }`

---

## Mută o afacere într-o altă etapă

`POST /deals/{dealId}/move` — corp `{ "new_stage_id": "stage-3", "new_position": 0 }`. Poziția `0` plasează cardul în partea de sus a coloanei.

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

**Răspuns** (`200`): `{ "success": true, "deal_id": "deal_abc123", "stage": "stage-3", "position": 0 }`

---

## Șterge o afacere

`DELETE /deals/{dealId}` — elimină afacerea. **Această acțiune nu poate fi anulată.**

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

**Răspuns** (`200`): `{ "success": true }`

---

## Fluxuri de lucru

Fiecare cont are un flux de lucru principal (`id: "default"`); poți adăuga până la nouă suplimentare, fiecare cu propriile etape. Id-urile etapelor și etichetele de declanșare trebuie să fie unice în toate fluxurile de lucru din cont, iar fiecare flux de lucru poate marca o etapă ca fiind `won` și una ca fiind `lost`.

### Listarea fluxurilor de lucru

`GET /pipelines` — fiecare flux de lucru, cel principal primul, fiecare cu etapele sale sortate după poziție.

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

**Răspuns** (`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" }
        ]
      }
    ]
  }
}
```

### Crearea unui flux de lucru

`POST /pipelines` — corp `{ "id"?, "name", "stages"?, "settings"? }`. Lasă `id` necompletat pentru a fi generat unul. Fiecare etapă preia aceleași câmpuri ca în dialogul Etape: `id`, `name`, `color`, `position`, opțional `trigger_tag` (o cale de etichetă, `users/{uid}/tags/{tagId}`), `default_value`, `auto_move_after_days` + `auto_move_to_stage` (o etapă din același flux de lucru) și `outcome` (`"won"` sau `"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" }
    ]
  }'
```

**Răspuns** (`201`): `{ "success": true, "data": { "pipeline": { ... } } }`. Un id de etapă sau o etichetă de declanșare deja utilizată de un alt flux de lucru reprezintă o `400` care numește acel flux de lucru; un id care există deja este o `409`.

### Actualizarea unui flux de lucru

`PUT /pipelines/{pipelineId}` — corp `{ "name"?, "stages"?, "settings"? }`. `stages` înlocuiește întreaga listă, la fel ca în dialogul Etape. Folosește `default` pentru fluxul de lucru principal. Id-ul fluxului de lucru în sine nu poate fi modificat.

### Ștergerea unui flux de lucru

`DELETE /pipelines/{pipelineId}` — elimină un flux de lucru suplimentar (cel principal nu poate fi șters). Dacă există tranzacții în etapele sale, apelul răspunde cu `409` și `deal_count`; adaugă `?delete_deals=true` pentru a șterge acele tranzacții împreună cu fluxul de lucru. **Această acțiune nu poate fi anulată.**

**Răspuns** (`204`).

---

## Pașii următori

- [Sales Pipeline](../deals/sales-pipeline.md) — cum funcționează etapele, etichetele de etapă, mai multe fluxuri de vânzări și panoul.
- [API Sarcini](tasks.md) — sarcinile pot fi legate de o tranzacție cu `deal_id`.
- [Automatizări](../automations/automations.md) — pașii **Găsește tranzacții** și **Găsește tranzacție** citesc aceleași date în cadrul unui flux de lucru.