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.