---
title: "Tarefas"
slug: tasks
group: "Referência da API"
source: https://linkzap.orion.moe/developers/tasks
openapi: https://linkzap.orion.moe/openapi.json
---

# Tarefas

O que a equipe tem de fazer: ligar de volta, mandar a proposta, cobrar o retorno. Uma tarefa pode ser de um contato, de um negócio ou de ninguém, e tem responsável e prazo.

## Listar tarefas

### `GET /api/v1/tasks`
Lista as tarefas, da criada mais recentemente para a mais antiga. Paginada. A chave de API vê as tarefas de **toda a equipe**.

**Parâmetros da URL**

| Campo | Tipo | Descrição |
| --- | --- | --- |
| `status` | texto | `open` (em aberto) ou `done` (concluídas). Qualquer outro valor responde 422. |
| `contactId` | texto | As tarefas de um contato. |
| `dealId` | texto | As tarefas de um negócio. |
| `assigneeId` | texto | As tarefas de uma pessoa da equipe. |
| `page` | inteiro | A partir de 1. |
| `limit` | inteiro | De 1 a 200. Padrão 50. |

Pedido:

```bash
curl "https://linkzap.orion.moe/api/v1/tasks?status=open" \
  -H "Authorization: Bearer lz_SUA_CHAVE"
```

Resposta:

```json
{
  "data": [
    {
    "id": "tsk_5d90...",
    "title": "Ligar de volta",
    "notes": null,
    "contactId": "ctt_3c81...",
    "dealId": null,
    "assigneeId": "usr_44e1...",
    "dueAt": "2026-10-08T02:59:59.000Z",
    "dueHasTime": false,
    "done": false,
    "doneAt": null,
    "createdAt": "2026-10-06T13:00:00.000Z",
    "updatedAt": "2026-10-06T13:00:00.000Z"
  }
  ],
  "page": 1,
  "limit": 50,
  "total": 1
}
```

`dueAt` vem em UTC. Com `dueHasTime: false` o prazo é o dia inteiro, e o horário gravado é o **fim daquele dia no fuso da organização** — por isso `02:59:59Z` para um dia em Brasília.

## Criar uma tarefa

### `POST /api/v1/tasks`
Cria uma tarefa. Responde 201. Quem recebe a tarefa (`assigneeId`) é lembrado por e-mail: na hora marcada ou, sem hora, às 9h do dia.

**Corpo (JSON)**

| Campo | Tipo | Obrigatório | Descrição |
| --- | --- | --- | --- |
| `title` | texto | obrigatório | O que tem de ser feito. Até 160 caracteres. |
| `notes` | texto | — | Detalhes, para quem vai fazer. Até 2.000 caracteres. |
| `contactId` | texto | — | O contato da tarefa. Opcional. |
| `phone` | texto | — | Em vez de `contactId`: o telefone de um contato que já existe. 404 se não houver. Não mande os dois. |
| `dealId` | texto | — | O negócio da tarefa. Com ele, o contato é o do negócio. |
| `assigneeId` | texto | — | O id de uma pessoa da equipe. 422 se não for da equipe. |
| `dueOn` | data | — | O dia do prazo, `AAAA-MM-DD`, **no fuso da organização**. |
| `dueTime` | hora | — | `HH:MM`, opcional. Só vale junto de `dueOn`. |

Pedido:

```bash
curl -X POST https://linkzap.orion.moe/api/v1/tasks \
  -H "Authorization: Bearer lz_SUA_CHAVE" \
  -H "Content-Type: application/json" \
  -d '{
    "phone": "5592999990000",
    "title": "Ligar de volta",
    "assigneeId": "usr_44e1...",
    "dueOn": "2026-10-07"
  }'
```

Resposta:

```json
{
  "data": {
    "id": "tsk_5d90...",
    "title": "Ligar de volta",
    "notes": null,
    "contactId": "ctt_3c81...",
    "dealId": null,
    "assigneeId": "usr_44e1...",
    "dueAt": "2026-10-08T02:59:59.000Z",
    "dueHasTime": false,
    "done": false,
    "doneAt": null,
    "createdAt": "2026-10-06T13:00:00.000Z",
    "updatedAt": "2026-10-06T13:00:00.000Z"
  }
}
```

## Concluir, reabrir e editar

### `POST /api/v1/tasks/{id}`
Muda uma tarefa. Mande só o que quer mudar. Concluir a que já está concluída não muda nada e responde 200.

**Corpo (JSON)**

| Campo | Tipo | Descrição |
| --- | --- | --- |
| `done` | booleano | `true` conclui; `false` reabre. |
| `title` | texto | Novo título. |
| `notes` | texto ou nulo | Novos detalhes; `null` apaga. |
| `assigneeId` | texto ou nulo | Novo responsável; `null` tira. |
| `dueOn` | data ou nulo | Novo dia do prazo; `null` tira o prazo inteiro. Mudar só o dia mantém a hora que a tarefa já tinha. |
| `dueTime` | hora ou nulo | Nova hora; `null` volta a valer o dia inteiro. Pode vir sem `dueOn` quando a tarefa já tem dia (a hora entra nele); numa tarefa sem dia, responde 422. |

Pedido:

```bash
curl -X POST https://linkzap.orion.moe/api/v1/tasks/tsk_5d90... \
  -H "Authorization: Bearer lz_SUA_CHAVE" \
  -H "Content-Type: application/json" \
  -d '{ "done": true }'
```

Resposta:

```json
{
  "data": {
    "id": "tsk_5d90...",
    "title": "Ligar de volta",
    "notes": null,
    "contactId": "ctt_3c81...",
    "dealId": null,
    "assigneeId": "usr_44e1...",
    "dueAt": "2026-10-08T02:59:59.000Z",
    "dueHasTime": false,
    "done": true,
    "doneAt": "2026-10-07T14:10:00.000Z",
    "createdAt": "2026-10-06T13:00:00.000Z",
    "updatedAt": "2026-10-07T14:10:00.000Z"
  }
}
```

Criar dispara o webhook `task.created` e concluir dispara `task.completed` — também quando a tarefa nasce de um fluxo ou da Aura. Reabrir não dispara evento.