Atividades

O recurso Atividade registra interações e compromissos do CRM: ligações, reuniões, e-mails, tarefas e notas. Cada atividade pertence a uma empresa (tenant), resolvida automaticamente a partir do token — ver Autenticação.

Identificadores de atividade usam o prefixo act_ (ex.: act_01J9Z3K8).

Esquema do recurso

Campo	Tipo	Obrigatório	Descrição
`id`	string	leitura	Identificador prefixado (`act_`).
`type`	string	sim	Tipo da atividade. Um de `call`, `meeting`, `email`, `task`, `note`.
`title`	string	sim	Título da atividade. Entre 2 e 150 caracteres.
`description`	string	não	Descrição livre. Máx. 5000 caracteres.
`related_to`	object	não	Vínculo polimórfico com o registro de origem. Contém `type` e `id`.
`due_at`	string (ISO-8601)	não	Data/hora prevista.
`completed_at`	string (ISO-8601)	leitura	Data/hora de conclusão. `null` enquanto não concluída.
`is_completed`	boolean	leitura	Indica se a atividade foi concluída.
`assigned_to`	string	não	Usuário (`user_`) responsável. Deve pertencer à mesma empresa (tenant).
`created_at`	string (ISO-8601)	leitura	Data de criação.
`updated_at`	string (ISO-8601)	leitura	Data da última atualização.

Tipos de atividade

Valor	Descrição
`call`	Ligação telefônica.
`meeting`	Reunião presencial ou online.
`email`	Mensagem de e-mail.
`task`	Tarefa a ser executada.
`note`	Anotação ou observação.

Vínculo polimórfico (`related_to`)

O campo related_to associa a atividade a um único registro de origem. É enviado como objeto com type e id:

`related_to.type`	`related_to.id`	Aponta para
`contact`	`cont_...`	um contato.
`company`	`comp_...`	uma empresa do CRM.
`deal`	`deal_...`	um negócio.

Listar atividades

Retorna uma coleção paginada de atividades da empresa. Aceita os parâmetros padrão de paginação, busca e ordenação (ver Convenções). A busca (search) percorre title e description.

GET /crm/activities

Listar atividades

Retorna a lista paginada de atividades da empresa resolvida pelo token.

Parâmetros de query

Campo	Tipo	Obrigatório	Descrição
`page`	integer	—	Página atual (padrão: 1).
`per_page`	integer	—	Itens por página (padrão: 20, máx: 100).
`search`	string	—	Busca textual em title e description.
`sort`	string	—	Campo de ordenação (ex.: due_at, created_at).
`direction`	string	—	Direção da ordenação: asc ou desc.
`type`	string	—	Filtra por tipo: call, meeting, email, task ou note.
`related_type`	string	—	Filtra pelo tipo do vínculo: contact, company ou deal.
`related_id`	string	—	Filtra pelo id do registro vinculado.
`assigned_to`	string	—	Filtra pelo usuário responsável (user_).
`is_completed`	boolean	—	Filtra por atividades concluídas (true) ou pendentes (false).
`due_from`	date	—	Filtra por data prevista (início).
`due_to`	date	—	Filtra por data prevista (fim).
`created_from`	date	—	Filtra por data de criação (início).
`created_to`	date	—	Filtra por data de criação (fim).

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

<?php
$client = new \GuzzleHttp\Client();
$response = $client->request('GET', 'https://api.maestron.com.br/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/v1/crm/activities",
    headers=headers,
)
data = response.json()

const response = await fetch("https://api.maestron.com.br/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/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

{
  "message": "Atividades listadas.",
  "data": [
    {
      "id": "act_01J9Z3K8",
      "type": "call",
      "title": "Ligação de qualificação",
      "description": "Confirmar interesse e orçamento.",
      "related_to": {
        "type": "contact",
        "id": "cont_01J9Z3K8"
      },
      "due_at": "2026-06-22T14:30:00Z",
      "completed_at": null,
      "is_completed": false,
      "assigned_to": "user_01J9Z3K8",
      "created_at": "2026-06-20T10:00:00Z",
      "updated_at": "2026-06-20T10:00:00Z"
    },
    {
      "id": "act_01J9Z3K9",
      "type": "meeting",
      "title": "Reunião de proposta",
      "description": null,
      "related_to": {
        "type": "deal",
        "id": "deal_01J9Z3K8"
      },
      "due_at": "2026-06-25T16:00:00Z",
      "completed_at": "2026-06-25T17:05:00Z",
      "is_completed": true,
      "assigned_to": "user_01J9Z3K8",
      "created_at": "2026-06-19T09:00:00Z",
      "updated_at": "2026-06-25T17:05:00Z"
    }
  ],
  "meta": {
    "current_page": 1,
    "per_page": 20,
    "total": 2,
    "last_page": 1
  }
}

{
  "message": "Não autenticado."
}

Obter uma atividade

GET /crm/activities/{id}

Obter atividade

Retorna uma atividade específica pelo identificador.

Parâmetros de caminho

Campo	Tipo	Obrigatório	Descrição
`id`	string	Sim	Identificador da atividade (act_).

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

<?php
$client = new \GuzzleHttp\Client();
$response = $client->request('GET', 'https://api.maestron.com.br/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/v1/crm/activities/{id}",
    headers=headers,
)
data = response.json()

const response = await fetch("https://api.maestron.com.br/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/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

{
  "message": "Atividade retornada.",
  "data": {
    "id": "act_01J9Z3K8",
    "type": "call",
    "title": "Ligação de qualificação",
    "description": "Confirmar interesse e orçamento.",
    "related_to": {
      "type": "contact",
      "id": "cont_01J9Z3K8"
    },
    "due_at": "2026-06-22T14:30:00Z",
    "completed_at": null,
    "is_completed": false,
    "assigned_to": "user_01J9Z3K8",
    "created_at": "2026-06-20T10:00:00Z",
    "updated_at": "2026-06-20T10:00:00Z"
  }
}

{
  "message": "Não autenticado."
}

{
  "message": "Atividade não encontrada."
}

Criar uma atividade

Cria uma nova atividade, opcionalmente vinculada a um contato, empresa ou negócio via related_to.

POST /crm/activities

Criar atividade

Cria uma nova atividade vinculada opcionalmente a um contato, empresa ou negócio.

Corpo (body)

Campo	Tipo	Obrigatório	Descrição
`type`	string	Sim	Tipo da atividade: call, meeting, email, task ou note.
`title`	string	Sim	Título da atividade. Entre 2 e 150 caracteres.
`description`	string	—	Descrição livre. Máx. 5000 caracteres.
`related_to`	object	—	Vínculo polimórfico com type (contact, company ou deal) e id correspondente.
`due_at`	string	—	Data/hora prevista (ISO-8601).
`assigned_to`	string	—	Usuário responsável (user_).

curl -X POST https://api.maestron.com.br/v1/crm/activities \
  -H "Authorization: Bearer SEU_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "type": "call",
    "title": "Ligação de qualificação",
    "description": "Confirmar interesse e orçamento.",
    "related_to": {
      "type": "contact",
      "id": "cont_01J9Z3K8"
    },
    "due_at": "2026-06-22T14:30:00Z",
    "assigned_to": "user_01J9Z3K8"
  }'

<?php
$client = new \GuzzleHttp\Client();
$response = $client->request('POST', 'https://api.maestron.com.br/v1/crm/activities', [
    'headers' => [
        'Authorization' => 'Bearer SEU_TOKEN',
        'Accept' => 'application/json',
    ],
    'json' => [
        'type' => 'call',
        'title' => 'Ligação de qualificação',
        'description' => 'Confirmar interesse e orçamento.',
        'related_to' => [object Object],
        'due_at' => '2026-06-22T14:30:00Z',
        'assigned_to' => 'user_01J9Z3K8',
    ],
]);
$data = json_decode($response->getBody(), true);

import requests
headers = {"Authorization": "Bearer SEU_TOKEN"}
payload = {
    "type": "call",
    "title": "Ligação de qualificação",
    "description": "Confirmar interesse e orçamento.",
    "related_to": [object Object],
    "due_at": "2026-06-22T14:30:00Z",
    "assigned_to": "user_01J9Z3K8",
}
response = requests.post(
    "https://api.maestron.com.br/v1/crm/activities",
    headers=headers,
    json=payload,
)
data = response.json()

const response = await fetch("https://api.maestron.com.br/v1/crm/activities", {
  method: "POST",
  headers: {
    "Authorization": "Bearer SEU_TOKEN",
    "Content-Type": "application/json",
  },
  body: JSON.stringify({
    "type": "call",
    "title": "Ligação de qualificação",
    "description": "Confirmar interesse e orçamento.",
    "related_to": {
      "type": "contact",
      "id": "cont_01J9Z3K8"
    },
    "due_at": "2026-06-22T14:30:00Z",
    "assigned_to": "user_01J9Z3K8"
  }),
});
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(
    "{\"type\":\"call\",\"title\":\"Ligação de qualificação\",\"description\":\"Confirmar interesse e orçamento.\",\"related_to\":{\"type\":\"contact\",\"id\":\"cont_01J9Z3K8\"},\"due_at\":\"2026-06-22T14:30:00Z\",\"assigned_to\":\"user_01J9Z3K8\"}",
    System.Text.Encoding.UTF8, "application/json");
var response = await client.PostAsync("https://api.maestron.com.br/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

{
  "type": "call",
  "title": "Ligação de qualificação",
  "description": "Confirmar interesse e orçamento.",
  "related_to": {
    "type": "contact",
    "id": "cont_01J9Z3K8"
  },
  "due_at": "2026-06-22T14:30:00Z",
  "assigned_to": "user_01J9Z3K8"
}

Respostas

{
  "message": "Atividade criada.",
  "data": {
    "id": "act_01J9Z3K8",
    "type": "call",
    "title": "Ligação de qualificação",
    "description": "Confirmar interesse e orçamento.",
    "related_to": {
      "type": "contact",
      "id": "cont_01J9Z3K8"
    },
    "due_at": "2026-06-22T14:30:00Z",
    "completed_at": null,
    "is_completed": false,
    "assigned_to": "user_01J9Z3K8",
    "created_at": "2026-06-20T10:00:00Z",
    "updated_at": "2026-06-20T10:00:00Z"
  }
}

{
  "message": "Não autenticado."
}

{
  "message": "Registro vinculado não encontrado."
}

{
  "message": "Os dados informados são inválidos.",
  "errors": {
    "type": [
      "O campo type é obrigatório."
    ],
    "title": [
      "O campo title é obrigatório."
    ],
    "related_to.id": [
      "O id informado não corresponde ao type do vínculo."
    ]
  }
}

Atualizar uma atividade

Atualiza parcialmente uma atividade. Apenas os campos enviados são alterados.

PATCH /crm/activities/{id}

Atualizar atividade

Atualiza parcialmente uma atividade. Apenas os campos enviados são alterados.

Parâmetros de caminho

Campo	Tipo	Obrigatório	Descrição
`id`	string	Sim	Identificador da atividade (act_).

Corpo (body)

Campo	Tipo	Obrigatório	Descrição
`type`	string	—	Tipo da atividade: call, meeting, email, task ou note.
`title`	string	—	Título da atividade. Entre 2 e 150 caracteres.
`description`	string	—	Descrição livre. Máx. 5000 caracteres.
`related_to`	object	—	Vínculo polimórfico com type (contact, company ou deal) e id correspondente.
`due_at`	string	—	Data/hora prevista (ISO-8601).
`assigned_to`	string	—	Usuário responsável (user_).

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

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

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

const response = await fetch("https://api.maestron.com.br/v1/crm/activities/{id}", {
  method: "PATCH",
  headers: {
    "Authorization": "Bearer SEU_TOKEN",
    "Content-Type": "application/json",
  },
  body: JSON.stringify({
    "title": "Ligação de qualificação (reagendada)",
    "due_at": "2026-06-23T15: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(
    "{\"title\":\"Ligação de qualificação (reagendada)\",\"due_at\":\"2026-06-23T15:00:00Z\"}",
    System.Text.Encoding.UTF8, "application/json");
var response = await client.SendAsync(new HttpRequestMessage(
    new HttpMethod("PATCH"), "https://api.maestron.com.br/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

{
  "title": "Ligação de qualificação (reagendada)",
  "due_at": "2026-06-23T15:00:00Z"
}

Respostas

{
  "message": "Atividade atualizada.",
  "data": {
    "id": "act_01J9Z3K8",
    "type": "call",
    "title": "Ligação de qualificação (reagendada)",
    "description": "Confirmar interesse e orçamento.",
    "related_to": {
      "type": "contact",
      "id": "cont_01J9Z3K8"
    },
    "due_at": "2026-06-23T15:00:00Z",
    "completed_at": null,
    "is_completed": false,
    "assigned_to": "user_01J9Z3K8",
    "created_at": "2026-06-20T10:00:00Z",
    "updated_at": "2026-06-20T11:30:00Z"
  }
}

{
  "message": "Não autenticado."
}

{
  "message": "Atividade não encontrada."
}

{
  "message": "Os dados informados são inválidos.",
  "errors": {
    "type": [
      "O type selecionado é inválido."
    ]
  }
}

Concluir uma atividade

Marca a atividade como concluída, definindo completed_at e is_completed. A operação é idempotente: concluir uma atividade já concluída mantém o completed_at original.

POST /crm/activities/{id}/complete

Concluir atividade

Marca a atividade como concluída.

Parâmetros de caminho

Campo	Tipo	Obrigatório	Descrição
`id`	string	Sim	Identificador da atividade (act_).

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

<?php
$client = new \GuzzleHttp\Client();
$response = $client->request('POST', 'https://api.maestron.com.br/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/v1/crm/activities/{id}/complete",
    headers=headers,
)
data = response.json()

const response = await fetch("https://api.maestron.com.br/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/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

{
  "message": "Atividade concluída.",
  "data": {
    "id": "act_01J9Z3K8",
    "type": "call",
    "title": "Ligação de qualificação",
    "description": "Confirmar interesse e orçamento.",
    "related_to": {
      "type": "contact",
      "id": "cont_01J9Z3K8"
    },
    "due_at": "2026-06-22T14:30:00Z",
    "completed_at": "2026-06-22T14:45:00Z",
    "is_completed": true,
    "assigned_to": "user_01J9Z3K8",
    "created_at": "2026-06-20T10:00:00Z",
    "updated_at": "2026-06-22T14:45:00Z"
  }
}

{
  "message": "Não autenticado."
}

{
  "message": "Atividade não encontrada."
}

Remover uma atividade

DELETE /crm/activities/{id}

Remover atividade

Remove permanentemente uma atividade.

Parâmetros de caminho

Campo	Tipo	Obrigatório	Descrição
`id`	string	Sim	Identificador da atividade (act_).

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

<?php
$client = new \GuzzleHttp\Client();
$response = $client->request('DELETE', 'https://api.maestron.com.br/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/v1/crm/activities/{id}",
    headers=headers,
)
data = response.json()

const response = await fetch("https://api.maestron.com.br/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/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

{
  "message": "Atividade removida."
}

{
  "message": "Não autenticado."
}

{
  "message": "Atividade não encontrada."
}

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

Atividades

Esquema do recurso

Tipos de atividade

Vínculo polimórfico (related_to)

Listar atividades

Obter uma atividade

Criar uma atividade

Atualizar uma atividade

Concluir uma atividade

Remover uma atividade

Vínculo polimórfico (`related_to`)