# API des transactions

Une transaction est une opportunité de vente sur votre tableau de [Pipeline de ventes](../deals/sales-pipeline.md) — un titre, une valeur, l'étape dans laquelle elle se trouve, et éventuellement le contact auquel elle appartient et le membre de l'équipe auquel elle est assignée. Ce guide couvre la lecture et la gestion des transactions via l'API.

- **URL de base** — `https://api.youraiconnector.com/v1`
- **Authentification** — votre clé API (voir [Authentification](authentication.md))
- **Erreurs et pagination** — voir [Erreurs et pagination](errors-and-pagination.md)

Tous les exemples ci-dessous utilisent le format de requête `?apiKey=` en cURL et l'en-tête `X-API-Key` en JavaScript et Python — les deux fonctionnent sur chaque point de terminaison.

---

## L'objet transaction

```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` est l'identifiant de l'une de vos étapes de pipeline — lisez-les avec `GET /pipelines` (voir [Pipelines](#pipelines) ci-dessous). Les identifiants d'étape sont uniques sur l'ensemble de vos pipelines, donc `pipeline_id` est dérivé de l'étape et est en lecture seule : `default` est votre pipeline principal, et il est `null` lorsque l'étape n'existe plus. Les horodatages sont au format ISO 8601.

Une affaire ne stocke que les champs indiqués ci-dessus. Lorsque vous en créez ou en mettez à jour une, tout autre champ est refusé avec une `400` qui le nomme, afin que rien de ce que vous envoyez ne soit perdu silencieusement. Conservez les données supplémentaires dans les champs personnalisés du contact associé.

---

## Lister les transactions

`GET /deals` — renvoie les transactions de votre compte, de la plus récente à la plus ancienne.

**Paramètres de requête** (tous facultatifs) : `stage` (un identifiant d'étape), `pipeline_id` (uniquement les transactions sur ce pipeline), `contact_id`, `limit` (50 par défaut, 200 max), `cursor` (depuis le `next_cursor` de la page précédente).

**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éponse** (`200`)

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

---

## Obtenir une transaction

`GET /deals/{dealId}`

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

**Réponse** (`200`)

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

Une transaction qui n'existe pas, ou qui appartient à un autre compte, renvoie `404`.

---

## Créer une transaction

`POST /deals` — `title` et `stage` sont requis ; `stage` doit être l'un des identifiants d'étape de votre pipeline.

```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éponse** (`201`)

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

---

## Mettre à jour une transaction

`PUT /deals/{dealId}` — envoyez uniquement les champs que vous souhaitez modifier (`title`, `description`, `notes`, `value`, `stage`, `status`, `priority`, `contact_id`, …). `value` doit être un nombre.

```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éponse** (`200`) : `{ "success": true, "deal_id": "deal_abc123" }`

---

## Déplacer une affaire vers une autre étape

`POST /deals/{dealId}/move` — corps `{ "new_stage_id": "stage-3", "new_position": 0 }`. La position `0` place la carte en haut de la colonne.

```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éponse** (`200`) : `{ "success": true, "deal_id": "deal_abc123", "stage": "stage-3", "position": 0 }`

---

## Supprimer une affaire

`DELETE /deals/{dealId}` — supprime l'affaire. **Cette action est irréversible.**

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

**Réponse** (`200`) : `{ "success": true }`

---

## Pipelines

Chaque compte possède un pipeline principal (`id: "default"`) ; vous pouvez en ajouter jusqu'à neuf autres, chacun avec ses propres étapes. Les identifiants d'étape et les balises de déclenchement doivent être uniques sur tous les pipelines du compte, et chaque pipeline peut marquer une étape comme son résultat `won` et une autre comme son résultat `lost`.

### Lister les pipelines

`GET /pipelines` — tous les pipelines, le principal en premier, chacun avec ses étapes triées par position.

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

**Réponse** (`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" }
        ]
      }
    ]
  }
}
```

### Créer un pipeline

`POST /pipelines` — corps `{ "id"?, "name", "stages"?, "settings"? }`. Laissez `id` vide pour en générer un. Chaque étape utilise les mêmes champs que la boîte de dialogue Étapes : `id`, `name`, `color`, `position`, `trigger_tag` facultatif (un chemin de balise, `users/{uid}/tags/{tagId}`), `default_value`, `auto_move_after_days` + `auto_move_to_stage` (une étape du même pipeline) et `outcome` (`"won"` ou `"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éponse** (`201`) : `{ "success": true, "data": { "pipeline": { ... } } }`. Un identifiant d'étape ou une balise de déclenchement déjà utilisé par un autre pipeline est une `400` nommant ce pipeline ; un identifiant qui existe déjà est une `409`.

### Mettre à jour un pipeline

`PUT /pipelines/{pipelineId}` — corps `{ "name"?, "stages"?, "settings"? }`. `stages` remplace toute la liste, comme dans la boîte de dialogue Étapes. Utilisez `default` pour le pipeline principal. L'identifiant du pipeline lui-même ne peut pas être modifié.

### Supprimer un pipeline

`DELETE /pipelines/{pipelineId}` — supprime un pipeline supplémentaire (le principal ne peut pas être supprimé). Si des transactions se trouvent encore dans ses étapes, l'appel répond `409` avec `deal_count` ; ajoutez `?delete_deals=true` pour supprimer ces transactions en même temps que le pipeline. **Cette action est irréversible.**

**Réponse** (`204`).

---

## Étapes suivantes

- [Pipeline de ventes](../deals/sales-pipeline.md) — fonctionnement des étapes, des étiquettes d'étape, des pipelines multiples et du tableau.
- [API Tâches](tasks.md) — les tâches peuvent être liées à une affaire avec `deal_id`.
- [Automatisations](../automations/automations.md) — les étapes **Trouver des affaires** et **Trouver une affaire** lisent les mêmes données au sein d'un flux de travail.