Tarefas
* só DEFINE quando a tarefa ainda não tem external_id; trocar um já gravado é 409 — ver §27.
{
"id": "5b9e2c7f-8d4a-4c1b-9a6e-7d3f5b8c2a38",
"title": "Ligar pro lead",
"description": null,
"status": "pending",
"priority": "high",
"due_date": "2026-07-05",
"assigned_to": "1b7c9d2e-5f3a-4e8b-9c1d-2a6f4b8e3d57",
"contact_id": "9f1e4b7a-2d5c-4f8e-8b3a-6c9d2e5f1a73",
"company_id": null,
"deal_id": null,
"external_id": null,
"completed_at": null,
"created_at": "2026-07-02T12:00:00.000Z",
"updated_at": "2026-07-02T12:00:00.000Z"
}| Campo | Tipo | Criar | Editar | Regras |
|---|---|---|---|---|
title |
texto | obrigatório | opcional | 2–120 |
description |
texto | null | opcional | opcional | até 1000 |
status |
enum | opcional (nasce pending se omitido) |
opcional | pending, in_progress, done |
priority |
enum | obrigatório | opcional | low, medium, high |
due_date |
texto | null | opcional | opcional | AAAA-MM-DD |
contact_id / company_id / deal_id |
uuid | null | opcional | opcional | precisam existir na conta |
assigned_to |
uuid | null | opcional | opcional | pessoa ativa da equipe |
external_id |
texto | null | opcional | opcional* | até 255 — ver §27 |
completed_at |
texto (data-hora) | null | opcional** | — (só leitura) | ver abaixo |
* só DEFINE quando a tarefa ainda não tem external_id; trocar um já gravado é 409 — ver §27.
** completed_at só existe numa chave com o escopo import:write, e só junto de
status: "done" na mesma chamada — mandá-lo sem o escopo, ou sem a tarefa nascer concluída,
responde 400 nomeando o campo, e nada é gravado.
| Método | Escopo | Descrição |
|---|---|---|
GET/api/tasks |
tasks:read |
Lista. Filtros: ?status=, ?priority=, ?deal_id=, ?contact_id=, ?external_id=, ?created_after=, ?created_before=, ?updated_after=, ?updated_before=, ?format=csv |
GET/api/tasks/{id} |
tasks:read |
Uma tarefa |
POST/api/tasks |
tasks:write |
Cria (201) |
PATCH/api/tasks/{id} |
tasks:write |
Edição parcial, inclui concluir |
DELETE/api/tasks/{id} |
tasks:write |
Exclui (204) |
Marcar status: "done" dispara o webhook task.completed, igual a concluir pela tela, e grava
completed_at com a hora exata — voltando o status pra qualquer outro valor, completed_at
limpa. Isso vale tanto por aqui quanto pela tela: são o mesmo mecanismo por trás.
Trazendo tarefa já concluída de outra ferramenta (só com import:write)
Migrar uma base de outro CRM costuma trazer tarefa que já nasceu concluída — sem o escopo
import:write, toda tarefa criada por aqui nasce com completed_at vazio até alguém marcar
status: "done" de verdade. Com o escopo, POST/api/tasks aceita status: "done" +
completed_at juntos na criação, e o valor informado é o que fica gravado (não é substituído
pela hora da chamada):
{
"title": "Ligação de retomada (importada)",
"priority": "medium",
"status": "done",
"completed_at": "2025-11-03T14:22:00Z"
}Tarefa gravada antes de completed_at existir (histórico anterior a esta versão da API)
devolve "completed_at": null no GET, mesmo já concluída — não há como saber quando cada uma
foi concluída, então o campo fica vazio em vez de inventar uma data.