Activities

Endpoints da WebApiAlcance para o registro de atividades - o log operacional das tarefas executadas pela equipe, vinculadas a um cliente e a um usuário responsável. Cobrem criação, listagem geral, detalhamento por ID, atualização, exclusão, listagem das atividades de um usuário (com filtros opcionais) e estatísticas por usuário.

Todos os endpoints exigem autenticação. Veja Autenticação para o fluxo de API Key. O Swagger oficial está em api.contabilidadealcance.com.br/docs.

Base path

/api/v1/activities

Escopos necessários

activities:read - listagem, detalhamento, atividades por usuário e estatísticas
activities:write - criação, atualização e exclusão

O escopo é derivado da rota: o prefixo /activities vira o recurso activities, e o método HTTP define a ação (read para GET, write para POST/PUT/DELETE).

Endpoints

`POST /activities/`

Cria uma nova atividade no sistema. Todos os campos do corpo são opcionais - o mais comum é enviar cliente_id, usuario_id, tipo, titulo, data_inicio e status.

Parâmetros

Este endpoint não recebe parâmetros de rota ou query - os dados vão no corpo da requisição (ActivityCreate): cliente_id, usuario_id, data_inicio, data_fim, tipo, titulo, descricao e status, todos opcionais.

Request

{
  "cliente_id": 1234,
  "usuario_id": 7,
  "data_inicio": "2026-07-03T09:00:00",
  "data_fim": null,
  "tipo": "apuracao",
  "titulo": "Apuração de impostos - julho/2026",
  "descricao": "Fechamento mensal",
  "status": "em_andamento"
}

Response 201 Created

{
  "success": true,
  "message": "Atividade criada com sucesso",
  "data": {
    "id": 512,
    "cliente_id": 1234,
    "usuario_id": 7,
    "data_inicio": "2026-07-03T09:00:00",
    "data_fim": null,
    "tipo": "apuracao",
    "titulo": "Apuração de impostos - julho/2026",
    "descricao": "Fechamento mensal",
    "status": "em_andamento"
  }
}

Escopo: activities:write

`GET /activities/{activity_id}`

Detalha uma atividade pelo ID inteiro. Quando não encontrada, retorna o envelope de erro com message: "Atividade não encontrada.".

Parâmetros

Parâmetro	Tipo	Local	Obrigatório	Descrição
`activity_id`	`int`	path	sim	ID interno da atividade

Request

Sem corpo de requisição.

Response 200 OK

{
  "success": true,
  "message": "Atividade encontrada com sucesso",
  "data": {
    "id": 512,
    "cliente_id": 1234,
    "usuario_id": 7,
    "data_inicio": "2026-07-03T09:00:00",
    "data_fim": null,
    "tipo": "apuracao",
    "titulo": "Apuração de impostos - julho/2026",
    "descricao": "Fechamento mensal",
    "status": "em_andamento"
  }
}

Escopo: activities:read

`GET /activities/`

Lista todas as atividades cadastradas. Lista vazia é um estado válido - retorna 200 OK com data: [] e a mensagem "Nenhuma atividade encontrada.".

Parâmetros

Este endpoint não recebe parâmetros de rota ou query.

Request

Sem corpo de requisição.

Response 200 OK

{
  "success": true,
  "message": "Lista de atividades recuperada com sucesso",
  "data": [
    { "id": 1, "cliente_id": 1234, "usuario_id": 7, "titulo": "...", "status": "concluida" },
    { "id": 2, "cliente_id": 88, "usuario_id": 3, "titulo": "...", "status": "em_andamento" }
  ]
}

Escopo: activities:read

`PUT /activities/{activity_id}`

Atualiza uma atividade existente. O corpo é um ActivityUpdate com campos parciais - somente o que vier preenchido é alterado. Quando não encontrada, retorna o envelope de erro com message: "Atividade não encontrada.".

Parâmetros

Parâmetro	Tipo	Local	Obrigatório	Descrição
`activity_id`	`int`	path	sim	ID da atividade

Request (ActivityUpdate - todos os campos opcionais)

{
  "status": "concluida",
  "data_fim": "2026-07-05T17:30:00"
}

Response 200 OK

{
  "success": true,
  "message": "Atividade atualizada com sucesso",
  "data": {
    "id": 512,
    "cliente_id": 1234,
    "usuario_id": 7,
    "data_inicio": "2026-07-03T09:00:00",
    "data_fim": "2026-07-05T17:30:00",
    "tipo": "apuracao",
    "titulo": "Apuração de impostos - julho/2026",
    "descricao": "Fechamento mensal",
    "status": "concluida"
  }
}

Escopo: activities:write

`DELETE /activities/{activity_id}`

Remove uma atividade pelo ID. Quando não encontrada, retorna o envelope de erro com message: "Atividade não encontrada.".

Parâmetros

Parâmetro	Tipo	Local	Obrigatório	Descrição
`activity_id`	`int`	path	sim	ID da atividade

Request

Sem corpo de requisição.

Response 200 OK

{
  "success": true,
  "message": "Atividade deletada com sucesso",
  "data": null
}

Escopo: activities:write

`GET /activities/activities/user/{user_id}`

Retorna as atividades de um usuário, com suporte a filtros opcionais por período, cliente, status e tipo de automação. Lista vazia retorna 200 OK com data: [] e a mensagem "Nenhuma atividade encontrada.".

O caminho tem activities duplicado: o prefixo do módulo é /api/v1/activities e esta rota é declarada com o caminho /activities/user/{user_id}, resultando em /api/v1/activities/activities/user/{user_id}. Use o caminho exatamente como mostrado.

Parâmetros

Parâmetro	Tipo	Local	Obrigatório	Descrição
`user_id`	`int`	path	sim	ID do usuário
`ano`	`int`	query	não	Filtra pelo ano
`mes`	`int`	query	não	Filtra pelo mês
`cliente_id`	`int`	query	não	Filtra por cliente
`status`	`str`	query	não	Filtra pelo status da atividade
`tipo_automacao`	`str`	query	não	Filtra pelo tipo de automação

Request

Sem corpo de requisição. Exemplo com filtros: GET /api/v1/activities/activities/user/7?ano=2026&mes=7&cliente_id=1234&status=concluida.

Response 200 OK

{
  "success": true,
  "message": "Atividades recuperadas com sucesso",
  "data": [
    {
      "id": 512,
      "cliente_id": 1234,
      "usuario_id": 7,
      "data_inicio": "2026-07-03T09:00:00",
      "data_fim": "2026-07-05T17:30:00",
      "tipo": "apuracao",
      "titulo": "Apuração de impostos - julho/2026",
      "descricao": "Fechamento mensal",
      "status": "concluida"
    }
  ]
}

Escopo: activities:read

`GET /activities/stats/user/{user_id}`

Retorna as estatísticas das atividades de um usuário (agregações do log operacional). Sem dados, retorna 200 OK com data: [] e a mensagem "Nenhuma atividade encontrada.".

Parâmetros

Parâmetro	Tipo	Local	Obrigatório	Descrição
`user_id`	`int`	path	sim	ID do usuário

Request

Sem corpo de requisição.

Response 200 OK

{
  "success": true,
  "message": "Atividades recuperadas com sucesso",
  "data": {
    "total": 42,
    "concluidas": 30,
    "em_andamento": 12
  }
}

Escopo: activities:read

Schemas

`ActivityCreate`

Todos os campos são opcionais.

Campo	Tipo	Obrigatório	Observações
`cliente_id`	`int`	não	Cliente vinculado à atividade.
`usuario_id`	`int`	não	Usuário responsável pela atividade.
`data_inicio`	`datetime`	não	Início da atividade (ISO 8601).
`data_fim`	`datetime`	não	Término da atividade (ISO 8601).
`tipo`	`str`	não	Tipo/categoria da atividade.
`titulo`	`str`	não	Título curto da atividade.
`descricao`	`str`	não	Descrição detalhada.
`status`	`str`	não	Situação da atividade (ex.: `em_andamento`, `concluida`).

`ActivityUpdate`

Todos os campos são opcionais; apenas os enviados são atualizados. Mesmos campos do ActivityCreate:

Campo	Tipo	Observações
`cliente_id`	`int`	Reassocia a atividade a outro cliente.
`usuario_id`	`int`	Reatribui a atividade a outro usuário.
`data_inicio`	`datetime`	Novo início.
`data_fim`	`datetime`	Novo término.
`tipo`	`str`	Novo tipo.
`titulo`	`str`	Novo título.
`descricao`	`str`	Nova descrição.
`status`	`str`	Nova situação.

`ActivityRead`

Estende os campos do ActivityBase (mesmos do ActivityCreate) e acrescenta o id.

Campo	Tipo	Notas
`id`	`int`	Identificador da atividade.
`cliente_id`	`int`	Cliente vinculado.
`usuario_id`	`int`	Usuário responsável.
`data_inicio`	`datetime`	Início da atividade.
`data_fim`	`datetime`	Término da atividade.
`tipo`	`str`	Tipo/categoria.
`titulo`	`str`	Título.
`descricao`	`str`	Descrição.
`status`	`str`	Situação.

Notas

Toda resposta segue o envelope { success, message, data } (ou { success: false, message, details } em erro).
A rota estática GET /activities/stats/user/{user_id} e a rota GET /activities/activities/user/{user_id} convivem com a rota dinâmica GET /activities/{activity_id}. Como stats e activities são prefixos distintos de {activity_id} (que é int), não há conflito de roteamento.
As atividades relacionam-se a Customers via cliente_id - ao excluir um cliente, as atividades vinculadas são removidas em cascata.