# API des tâches

Les tâches sont les éléments à faire et les suivis associés à votre compte — éventuellement liés à un contact, une affaire ou une campagne. Elles progressent à travers les **étapes** de votre tableau de tâches (vos colonnes kanban) et possèdent un **type** et une **priorité**. Ce guide explique comment les gérer 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 tâche

```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` ou vos types de tâches configurés (voir [Lister les types de tâches](#list-task-types)).
- **`priority`** — `none`, `low`, `normal`, `high` ou `urgent`.
- **`stage`** — l'identifiant d'une étape sur votre tableau de tâches (voir [Lister les étapes de tâche](#list-task-stages)). Si omis lors de la création, la tâche est placée dans votre première étape.
- **`remind_before_minutes`** — nombre de minutes avant `due_date` pour envoyer un rappel. `0` signifie à l'heure d'échéance ; omettez-le ou envoyez `null` pour aucun rappel. Doit être un nombre entier compris entre `0` et `1440` (1 jour) — toute valeur supérieure sera rejetée. Le rappel nécessite un `due_date` pour se déclencher, et la reprogrammation de la tâche déplace le rappel avec elle.

---

## Créer une tâche

`POST /tasks` — seul `title` est requis.

::: note
**Remarque :** `due_date` accepte un horodatage ISO 8601, incluant une heure de la journée. Associez-le à `remind_before_minutes` pour que le rappel soit envoyé selon vos paramètres de notification **Tâches**. `contact_id`, `deal_id` et `campaign_id` lient la tâche à ces enregistrements. `assigned_to` est l'identifiant utilisateur d'un membre de l'équipe.
:::


> **Bien configurer `assigned_to`.** Il doit s'agir de l'identifiant utilisateur du propriétaire du compte ou d'un membre actif de l'équipe sur le même compte. Ce point de terminaison ne le vérifie pas actuellement, donc un identifiant n'appartenant à personne est accepté et stocké exactement tel que vous l'avez envoyé — vous recevez tout de même un `201`. Copiez l'identifiant plutôt que de le retaper : ces identifiants mélangent `l` avec `L` et la lettre `O` avec le chiffre `0`, et un seul caractère erroné suffit. Pour vérifier ce que vous avez réellement envoyé, ouvrez la tâche dans le tableau de bord : le champ **Assigné** sur l'enregistrement de la tâche affiche l'identifiant brut lorsqu'il ne correspond à personne, et le sélecteur d'assigné dans **Modifier la tâche** indique **Non assigné**.

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

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

---

## Lister les tâches

`GET /tasks` — renvoie les tâches de votre compte, avec des filtres optionnels.

**Paramètres de requête** (tous facultatifs) : `stage`, `priority`, `contact_id`, `deal_id`, `assigned_to`, `due_before`, `due_after` (horodatages 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éponse** (`200`)

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

---

## Rechercher des tâches

`POST /tasks/search` — recherche en texte intégral sur le titre et la description, avec les mêmes filtres facultatifs que pour la liste.

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

---

## Obtenir une tâche

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

Une tâche qui n'existe pas sur votre compte renvoie `404`.

---

## Mettre à jour une tâche

`PUT /tasks/{taskId}` — envoyez uniquement les champs que vous souhaitez modifier (`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."},
)
```

---

## Terminer une tâche

`POST /tasks/{taskId}/complete` — déplace la tâche vers l'étape terminée de votre tableau. Un champ facultatif `notes` permet d'enregistrer une note de clôture.

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

---

## Déplacer et réorganiser (kanban)

**Déplacer une tâche vers une autre étape** — `POST /tasks/{taskId}/move` avec `new_stage_id` (l'étape de destination) et `new_position` (la position basée sur zéro au sein de cette étape ; obligatoire, doit être un entier non négatif) :

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

**Réorganiser les tâches au sein d'une étape** — `POST /tasks/reorder` avec `stage_id` et les identifiants des tâches dans leur nouvel ordre :

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

---

## Tâches pour un contact

`GET /tasks/contact/{contactId}` — chaque tâche liée à 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"})
```

---

## Configuration du tableau des tâches

### Lister les étapes des tâches

`GET /tasks/stages` — les colonnes de votre tableau, dans l'ordre. Utilisez un `id` d'étape comme champ `stage` lors de la création ou du déplacement de tâches.

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

### Mettre à jour les étapes des tâches

`PUT /tasks/stages` — remplacez la configuration des étapes de votre tableau. Envoyez le tableau `stages` complet et ordonné.

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

### Lister les types de tâches

`GET /tasks/types` — les types de tâches configurés sur votre compte (utilisés comme champ `type`).

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

---

## Approuver une suggestion de FAQ

Lorsque le bot IA propose une nouvelle FAQ, il crée une tâche de type `faq_update`. `POST /tasks/{taskId}/approve-faq` transforme cette suggestion en une véritable FAQ dans la base de connaissances de l'agent IA qui l'a soulevée et termine la tâche. Vous pouvez remplacer la question/réponse dans le corps du texte.

Ajoutez `"send_follow_up": true` pour que l'IA envoie également la réponse au contact lié à la tâche immédiatement, sous forme de message naturel dans cette discussion (la même chose que fait le bouton bascule **Envoyer la réponse au contact maintenant** dans l'application). La réponse est envoyée via l'agent IA qui gère ce 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` vous indique ce qui est arrivé au message : `not_requested` (indicateur non défini), `published` (envoyé), `queued` (le bot était en train de répondre à ce contact, la réponse est envoyée dès qu'il a terminé), `skipped_no_contact` (la tâche n'a aucun contact lié), `skipped_no_campaign` (aucun agent ou campagne n'a pu répondre pour ce contact) ou `skipped_error`. La FAQ est créée dans tous les cas.

Consultez l'[API FAQ](faqs.md) pour gérer la FAQ résultante.

---

## Supprimer une tâche

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

---

## Étapes suivantes

- [API Contacts](contacts.md) — associez des tâches au bon contact
- [API Webhooks](webhooks.md) — soyez notifié sur `Task Created`, `Task Updated` et `Task Completed`
- [Référence de l'API](reference.md) — l'explorateur de points de terminaison interactif complet