> ## Documentation Index > Fetch the complete documentation index at: https://docs.wegly.com.br/llms.txt > Use this file to discover all available pages before exploring further. # Tarefas e agendas > Tarefas, subtarefas, tags, recorrência, reuniões e controle de versão na API externa. Use `/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. ```json theme={null} { "crm_task_type_id": "11111111-1111-4111-8111-111111111111", "title": "Retornar contato sobre a proposta", "crm_deal_id": "22222222-2222-4222-8222-222222222222", "priority": 2, "start_date": "2026-09-15T13:00:00-03:00", "end_date": "2026-09-15T13:30:00-03:00", "has_time": true, "tag_ids": ["33333333-3333-4333-8333-333333333333"] } ``` Substitua os UUIDs dos exemplos pelos IDs da sua empresa. A resposta de criação é a tarefa formatada. Se houver `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_date` sem `start_date`, ou `end_date` junto com `has_time: false`. Sem horário, a tarefa vale para o dia inteiro. * `reminders_minutes` em 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 O `PUT` aceita atualização parcial. Envie o último `updated_at` recebido como `expected_updated_at` para detectar alterações concorrentes: ```json theme={null} { "expected_updated_at": "2026-09-10T12:00:00.000Z", "title": "Confirmar aprovação da proposta", "is_completed": true } ``` Na API externa, `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 No `POST`, `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 campos `create_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. | Provedor | Combinações aceitas | | - | - | | `google_calendar_integration` | `create_event`, com `create_online_meeting_link` opcional. Não aceita `create_meeting`. | | `teams_integration` | `create_event` ou `create_meeting`, nunca os dois. Não aceita `create_online_meeting_link`. | 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`, `declined` ou `tentative`). * `recordings`: URLs temporárias de gravações e transcrições, incluindo formatos VTT e TXT quando disponíveis. Por padrão, a listagem omite eventos importados de agendas que não são tarefas acionáveis. Use `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. This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.