Atividades
Registre e acompanhe atividades e interações pela API.
Atividades
Atividades formam o histórico operacional de interações, tarefas e eventos vinculados a clientes, oportunidades ou contratos.
Tipos de atividade
Os valores aceitos para type são: call, meeting, email, note, task, hearing, deadline, follow_up, case_event, contract_event e system.
Use deal_id como o identificador técnico da oportunidade vinculada.
GET /activities
Lista as atividades do time autenticado.
Parâmetros de consulta
| Parâmetro | Tipo | Padrão | Descrição |
|---|---|---|---|
page | number | 1 | Página atual. |
limit | number | 20 | Itens por página, de 1 a 100. |
type | string | — | Filtra por um dos tipos aceitos. Valores fora da lista não aplicam filtro. |
client_id | string | — | UUID do cliente. |
deal_id | string | — | UUID técnico da oportunidade. |
completed | string | — | true para concluídas ou false para não concluídas. Outros valores não aplicam filtro. |
search | string | — | Busca por título ou descrição. |
sort | string | -created_at | title, type, occurred_at, due_date, priority ou created_at. Use - para ordem decrescente. |
Quando sort é omitido, a API usa -created_at. Para um campo fora da lista, ela usa created_at e preserva a direção informada: invalido fica ascendente e -invalido, descendente.
Exemplo
curl "https://app.usecolmeia.com/api/v1/activities?type=follow_up&completed=false" \
-H "Authorization: Bearer ea_live_sua_chave_aqui"Resposta
{
"success": true,
"data": [
{
"id": "33333333-3333-4333-8333-333333333333",
"type": "follow_up",
"title": "Retornar contato sobre a proposta",
"description": "Confirmar dúvidas da equipe financeira.",
"occurred_at": "2026-08-05T14:00:00.000Z",
"duration_minutes": null,
"is_completed": false,
"due_date": "2026-08-08",
"priority": "high",
"tags": ["proposta"],
"client_id": "44444444-4444-4444-8444-444444444444",
"deal_id": "55555555-5555-4555-8555-555555555555",
"contract_id": null,
"assigned_to": null,
"created_by": null,
"created_at": "2026-08-05T14:00:00.000Z",
"updated_at": "2026-08-05T14:00:00.000Z"
}
],
"pagination": {
"page": 1,
"limit": 20,
"total": 1,
"pages": 1
}
}POST /activities
Cria uma atividade. title é removido dos espaços nas extremidades antes de ser salvo.
| Campo | Tipo | Obrigatório | Descrição |
|---|---|---|---|
title | string | Sim | Título da atividade. |
type | string | Não | Um dos tipos aceitos. O padrão é task. |
description | string | Não | Descrição; quando omitida, a API envia null. |
occurred_at | string | Não | Data e hora ISO 8601. O padrão é o momento da criação. |
duration_minutes | number | Não | Duração em minutos. No POST, 0 é convertido para null. |
is_completed | boolean | Não | Define se a atividade inicia concluída; o padrão é false. |
due_date | string | Não | Data civil em YYYY-MM-DD. |
priority | string | Não | low, medium ou high. |
tags | array | Não | Tags da atividade. O padrão é []. |
client_id | string | Não | UUID do cliente. |
deal_id | string | Não | UUID técnico da oportunidade. |
contract_id | string | Não | UUID do contrato. |
assigned_to | string | Não | UUID da pessoa responsável. |
created_by | string | Não | UUID de quem criou o registro. |
Exemplo
curl -X POST "https://app.usecolmeia.com/api/v1/activities" \
-H "Authorization: Bearer ea_live_sua_chave_aqui" \
-H "Content-Type: application/json" \
-d '{
"title": "Retornar contato sobre a proposta",
"type": "follow_up",
"client_id": "44444444-4444-4444-8444-444444444444",
"deal_id": "55555555-5555-4555-8555-555555555555"
}'Em caso de sucesso, retorna 201 e o objeto de atividade no envelope { "success": true, "data": ... }, com os campos exibidos na resposta de listagem.
GET /activities/:id
Busca uma atividade pelo UUID. A resposta de sucesso é o objeto de atividade mapeado, com todos os campos da resposta de listagem.
curl "https://app.usecolmeia.com/api/v1/activities/33333333-3333-4333-8333-333333333333" \
-H "Authorization: Bearer ea_live_sua_chave_aqui"PUT /activities/:id
Atualiza parcialmente uma atividade. Envie ao menos um dos campos aceitos; um corpo sem campos aceitos retorna 400 VALIDATION_ERROR.
| Campo atualizável | Valores ou formato |
|---|---|
title e description | string ou null para description |
type | um dos tipos aceitos |
occurred_at | data e hora ISO 8601 |
duration_minutes | number |
is_completed | boolean |
due_date | data civil em YYYY-MM-DD ou null |
priority | low, medium, high ou null |
tags | array |
client_id, deal_id, contract_id, assigned_to | UUID ou null |
created_by é aceito somente na criação e não pode ser atualizado por esta rota.
curl -X PUT "https://app.usecolmeia.com/api/v1/activities/33333333-3333-4333-8333-333333333333" \
-H "Authorization: Bearer ea_live_sua_chave_aqui" \
-H "Content-Type: application/json" \
-d '{ "is_completed": true }'A resposta é 200 com o objeto de atividade mapeado.
DELETE /activities/:id
Conclui logicamente a atividade; ela não é excluída fisicamente. A operação define is_completed como true e retorna updated_at como completed_at.
curl -X DELETE "https://app.usecolmeia.com/api/v1/activities/33333333-3333-4333-8333-333333333333" \
-H "Authorization: Bearer ea_live_sua_chave_aqui"{
"success": true,
"data": {
"id": "33333333-3333-4333-8333-333333333333",
"is_completed": true,
"completed_at": "2026-08-05T15:00:00.000Z"
}
}Erros
Todas as rotas retornam 401 UNAUTHORIZED quando a chave de API não é válida. GET, PUT e DELETE por um UUID inexistente retornam 404 NOT_FOUND. Criação e atualização retornam 400 VALIDATION_ERROR para JSON inválido, título ausente, tipo inválido ou ausência de campos atualizáveis. Falhas internas do armazenamento retornam 500 INTERNAL_ERROR.