/integrations/external/tasks para listar e criar tarefas, e /integrations/external/tasks/{id} para consultar, atualizar ou excluir. As permissões são crm/task.read, crm/task.create, crm/task.update e crm/task.delete. O usuário criador da chave é o ator das operações, e as consultas e alterações respeitam o acesso dele às tarefas no CRM.
Criar uma tarefa
crm_task_type_id e title são obrigatórios. O título aceita até 100 caracteres. A tarefa pode ter um responsável e, no máximo, um vínculo entre lead, oportunidade, entrega, pessoa, organização ou cliente.
sync_warning, a tarefa foi criada, mas algum processamento posterior apresentou problema; consulte o registro antes de tentar criá-lo novamente.
Quando omitidos, responsible_id assume o criador da chave, crm_task_stage_id assume a primeira etapa ativa que não seja de conclusão e priority assume 1 (normal). Sem end_date, o término é calculado pela duração padrão do tipo de tarefa. description aceita texto simples ou HTML; o HTML é higienizado e mantém apenas formatação básica, listas, tabelas e links, de modo que o valor retornado pode diferir do enviado.
As combinações abaixo retornam 400:
- Vínculo com lead ou oportunidade sem
start_date, ou tarefa de tipo reunião sem data. end_datesemstart_date, ouend_datejunto comhas_time: false. Sem horário, a tarefa vale para o dia inteiro.reminders_minutesem tarefa sem data e hora.- Mais de um vínculo no mesmo corpo.
- Tarefa pessoal (
is_personal: true) com vínculo ou com responsável diferente do criador da chave.
Subtarefas, tags e filtros
parent_task_id vincula uma subtarefa à tarefa pai. No retorno, parent_task_id, parent_task, hierarchy_level e is_subtask descrevem a hierarquia, que aceita até dois níveis abaixo da tarefa raiz. Subtarefas não podem ter recorrência própria.
Envie take explicitamente para limitar a página: sem take, a listagem retorna todos os registros e ignora skip. Sem parâmetros order_*, a ordem é por criação decrescente, e as tarefas sem data aparecem antes das demais.
Na listagem, hierarchy_mode=grouped organiza os registros em árvores no campo subtasks; total conta as raízes paginadas, e os filtros valem para as raízes, não para as subtarefas devolvidas dentro delas. hierarchy_mode=flat retorna uma lista plana. O filtro parent_task_id permite buscar tarefas de um pai específico.
Use tag_ids no corpo para definir as tags e consulte os resumos em tags. Na listagem, há filtros tag_id e tag_ids (lista separada por vírgulas), além de responsável, tipo, etapa, prioridade, vínculos e intervalos de datas. search procura apenas no título. completed_last=true coloca as pendentes antes das concluídas, preservando a ordenação escolhida dentro de cada grupo.
Os intervalos de datas (start_date_*, completed_at_* e created_at_*) trabalham no horário de Brasília. Envie YYYY-MM-DD: *_from considera sempre o início do dia informado e *_to, o fim do dia. *_to também aceita data e hora no horário de Brasília, sem sufixo de fuso (YYYY-MM-DDTHH:mm:ss). Evite Z ou offset nesses filtros: o valor não é convertido para o horário de Brasília e o limite fica deslocado.
Atualizar com controle de versão
OPUT aceita atualização parcial. Envie o último updated_at recebido como expected_updated_at para detectar alterações concorrentes:
expected_updated_at é opcional por compatibilidade. Quando informado e desatualizado, a API retorna 409. Recarregue a tarefa antes de reenviar a atualização.
Para trocar o vínculo da tarefa, envie apenas o novo campo crm_*_id: ele substitui o vínculo atual. Sem nenhum desses campos, o vínculo é mantido.
Concluir e reabrir
is_completed: true conclui a tarefa. O horário de conclusão é sempre o do servidor; completed_at no corpo é ignorado. is_completed: false não reabre a tarefa: para reabrir, envie em crm_task_stage_id uma etapa que não seja de conclusão. Enviar is_completed: true junto com uma etapa que não é de conclusão retorna 400.
Em tarefas de tipo reunião, meeting_outcome registra o resultado: 1 realizada, 2 não compareceu, 3 cancelada e 4 reagendada. No PUT, informar um resultado também conclui a tarefa. Com meeting_outcome: 4 e uma nova start_date ou end_date, a tarefa original é concluída e a API cria e retorna a tarefa reagendada, com outro id. Em tarefas de outros tipos, meeting_outcome, meeting_outcome_notes, meeting_mode, meeting_location e meeting_description retornam 400.
Recorrência
Para criar uma recorrência,recurrence.pattern e recurrence.interval são obrigatórios. O padrão aceita every_n_days ou weekly, e o intervalo é um inteiro entre 1 e 365. Para weekly, informe week_days com um a sete dias únicos; para end_type=until_date, informe until_date, que não pode anteceder o início da tarefa.
Em tarefas recorrentes, recurrence_scope define o alcance da alteração ou exclusão: only_this (padrão), this_and_future, open_only ou all. Com only_this, um recurrence enviado para uma tarefa que já pertence a uma série é ignorado. Quando a regra de recorrência é criada ou alterada, as tarefas do escopo são recriadas e o PUT retorna a tarefa principal da nova série, com outro id; use sempre o id do retorno nas chamadas seguintes.
O DELETE aceita recurrence_scope em um corpo JSON, exclui também as subtarefas e retorna { "success": true }.
Erros de escrita
NoPOST, PUT e DELETE, uma referência inexistente retorna 400, e não 404: isso vale para a própria tarefa, o tipo, a etapa, o responsável, as tags e o registro vinculado. O 404 fica restrito à consulta por ID e a um parent_task_id inexistente. 403 indica permissão ausente na chave, tarefa ou tarefa pai fora do alcance do criador da chave, ou criador da chave inativo.
Reuniões e sincronização de agendas
Os camposcreate_event, create_meeting, create_online_meeting_link e meeting_provider controlam a integração com a agenda, conforme o provedor e o tipo de tarefa. A conexão do usuário precisa estar disponível para a operação solicitada, e a tarefa precisa ter data e hora.
Qualquer um desses indicadores exige
meeting_provider, e, na criação, meeting_provider exige create_event ou create_meeting. create_meeting não aceita meeting_participants nem meeting_mode: in_person. A integração com agenda não pode ser combinada com recurrence. Combinações fora dessas regras retornam 400.
meeting_mode aceita online ou in_person. Para in_person, informe meeting_location (até 500 caracteres) e não solicite um link online. meeting_description aceita HTML com formatação básica: até 20.000 caracteres de entrada e 5.000 caracteres de texto normalizado. meeting_participants aceita até 100 e-mails únicos, normalizados em letras minúsculas.
No retorno, consulte:
meeting_event: informações do evento, local, participantes, permissões de edição e situação da sincronização.meeting_sync: operação de sincronização, tentativas, próxima tentativa e eventual erro. A persistência da tarefa pode ocorrer antes de a agenda concluir a sincronização.meeting_attendees: respostas dos convidados (needs_action,accepted,declinedoutentative).recordings: URLs temporárias de gravações e transcrições, incluindo formatos VTT e TXT quando disponíveis.
include_non_actionable=true para incluí-los e observe origin, is_actionable e calendar_lifecycle_status. O término de um compromisso importado não significa automaticamente que uma tarefa operacional foi concluída.