Tarefas (Tasks)

Esta seção documenta os endpoints para gerenciamento de tarefas no CRM.

---

📖 Visão Geral

Tarefas representam atividades de acompanhamento que podem ser vinculadas a negociações. Exemplos:

• Ligar para cliente
• Agendar visita
• Enviar proposta
• Follow-up

---

📊 Endpoints

Listar Tarefas

GET /api/v1/crm/tasks

Parâmetros de Query:

Parâmetro	Tipo	Descrição
page	number	Número da página (default: 1)
pageSize	number	Itens por página (default: 50, max: 100)
stage	string	Filtrar por etapa: todo, done
status	string	Filtrar por status: open, completed
dealId	uuid	Filtrar por negociação
assignedToId	uuid	Filtrar por responsável
dueBefore	datetime	Tarefas com vencimento antes de
dueAfter	datetime	Tarefas com vencimento após

Exemplo:

curl -X GET "https://app.garagem.ai/api/v1/crm/tasks?stage=todo&pageSize=20" \
  -H "Authorization: Bearer sua_api_key"

Resposta:

{
  "items": [
    {
      "id": "uuid-da-tarefa",
      "title": "Ligar para João Silva",
      "description": "Confirmar interesse no apartamento",
      "stage": "todo",
      "status": "open",
      "dueDate": "2024-01-20T14:00:00Z",
      "dealId": "uuid-do-deal",
      "assignedToId": "uuid-do-usuario",
      "createdAt": "2024-01-15T10:30:00Z"
    }
  ],
  "total": 45,
  "page": 1,
  "pageSize": 20
}

Buscar Tarefa por ID

GET /api/v1/crm/tasks/{id}

Criar Tarefa

POST /api/v1/crm/tasks

Body:

{
  "title": "Agendar visita ao imóvel",
  "description": "Cliente quer visitar o apartamento em Copacabana",
  "dueDate": "2024-01-20T14:00:00Z",
  "dealId": "uuid-do-deal",
  "stage": "todo",
  "status": "open"
}

Exemplo:

curl -X POST https://app.garagem.ai/api/v1/crm/tasks \
  -H "Authorization: Bearer sua_api_key" \
  -H "Content-Type: application/json" \
  -d '{
    "title": "Agendar visita ao imóvel",
    "description": "Cliente quer visitar o apartamento em Copacabana",
    "dueDate": "2024-01-20T14:00:00Z",
    "dealId": "uuid-do-deal",
    "stage": "todo",
    "status": "open",
    "custom": {
      "tipo_visita": "presencial",
      "duracao_estimada": 60,
      "endereco_visita": "Rua Example, 123 - Copacabana"
    }
  }'

Resposta:

{
  "id": "uuid-da-tarefa-criada",
  "title": "Agendar visita ao imóvel",
  "stage": "todo",
  "status": "open",
  "dueDate": "2024-01-20T14:00:00Z",
  "createdAt": "2024-01-15T10:30:00Z"
}

Atualizar Tarefa

PATCH /api/v1/crm/tasks/{id}

Body:

{
  "id": "uuid-da-tarefa",
  "data": {
    "stage": "done",
    "status": "completed",
    "custom": {
      "resultado": "Visita realizada com sucesso",
      "proximos_passos": "Enviar proposta"
    }
  }
}

Exemplo - Marcar como Concluída:

curl -X PATCH https://app.garagem.ai/api/v1/crm/tasks/uuid-da-tarefa \
  -H "Authorization: Bearer sua_api_key" \
  -H "Content-Type: application/json" \
  -d '{
    "id": "uuid-da-tarefa",
    "data": {
      "stage": "done",
      "status": "completed"
    }
  }'

Deletar Tarefa

DELETE /api/v1/crm/tasks/{id}

---

📋 Campos da Tarefa

Campos Principais

Campo	Tipo	Obrigatório	Descrição
title	string	Sim	Título da tarefa
description	string	Não	Descrição detalhada
stage	enum	Sim	todo ou done
status	enum	Sim	open, completed, cancelled
dueDate	datetime	Não	Data de vencimento
dealId	uuid	Não	ID da negociação vinculada
assignedToId	uuid	Não	ID do usuário responsável
custom	object	Não	Campos customizados

Campos Customizados Comuns

{
  "custom": {
    "tipo_tarefa": "visita",
    "prioridade": "alta",
    "duracao_estimada": 60,
    "endereco": "Rua Example, 123",
    "observacoes": "Cliente prefere horário da tarde"
  }
}

---

🔄 Fluxo de Estados

┌─────────┐     ┌─────────────┐     ┌───────────┐
│  todo   │ ──▶ │   done      │     │ cancelled │
│ (open)  │     │ (completed) │     │           │
└─────────┘     └─────────────┘     └───────────┘
     │                                    ▲
     └────────────────────────────────────┘

---

📅 Filtrar por Data

Tarefas vencidas:

curl -X GET "https://app.garagem.ai/api/v1/crm/tasks?stage=todo&dueBefore=2024-01-15T00:00:00Z" \
  -H "Authorization: Bearer sua_api_key"

Tarefas da próxima semana:

curl -X GET "https://app.garagem.ai/api/v1/crm/tasks?stage=todo&dueAfter=2024-01-15T00:00:00Z&dueBefore=2024-01-22T00:00:00Z" \
  -H "Authorization: Bearer sua_api_key"

---

📚 Mais Informações

• Negociações - Vincular tarefas a negociações
• Webhooks - Receber eventos de tarefas
• Exemplos Práticos - Mais exemplos de uso