Atividades

O recurso Atividade registra uma interação ligada a um negócio: ligação, reunião, tarefa, e-mail, nota ou outro tipo do catálogo do pipeline. Toda atividade pertence a exatamente um negócio (lead_id) e não muda de negócio depois de criada. A rota base é /crm/activities. Escopo: crm.view para leitura, crm.leads.edit para todas as operações de escrita.

Esquema do recurso

Campo	Tipo	Obrigatório	Descrição
id	string (UUID)	leitura	Identificador da atividade.
funnel_id	string (UUID)	leitura	Pipeline do negócio ao qual a atividade pertence.
lead_id	string (UUID)	sim (só na criação)	Negócio ao qual a atividade pertence. Não editável depois de criada.
activity_type_id	string (UUID)	sim	Tipo de atividade, deve pertencer ao catálogo do pipeline do negócio.
type_name	string	leitura	Nome do tipo no momento da criação (ex.: “Ligação”).
type_icon	string	leitura	Ícone do tipo no momento da criação.
type_color	string | null	leitura	Cor do tipo no momento da criação.
subject	string	sim	Título/assunto da atividade. Máx. 200 caracteres.
body	string | null	não	Corpo livre (HTML). Máx. 20000 caracteres.
location	string | null	não	Local. Máx. 200 caracteres.
due_at	string (ISO-8601) | null	não	Data/hora prevista.
duration_minutes	integer | null	não	Duração estimada, 0 a 65535.
done_at	string (ISO-8601) | null	leitura	Data/hora de conclusão. null enquanto pendente.
assigned_user_id	string (UUID) | null	não	Usuário responsável pela atividade.
assigned_name	string | null	leitura	Nome do responsável no momento da atribuição.
created_by_user_id	string (UUID) | null	leitura	Sempre null quando a atividade é criada pela API pública.
created_by_name	string | null	leitura	"API · <nome da chave>" quando criada pela API pública.
created_at	string (ISO-8601)	leitura	Data de criação.
updated_at	string (ISO-8601)	leitura	Data da última atualização.

activity_type_id não tem endpoint de catálogo ainda

A API pública não tem, hoje, um endpoint para listar os tipos de atividade de um pipeline. Para descobrir um activity_type_id válido, use o valor retornado em uma atividade já existente (GET /crm/activities ou GET /crm/deals/{id}/activities) ou consulte o painel Maestron. Um pipeline criado pela API pública nasce com 8 tipos padrão (Ligação, Reunião, Tarefa, Prazo, E-mail, Almoço, WhatsApp, Nota).

Listar atividades

GET /crm/activities Copiar para LLM

Listar atividades

Lista as atividades da empresa, paginado.

Parâmetros de query

Campo	Tipo	Obrigatório	Descrição
per_page	integer	—	Itens por página. De 1 a 100, padrão 20.
deal_id	string	—	Filtra pelas atividades de um negócio.

cURLPHPPythonNode.jsC#HTTP / Postman

curl -X GET https://api.maestron.com.br/api/v1/crm/activities \
  -H "Authorization: Bearer SEU_TOKEN"

<?php
$client = new \GuzzleHttp\Client();
$response = $client->request('GET', 'https://api.maestron.com.br/api/v1/crm/activities', [
    'headers' => [
        'Authorization' => 'Bearer SEU_TOKEN',
        'Accept' => 'application/json',
    ],
]);
$data = json_decode($response->getBody(), true);

import requests
headers = {"Authorization": "Bearer SEU_TOKEN"}
response = requests.get(
    "https://api.maestron.com.br/api/v1/crm/activities",
    headers=headers,
)
data = response.json()

const response = await fetch("https://api.maestron.com.br/api/v1/crm/activities", {
  method: "GET",
  headers: {
    "Authorization": "Bearer SEU_TOKEN",
  },
});
const data = await response.json();

using var client = new HttpClient();
client.DefaultRequestHeaders.Authorization =
    new System.Net.Http.Headers.AuthenticationHeaderValue("Bearer", "SEU_TOKEN");
var response = await client.GetAsync("https://api.maestron.com.br/api/v1/crm/activities");
var data = await response.Content.ReadAsStringAsync();

GET /crm/activities HTTP/1.1
Host: api.maestron.com.br
Authorization: Bearer SEU_TOKEN

Respostas

200 · Sucesso401 · Não autenticado403 · Sem escopo

{
  "message": "Atividades.",
  "data": [
    {
      "id": "d4e5f6a7-8b9c-4d0e-1f2a-3b4c5d6e7f8a",
      "funnel_id": "b7e8c1a2-3d4f-4a5b-8c9d-0e1f2a3b4c5d",
      "lead_id": "f1a2b3c4-5d6e-4f7a-8b9c-0d1e2f3a4b5c",
      "activity_type_id": "e5f6a7b8-9c0d-4e1f-2a3b-4c5d6e7f8a9b",
      "type_name": "Ligação",
      "type_icon": "phone",
      "type_color": "#2196f3",
      "subject": "Ligação de follow-up",
      "body": null,
      "location": null,
      "due_at": "2026-09-05T14:00:00Z",
      "duration_minutes": null,
      "done_at": null,
      "assigned_user_id": null,
      "assigned_name": null,
      "created_by_user_id": null,
      "created_by_name": "API · Integração ERP",
      "created_at": "2026-06-20T14:30:00Z",
      "updated_at": "2026-06-20T14:30:00Z"
    }
  ],
  "meta": {
    "current_page": 1,
    "per_page": 20,
    "total": 1,
    "last_page": 1
  }
}

{
  "message": "Não autenticado.",
  "data": null
}

{
  "message": "A chave não tem o escopo necessário.",
  "data": null
}

Obter uma atividade

GET /crm/activities/{id} Copiar para LLM

Obter atividade

Retorna uma atividade pelo ID.

Parâmetros de caminho

Campo	Tipo	Obrigatório	Descrição
id	string	Sim	ID da atividade (UUID).

cURLPHPPythonNode.jsC#HTTP / Postman

curl -X GET https://api.maestron.com.br/api/v1/crm/activities/{id} \
  -H "Authorization: Bearer SEU_TOKEN"

<?php
$client = new \GuzzleHttp\Client();
$response = $client->request('GET', 'https://api.maestron.com.br/api/v1/crm/activities/{id}', [
    'headers' => [
        'Authorization' => 'Bearer SEU_TOKEN',
        'Accept' => 'application/json',
    ],
]);
$data = json_decode($response->getBody(), true);

import requests
headers = {"Authorization": "Bearer SEU_TOKEN"}
response = requests.get(
    "https://api.maestron.com.br/api/v1/crm/activities/{id}",
    headers=headers,
)
data = response.json()

const response = await fetch("https://api.maestron.com.br/api/v1/crm/activities/{id}", {
  method: "GET",
  headers: {
    "Authorization": "Bearer SEU_TOKEN",
  },
});
const data = await response.json();

using var client = new HttpClient();
client.DefaultRequestHeaders.Authorization =
    new System.Net.Http.Headers.AuthenticationHeaderValue("Bearer", "SEU_TOKEN");
var response = await client.GetAsync("https://api.maestron.com.br/api/v1/crm/activities/{id}");
var data = await response.Content.ReadAsStringAsync();

GET /crm/activities/{id} HTTP/1.1
Host: api.maestron.com.br
Authorization: Bearer SEU_TOKEN

Respostas

200 · Sucesso401 · Não autenticado404 · Não encontrado

{
  "message": "Atividade.",
  "data": {
    "id": "d4e5f6a7-8b9c-4d0e-1f2a-3b4c5d6e7f8a",
    "subject": "Ligação de follow-up"
  }
}

{
  "message": "Não autenticado.",
  "data": null
}

{
  "message": "Recurso não encontrado.",
  "data": null
}

Criar atividade

POST /crm/activities Copiar para LLM

Criar atividade

Cria uma atividade vinculada a um negócio. idempotency_key é opcional — ver Sandbox & Idempotência.

Corpo (body)

Campo	Tipo	Obrigatório	Descrição
lead_id	string	Sim	Negócio ao qual a atividade pertence.
activity_type_id	string	Sim	Tipo de atividade, do catálogo do pipeline do negócio.
subject	string	Sim	Título/assunto. Máx. 200 caracteres.
body	string	—	Corpo livre. Máx. 20000 caracteres.
location	string	—	Local.
due_at	string	—	Data/hora prevista (ISO-8601).
duration_minutes	integer	—	Duração estimada em minutos.
assigned_user_id	string	—	Usuário responsável.
done	boolean	—	Quando true sem done_at explícito, marca como concluída agora.
idempotency_key	string	—	Opcional — evita duplicar em retry.

cURLPHPPythonNode.jsC#HTTP / Postman

curl -X POST https://api.maestron.com.br/api/v1/crm/activities \
  -H "Authorization: Bearer SEU_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "lead_id": "f1a2b3c4-5d6e-4f7a-8b9c-0d1e2f3a4b5c",
    "activity_type_id": "e5f6a7b8-9c0d-4e1f-2a3b-4c5d6e7f8a9b",
    "subject": "Ligação de follow-up",
    "due_at": "2026-09-05T14:00:00Z",
    "idempotency_key": "2c4d6e8a-1b3c-4d5e-9f0a-7b8c9d0e1f2a"
  }'

<?php
$client = new \GuzzleHttp\Client();
$response = $client->request('POST', 'https://api.maestron.com.br/api/v1/crm/activities', [
    'headers' => [
        'Authorization' => 'Bearer SEU_TOKEN',
        'Accept' => 'application/json',
    ],
    'json' => [
        'lead_id' => 'f1a2b3c4-5d6e-4f7a-8b9c-0d1e2f3a4b5c',
        'activity_type_id' => 'e5f6a7b8-9c0d-4e1f-2a3b-4c5d6e7f8a9b',
        'subject' => 'Ligação de follow-up',
        'due_at' => '2026-09-05T14:00:00Z',
        'idempotency_key' => '2c4d6e8a-1b3c-4d5e-9f0a-7b8c9d0e1f2a',
    ],
]);
$data = json_decode($response->getBody(), true);

import requests
headers = {"Authorization": "Bearer SEU_TOKEN"}
payload = {
    "lead_id": "f1a2b3c4-5d6e-4f7a-8b9c-0d1e2f3a4b5c",
    "activity_type_id": "e5f6a7b8-9c0d-4e1f-2a3b-4c5d6e7f8a9b",
    "subject": "Ligação de follow-up",
    "due_at": "2026-09-05T14:00:00Z",
    "idempotency_key": "2c4d6e8a-1b3c-4d5e-9f0a-7b8c9d0e1f2a",
}
response = requests.post(
    "https://api.maestron.com.br/api/v1/crm/activities",
    headers=headers,
    json=payload,
)
data = response.json()

const response = await fetch("https://api.maestron.com.br/api/v1/crm/activities", {
  method: "POST",
  headers: {
    "Authorization": "Bearer SEU_TOKEN",
    "Content-Type": "application/json",
  },
  body: JSON.stringify({
    "lead_id": "f1a2b3c4-5d6e-4f7a-8b9c-0d1e2f3a4b5c",
    "activity_type_id": "e5f6a7b8-9c0d-4e1f-2a3b-4c5d6e7f8a9b",
    "subject": "Ligação de follow-up",
    "due_at": "2026-09-05T14:00:00Z",
    "idempotency_key": "2c4d6e8a-1b3c-4d5e-9f0a-7b8c9d0e1f2a"
  }),
});
const data = await response.json();

using var client = new HttpClient();
client.DefaultRequestHeaders.Authorization =
    new System.Net.Http.Headers.AuthenticationHeaderValue("Bearer", "SEU_TOKEN");
var payload = new StringContent(
    "{\"lead_id\":\"f1a2b3c4-5d6e-4f7a-8b9c-0d1e2f3a4b5c\",\"activity_type_id\":\"e5f6a7b8-9c0d-4e1f-2a3b-4c5d6e7f8a9b\",\"subject\":\"Ligação de follow-up\",\"due_at\":\"2026-09-05T14:00:00Z\",\"idempotency_key\":\"2c4d6e8a-1b3c-4d5e-9f0a-7b8c9d0e1f2a\"}",
    System.Text.Encoding.UTF8, "application/json");
var response = await client.PostAsync("https://api.maestron.com.br/api/v1/crm/activities", payload);
var data = await response.Content.ReadAsStringAsync();

POST /crm/activities HTTP/1.1
Host: api.maestron.com.br
Authorization: Bearer SEU_TOKEN
Content-Type: application/json

{
  "lead_id": "f1a2b3c4-5d6e-4f7a-8b9c-0d1e2f3a4b5c",
  "activity_type_id": "e5f6a7b8-9c0d-4e1f-2a3b-4c5d6e7f8a9b",
  "subject": "Ligação de follow-up",
  "due_at": "2026-09-05T14:00:00Z",
  "idempotency_key": "2c4d6e8a-1b3c-4d5e-9f0a-7b8c9d0e1f2a"
}

Respostas

201 · Criada401 · Não autenticado403 · Sem escopo404 · Negócio não encontrado422 · Validação

{
  "message": "Atividade criada.",
  "data": {
    "id": "d4e5f6a7-8b9c-4d0e-1f2a-3b4c5d6e7f8a",
    "subject": "Ligação de follow-up",
    "done_at": null
  }
}

{
  "message": "Não autenticado.",
  "data": null
}

{
  "message": "A chave não tem o escopo necessário.",
  "data": null
}

{
  "message": "Recurso não encontrado.",
  "data": null
}

{
  "message": "Os dados informados são inválidos.",
  "data": null,
  "errors": {
    "subject": [
      "O campo subject é obrigatório."
    ],
    "activity_type_id": [
      "O campo activity_type_id selecionado é inválido."
    ]
  }
}

Atualizar atividade

lead_id não é aceito no PATCH — a atividade não migra de negócio.

PATCH /crm/activities/{id} Copiar para LLM

Atualizar atividade

Atualização parcial. Sem idempotency_key (PATCH já é naturalmente idempotente).

Parâmetros de caminho

Campo	Tipo	Obrigatório	Descrição
id	string	Sim	ID da atividade (UUID).

Corpo (body)

Campo	Tipo	Obrigatório	Descrição
subject	string	—	Título/assunto.
due_at	string	—	Data/hora prevista.
assigned_user_id	string	—	Usuário responsável.

cURLPHPPythonNode.jsC#HTTP / Postman

curl -X PATCH https://api.maestron.com.br/api/v1/crm/activities/{id} \
  -H "Authorization: Bearer SEU_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "subject": "Ligação de follow-up (reagendada)",
    "due_at": "2026-09-06T14:00:00Z"
  }'

<?php
$client = new \GuzzleHttp\Client();
$response = $client->request('PATCH', 'https://api.maestron.com.br/api/v1/crm/activities/{id}', [
    'headers' => [
        'Authorization' => 'Bearer SEU_TOKEN',
        'Accept' => 'application/json',
    ],
    'json' => [
        'subject' => 'Ligação de follow-up (reagendada)',
        'due_at' => '2026-09-06T14:00:00Z',
    ],
]);
$data = json_decode($response->getBody(), true);

import requests
headers = {"Authorization": "Bearer SEU_TOKEN"}
payload = {
    "subject": "Ligação de follow-up (reagendada)",
    "due_at": "2026-09-06T14:00:00Z",
}
response = requests.patch(
    "https://api.maestron.com.br/api/v1/crm/activities/{id}",
    headers=headers,
    json=payload,
)
data = response.json()

const response = await fetch("https://api.maestron.com.br/api/v1/crm/activities/{id}", {
  method: "PATCH",
  headers: {
    "Authorization": "Bearer SEU_TOKEN",
    "Content-Type": "application/json",
  },
  body: JSON.stringify({
    "subject": "Ligação de follow-up (reagendada)",
    "due_at": "2026-09-06T14:00:00Z"
  }),
});
const data = await response.json();

using var client = new HttpClient();
client.DefaultRequestHeaders.Authorization =
    new System.Net.Http.Headers.AuthenticationHeaderValue("Bearer", "SEU_TOKEN");
var payload = new StringContent(
    "{\"subject\":\"Ligação de follow-up (reagendada)\",\"due_at\":\"2026-09-06T14:00:00Z\"}",
    System.Text.Encoding.UTF8, "application/json");
var response = await client.SendAsync(new HttpRequestMessage(
    new HttpMethod("PATCH"), "https://api.maestron.com.br/api/v1/crm/activities/{id}") { Content = payload });
var data = await response.Content.ReadAsStringAsync();

PATCH /crm/activities/{id} HTTP/1.1
Host: api.maestron.com.br
Authorization: Bearer SEU_TOKEN
Content-Type: application/json

{
  "subject": "Ligação de follow-up (reagendada)",
  "due_at": "2026-09-06T14:00:00Z"
}

Respostas

200 · Atualizada401 · Não autenticado403 · Sem escopo404 · Não encontrado422 · Validação

{
  "message": "Atividade atualizada.",
  "data": {
    "id": "d4e5f6a7-8b9c-4d0e-1f2a-3b4c5d6e7f8a",
    "subject": "Ligação de follow-up (reagendada)"
  }
}

{
  "message": "Não autenticado.",
  "data": null
}

{
  "message": "A chave não tem o escopo necessário.",
  "data": null
}

{
  "message": "Recurso não encontrado.",
  "data": null
}

{
  "message": "Os dados informados são inválidos.",
  "data": null,
  "errors": {
    "due_at": [
      "O campo due_at deve ser uma data válida."
    ]
  }
}

Concluir atividade

POST /crm/activities/{id}/complete Copiar para LLM

Concluir atividade

Define done_at como agora. Sem idempotency_key nesta rota.

Parâmetros de caminho

Campo	Tipo	Obrigatório	Descrição
id	string	Sim	ID da atividade (UUID).

cURLPHPPythonNode.jsC#HTTP / Postman

curl -X POST https://api.maestron.com.br/api/v1/crm/activities/{id}/complete \
  -H "Authorization: Bearer SEU_TOKEN"

<?php
$client = new \GuzzleHttp\Client();
$response = $client->request('POST', 'https://api.maestron.com.br/api/v1/crm/activities/{id}/complete', [
    'headers' => [
        'Authorization' => 'Bearer SEU_TOKEN',
        'Accept' => 'application/json',
    ],
]);
$data = json_decode($response->getBody(), true);

import requests
headers = {"Authorization": "Bearer SEU_TOKEN"}
response = requests.post(
    "https://api.maestron.com.br/api/v1/crm/activities/{id}/complete",
    headers=headers,
)
data = response.json()

const response = await fetch("https://api.maestron.com.br/api/v1/crm/activities/{id}/complete", {
  method: "POST",
  headers: {
    "Authorization": "Bearer SEU_TOKEN",
  },
});
const data = await response.json();

using var client = new HttpClient();
client.DefaultRequestHeaders.Authorization =
    new System.Net.Http.Headers.AuthenticationHeaderValue("Bearer", "SEU_TOKEN");
var response = await client.PostAsync("https://api.maestron.com.br/api/v1/crm/activities/{id}/complete", null);
var data = await response.Content.ReadAsStringAsync();

POST /crm/activities/{id}/complete HTTP/1.1
Host: api.maestron.com.br
Authorization: Bearer SEU_TOKEN

Respostas

200 · Concluída401 · Não autenticado403 · Sem escopo404 · Não encontrado

{
  "message": "Atividade concluída.",
  "data": {
    "id": "d4e5f6a7-8b9c-4d0e-1f2a-3b4c5d6e7f8a",
    "done_at": "2026-09-05T14:45:00Z"
  }
}

{
  "message": "Não autenticado.",
  "data": null
}

{
  "message": "A chave não tem o escopo necessário.",
  "data": null
}

{
  "message": "Recurso não encontrado.",
  "data": null
}

Reabrir atividade

POST /crm/activities/{id}/reopen Copiar para LLM

Reabrir atividade

Define done_at como null. Sem idempotency_key nesta rota.

Parâmetros de caminho

Campo	Tipo	Obrigatório	Descrição
id	string	Sim	ID da atividade (UUID).

cURLPHPPythonNode.jsC#HTTP / Postman

curl -X POST https://api.maestron.com.br/api/v1/crm/activities/{id}/reopen \
  -H "Authorization: Bearer SEU_TOKEN"

<?php
$client = new \GuzzleHttp\Client();
$response = $client->request('POST', 'https://api.maestron.com.br/api/v1/crm/activities/{id}/reopen', [
    'headers' => [
        'Authorization' => 'Bearer SEU_TOKEN',
        'Accept' => 'application/json',
    ],
]);
$data = json_decode($response->getBody(), true);

import requests
headers = {"Authorization": "Bearer SEU_TOKEN"}
response = requests.post(
    "https://api.maestron.com.br/api/v1/crm/activities/{id}/reopen",
    headers=headers,
)
data = response.json()

const response = await fetch("https://api.maestron.com.br/api/v1/crm/activities/{id}/reopen", {
  method: "POST",
  headers: {
    "Authorization": "Bearer SEU_TOKEN",
  },
});
const data = await response.json();

using var client = new HttpClient();
client.DefaultRequestHeaders.Authorization =
    new System.Net.Http.Headers.AuthenticationHeaderValue("Bearer", "SEU_TOKEN");
var response = await client.PostAsync("https://api.maestron.com.br/api/v1/crm/activities/{id}/reopen", null);
var data = await response.Content.ReadAsStringAsync();

POST /crm/activities/{id}/reopen HTTP/1.1
Host: api.maestron.com.br
Authorization: Bearer SEU_TOKEN

Respostas

200 · Reaberta401 · Não autenticado403 · Sem escopo404 · Não encontrado

{
  "message": "Atividade reaberta.",
  "data": {
    "id": "d4e5f6a7-8b9c-4d0e-1f2a-3b4c5d6e7f8a",
    "done_at": null
  }
}

{
  "message": "Não autenticado.",
  "data": null
}

{
  "message": "A chave não tem o escopo necessário.",
  "data": null
}

{
  "message": "Recurso não encontrado.",
  "data": null
}

Remover atividade

DELETE /crm/activities/{id} Copiar para LLM

Remover atividade

Remove (soft delete) uma atividade.

Parâmetros de caminho

Campo	Tipo	Obrigatório	Descrição
id	string	Sim	ID da atividade (UUID).

cURLPHPPythonNode.jsC#HTTP / Postman

curl -X DELETE https://api.maestron.com.br/api/v1/crm/activities/{id} \
  -H "Authorization: Bearer SEU_TOKEN"

<?php
$client = new \GuzzleHttp\Client();
$response = $client->request('DELETE', 'https://api.maestron.com.br/api/v1/crm/activities/{id}', [
    'headers' => [
        'Authorization' => 'Bearer SEU_TOKEN',
        'Accept' => 'application/json',
    ],
]);
$data = json_decode($response->getBody(), true);

import requests
headers = {"Authorization": "Bearer SEU_TOKEN"}
response = requests.delete(
    "https://api.maestron.com.br/api/v1/crm/activities/{id}",
    headers=headers,
)
data = response.json()

const response = await fetch("https://api.maestron.com.br/api/v1/crm/activities/{id}", {
  method: "DELETE",
  headers: {
    "Authorization": "Bearer SEU_TOKEN",
  },
});
const data = await response.json();

using var client = new HttpClient();
client.DefaultRequestHeaders.Authorization =
    new System.Net.Http.Headers.AuthenticationHeaderValue("Bearer", "SEU_TOKEN");
var response = await client.DeleteAsync("https://api.maestron.com.br/api/v1/crm/activities/{id}");
var data = await response.Content.ReadAsStringAsync();

DELETE /crm/activities/{id} HTTP/1.1
Host: api.maestron.com.br
Authorization: Bearer SEU_TOKEN

Respostas

200 · Removida401 · Não autenticado403 · Sem escopo404 · Não encontrado

{
  "message": "Atividade removida.",
  "data": null
}

{
  "message": "Não autenticado.",
  "data": null
}

{
  "message": "A chave não tem o escopo necessário.",
  "data": null
}

{
  "message": "Recurso não encontrado.",
  "data": null
}

A descrição completa de cada código de status está em Erros.