Skip to main content

Módulo 14: Tarefas & Follow-up — API

Status: Rascunho Inicial Regras de negócio: ver regras-negocio/14_tarefas.md Domínio: ver dominio/tarefa.md

1. Contratos de API (RESTful)​

1.1 Consulta e Manipulação de Tarefas​

GET /api/tarefas
  Auth: Todos os usuários autenticados
  Query: ?responsavel_id=uuid&status=PENDENTE&atrasada=true&vinculo_tipo=LEAD&vinculo_id=uuid
  Return: [{ id, responsavel_id, tipo, titulo, data_prevista, status, gerada_pelo_sistema, vinculo_tipo, vinculo_id }]
  Nota: Usuários sem privilégios de gestão só podem listar tarefas atribuídas a si próprios.

POST /api/tarefas
  Auth: Todos os usuários autenticados
  Body:
  {
    "titulo": "string",
    "descricao": "string | null",
    "tipo": "LIGACAO | WHATSAPP | EMAIL | REUNIAO | LEMBRETE",
    "data_prevista": "datetime",
    "responsavel_id": "uuid",
    "vinculo_tipo": "LEAD | CLIENTE | PROPOSTA | CONTRATO | PLANO_CONTRATADO | null",
    "vinculo_id": "uuid | null"
  }
  Return: { id, status: "PENDENTE" }
  Errors:
    400 — data_prevista menor que data/hora atual para criação manual
    422 — relacionamento polimórfico inválido (vinculo_id não coincide com vinculo_tipo)

POST /api/tarefas/{id}/concluir
  Auth: Responsável | Gestor
  Body:
  {
    "nota_interacao": "string",
    "gerar_proxima_tarefa": {
      "titulo": "string",
      "tipo": "LIGACAO | WHATSAPP | EMAIL | REUNIAO | LEMBRETE",
      "data_prevista": "datetime"
    } | null
  }
  Return: 200 OK
  {
    "status": "CONCLUIDA",
    "data_conclusao": "datetime",
    "interacao_id": "uuid | null",
    "nova_tarefa_id": "uuid | null"
  }
  Nota: O backend cria automaticamente a interação na timeline do cliente.

PATCH /api/tarefas/{id}/reagendar
  Auth: Responsável | Gestor
  Body: { nova_data_prevista: "datetime", motivo: "string" }
  Return: 200 OK
  Nota: Registra alteração de prazo e adiciona o motivo na timeline de auditoria da tarefa.

POST /api/tarefas/{id}/reatribuir
  Auth: Gestor | Admin
  Body: { responsavel_id: "uuid" }
  Return: 200 OK

2. Schema de Dados​

Tarefa​

{
  "id": "uuid",
  "tenant_id": "uuid",
  "responsavel_id": "uuid",
  "criador_id": "uuid",
  "tipo": "LIGACAO | WHATSAPP | EMAIL | REUNIAO | LEMBRETE | SISTEMA",
  "titulo": "string",
  "descricao": "string | null",
  "data_prevista": "datetime",
  "status": "PENDENTE | CONCLUIDA | CANCELADA",
  "vinculo_tipo": "LEAD | CLIENTE | PROPOSTA | CONTRATO | PLANO_CONTRATADO | null",
  "vinculo_id": "uuid | null",
  "gerada_pelo_sistema": "boolean",
  "data_conclusao": "datetime | null",
  "created_at": "datetime",
  "updated_at": "datetime"
}

3. Segurança e Boas Práticas​

RegraImplementação
Autenticação e Controle de EscopoOperadores sem permissão de gerenciamento não podem ler ou alterar tarefas de terceiros (responsavel_id diferente do ID do usuário autenticado).
Transação de TransferênciaO processo de redistribuição de carteira (Módulo 06) deve executar a migração de tarefas pendentes em lote dentro de uma transação SQL (transactional block). Em caso de falha, realizar rollback completo.
Integridade PolimórficaValidar o par vinculo_tipo e vinculo_id dinamicamente no backend antes da persistência no banco, verificando a existência real do registro nas tabelas correspondentes.
Deduplicação de Tarefas AutomáticasAntes de persistir uma tarefa gerada pelo sistema, verificar se já existe outra tarefa ativa do tipo SISTEMA com o mesmo título e vínculo pendente para a entidade. Se houver, a operação de escrita deve ser cancelada.
Criação de InteraçãoA conclusão de uma tarefa de contato vinculada a um Lead ou Cliente gera obrigatoriamente um registro correspondente na tabela Interacao na mesma transação.