# 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.dmchamp.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",
  "stage": "stage-2",
  "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 des étapes de votre pipeline — lisez-les depuis les paramètres de votre pipeline (`GET /users/me/pipeline-settings`). Les horodatages sont au format ISO 8601.

---

## 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 optionnels) : `stage` (un identifiant d'étape), `contact_id`, `limit` (50 par défaut, 200 maximum), `cursor` (depuis le `next_cursor` de la page précédente).

**cURL**

```bash
curl "https://api.dmchamp.com/v1/deals?apiKey=YOUR_API_KEY&stage=stage-2&limit=50"
```

**JavaScript**

```javascript
const res = await fetch("https://api.dmchamp.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.dmchamp.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.dmchamp.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.dmchamp.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`, `value`, `stage`, `status`, `priority`, `contact_id`, …). `value` doit être un nombre.

```bash
curl -X PUT "https://api.dmchamp.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.dmchamp.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.dmchamp.com/v1/deals/deal_abc123?apiKey=YOUR_API_KEY"
```

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

---

## Étapes suivantes

- [Pipeline de ventes](../deals/sales-pipeline.md) — fonctionnement des étapes, des étiquettes d'étape 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.