# API de Tarefas

Tarefas são os itens a fazer e acompanhamentos vinculados à sua conta — opcionalmente associados a um contato, negócio ou campanha. Elas avançam pelos **estágios** do seu quadro de tarefas (suas colunas kanban) e possuem um **tipo** e uma **prioridade**. Este guia aborda como gerenciá-las via API.

- **URL Base** — `https://api.youraiconnector.com/v1`
- **Autenticação** — sua chave de API (veja [Autenticação](authentication.md))
- **Erros e paginação** — veja [Erros e Paginação](errors-and-pagination.md)

Todos os exemplos abaixo mostram a forma de consulta `?apiKey=` em cURL e o cabeçalho `X-API-Key` em JavaScript e Python — ambos funcionam em todos os endpoints.

---

## O objeto de tarefa

```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 seus tipos de tarefa configurados (consulte [Listar tipos de tarefa](#list-task-types)).
- **`priority`** — `none`, `low`, `normal`, `high` ou `urgent`.
- **`stage`** — o id de uma etapa no seu quadro de tarefas (consulte [Listar etapas de tarefa](#list-task-stages)). Quando omitido na criação, a tarefa é colocada na sua primeira etapa.
- **`remind_before_minutes`** — quantos minutos antes de `due_date` enviar um lembrete. `0` significa no horário de vencimento; omita ou envie `null` para nenhum lembrete. Deve ser um número inteiro de `0` a `1440` (1 dia) — qualquer valor maior será rejeitado. O lembrete precisa de um `due_date` para ser disparado, e reagendar a tarefa move o lembrete junto com ela.

---

## Criar uma tarefa

`POST /tasks` — apenas `title` é obrigatório.

::: note
**Nota:** `due_date` aceita um carimbo de data/hora ISO 8601, incluindo um horário do dia. Combine-o com `remind_before_minutes` para que o lembrete seja entregue nas suas configurações de notificação de **Tarefas**. `contact_id`, `deal_id` e `campaign_id` vinculam a tarefa a esses registros. `assigned_to` é o id de usuário de um membro da equipe.
:::


> **Definindo o `assigned_to` corretamente.** Deve ser o ID de usuário do proprietário da conta ou de um membro ativo da equipe na mesma conta. Este endpoint atualmente não verifica isso, portanto, um ID que não pertence a ninguém é aceito e armazenado exatamente como você o enviou — você ainda recebe um `201`. Copie o ID em vez de redigitá-lo: esses IDs misturam `l` com `L` e a letra `O` com o dígito `0`, e um caractere errado é o suficiente. Para verificar o que você realmente enviou, abra a tarefa no painel: o campo **Responsável** no registro da tarefa volta a mostrar o ID bruto quando não corresponde a ninguém, e o seletor de responsável em **Editar tarefa** mostra **Não atribuído**.

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

**Resposta** (`201`)

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

---

## Listar tarefas

`GET /tasks` — retorna as tarefas da sua conta, com filtros opcionais.

**Parâmetros de consulta** (todos opcionais): `stage`, `priority`, `contact_id`, `deal_id`, `assigned_to`, `due_before`, `due_after` (timestamps 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"]
```

**Resposta** (`200`)

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

---

## Pesquisar tarefas

`POST /tasks/search` — correspondência de texto completo no título e na descrição, com os mesmos filtros opcionais da listagem.

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

---

## Obter uma tarefa

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

Uma tarefa que não existe na sua conta retorna `404`.

---

## Atualizar uma tarefa

`PUT /tasks/{taskId}` — envie apenas os campos que deseja alterar (`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."},
)
```

---

## Concluir uma tarefa

`POST /tasks/{taskId}/complete` — move a tarefa para o estágio de concluídas do seu quadro. Um campo opcional `notes` registra uma nota de fechamento.

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

---

## Mover e reordenar (kanban)

**Mova uma tarefa para outro estágio** — `POST /tasks/{taskId}/move` com `new_stage_id` (o estágio de destino) e `new_position` (a posição baseada em zero dentro desse estágio; obrigatório, deve ser um número inteiro não negativo):

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

**Reordene tarefas dentro de um estágio** — `POST /tasks/reorder` com `stage_id` e os IDs das tarefas em sua nova ordem:

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

---

## Tarefas para um contato

`GET /tasks/contact/{contactId}` — cada tarefa vinculada a um contato.

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

---

## Configuração do quadro de tarefas

### Listar estágios de tarefa

`GET /tasks/stages` — as colunas do seu quadro, em ordem. Use um `id` de estágio como o campo `stage` ao criar ou mover tarefas.

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

### Atualizar estágios de tarefa

`PUT /tasks/stages` — substitua a configuração de estágio do seu quadro. Envie o array `stages` completo e ordenado.

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

### Listar tipos de tarefa

`GET /tasks/types` — os tipos de tarefa configurados em sua conta (usados como o campo `type`).

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

---

## Aprovar uma sugestão de FAQ

Quando o bot de IA propõe uma nova FAQ, ele cria uma tarefa do tipo `faq_update`. O `POST /tasks/{taskId}/approve-faq` transforma essa sugestão em uma FAQ real na base de conhecimento do agente de IA que a gerou e conclui a tarefa. Você pode substituir a pergunta/resposta no corpo.

Adicione `"send_follow_up": true` para também fazer com que a IA envie a resposta ao contato vinculado à tarefa imediatamente, como uma mensagem natural naquele chat (a mesma coisa que a opção **Enviar a resposta ao contato agora** faz no aplicativo). A resposta é enviada pelo agente de IA que gerencia esse contato.

```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` informa o que aconteceu com a mensagem: `not_requested` (flag não definida), `published` (enviada), `queued` (o bot estava respondendo a esse contato, a resposta será enviada assim que ele terminar), `skipped_no_contact` (a tarefa não possui contato vinculado), `skipped_no_campaign` (nenhum agente ou campanha pôde responder por esse contato) ou `skipped_error`. A FAQ é criada em todos os casos.

Consulte a [API de FAQs](faqs.md) para gerenciar a FAQ resultante.

---

## Excluir uma tarefa

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

---

## Próximos passos

- [API de Contatos](contacts.md) — vincule tarefas ao contato correto
- [API de Webhooks](webhooks.md) — seja notificado sobre `Task Created`, `Task Updated` e `Task Completed`
- [Referência da API](reference.md) — o explorador de endpoints interativo completo