Criar tarefa
POST /tasks — cria uma tarefa para um membro da equipe, vinculada a um negócio, contato ou conversa, sem enviar nada ao contato.
/tasks
Escopo necessário: tasks:write
Cria uma tarefa na organização (resolvida pela API key) para um membro da equipe, vinculada a um negócio, contato ou conversa. A tarefa fica dentro do CRM: nada é enviado ao contato e nenhuma automação é disparada.
Endpoint
POST https://crm.oficinamartech.com/api/v1/tasksCabeçalhos
| Cabeçalho | Obrigatório | Descrição |
|---|---|---|
Authorization | Sim | Bearer + a API key. |
Content-Type | Sim | application/json. |
Idempotency-Key | Sim | De 1 a 128 letras, números, ponto, hífen, sublinhado ou dois-pontos. Veja Repetição. |
Corpo
O corpo tem no máximo 64 KiB. Um campo fora desta tabela é recusado com 400.
| Campo | Tipo | Obrigatório | Descrição |
|---|---|---|---|
title | string (1-200) | Sim | O que deve ser feito. |
description | string (1-4000) | Não | Detalhes da tarefa. |
type | task | call | email | whatsapp | meeting | reminder | Não | Rótulo do que a pessoa deve fazer. Padrão: task. Não envia mensagem, e-mail nem agenda reunião. |
priority | low | medium | high | urgent | Não | Prioridade. Padrão: medium. |
due_at | string ISO 8601 com offset | Sim | Vencimento, por exemplo 2026-11-20T15:00:00-03:00. |
assigned_to | UUID | Não | Responsável (user_id de GET /members). Sem ele, quem criou a chave. |
deal_id | UUID | * | Negócio da tarefa. |
contact_id | UUID | * | Contato da tarefa. |
conversation_id | UUID | * | Conversa da tarefa. |
* Informe ao menos um entre deal_id, contact_id e conversation_id.
type é só um rótulo para organizar o trabalho da equipe. Uma tarefa
whatsapp ou email não envia mensagem, e uma meeting não cria
agendamento.
Exemplo
curl -s -X POST "https://crm.oficinamartech.com/api/v1/tasks" \
-H "Authorization: Bearer crm_live_SEU_PREFIXO_SEU_SEGREDO" \
-H "Content-Type: application/json" \
-H "Idempotency-Key: proposta-d3a1c0de-2026-11-20" \
-d '{
"title": "Enviar proposta revisada",
"description": "Incluir o desconto combinado na ligação.",
"type": "call",
"priority": "high",
"due_at": "2026-11-20T15:00:00-03:00",
"assigned_to": "11111111-58cc-4372-a567-0e02b2c3d479",
"deal_id": "d3a1c0de-58cc-4372-a567-0e02b2c3d479"
}'Resposta 201
{
"replayed": false,
"task": {
"id": "7a5c7a5c-58cc-4372-a567-0e02b2c3d479",
"title": "Enviar proposta revisada",
"description": "Incluir o desconto combinado na ligação.",
"type": "call",
"priority": "high",
"status": "pending",
"assigned_to": "11111111-58cc-4372-a567-0e02b2c3d479",
"created_by": "22222222-58cc-4372-a567-0e02b2c3d479",
"deal_id": "d3a1c0de-58cc-4372-a567-0e02b2c3d479",
"contact_id": null,
"conversation_id": null,
"due_at": "2026-11-20T18:00:00.000Z",
"completed_at": null,
"completed_by": null,
"created_at": "2026-11-13T14:02:31.000Z",
"updated_at": "2026-11-13T14:02:31.000Z"
}
}A tarefa tem o mesmo formato de GET /tasks.
Repetição e idempotência
O Idempotency-Key vale por chave de API. Repetir o mesmo pedido com a mesma chave devolve a tarefa original com 200 e replayed: true, sem criar outra. Use uma chave por tarefa lógica e, se o resultado de uma chamada ficou incerto, repita com a mesma chave.
A mesma chave com um pedido diferente responde 409 idempotency_conflict.
Erros
| Status | Código | Quando |
|---|---|---|
400 | invalid_idempotency_key | Idempotency-Key ausente ou fora do formato. |
400 | invalid_json | Corpo que não é JSON. |
400 | invalid_payload | Campo desconhecido, ausente ou inválido, ou nenhum vínculo informado. |
400 | invalid_links | Negócio, contato ou conversa que não pertence à organização. |
400 | invalid_assignee | O responsável não é membro aceito da organização. |
401 | missing_api_key / invalid_api_key | API key ausente, inválida, expirada ou revogada. |
403 | missing_scope | A chave não tem o escopo tasks:write. |
409 | idempotency_conflict | A chave de idempotência já foi usada com outro pedido. |
413 | payload_too_large | Corpo acima de 64 KiB. |
429 | rate_limited | Acima do limite de requisições por chave ou por organização. |
429 | daily_limit | Teto das conexões de agente atingido (abaixo). Nada foi gravado. |
500 | — | Erro interno. Repita com a mesma chave de idempotência. |
Teto das conexões de agente
As chaves criadas por conexões de agente (MCP) de uma mesma pessoa fazem, juntas, no máximo 200 escritas (tarefas e notas) a cada 24 horas por organização. Acima disso a resposta é 429 com code: "daily_limit" e nada é gravado; repetir não resolve. Chaves de integração criadas em Configurações → API não têm esse teto.