Activity Errors

Endpoints da WebApiAlcance para registrar e consultar erros de atividades - o registro estruturado das falhas ocorridas nas automações e rotinas da Alcance Contabilidade, usado para diagnóstico e auditoria. Cada erro guarda o usuário e a atividade envolvidos, data/hora, tipo de automação, título e um campo livre de detalhes (stack trace, mensagem etc.). Os endpoints cobrem criação, listagem geral, detalhamento por ID, listagem filtrada por atividade, atualização e exclusão.

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/activity_errors

Escopos necessários

activity_errors:read - listagem, detalhamento e listagem por atividade
activity_errors:write - criação, atualização e exclusão

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

Endpoints

`POST /activity_errors/`

Cria um novo erro de atividade. Todos os campos do corpo são opcionais e o campo detalhes é truncado defensivamente pelo servidor quando excede o limite da coluna.

Parâmetros

Este endpoint não recebe parâmetros de rota ou query - os dados vão no corpo da requisição (ActivityErrorCreate): usuario_id, atividade_id, data_hora, tipo_automacao, titulo e detalhes, todos opcionais.

Request

{
  "usuario_id": 1,
  "atividade_id": 1,
  "data_hora": "2023-01-01T12:00:00",
  "tipo_automacao": "Automação de Relatórios",
  "titulo": "Erro ao gerar relatório",
  "detalhes": "O sistema falhou ao gerar o relatório solicitado devido a um timeout."
}

Response 201 Created

{
  "success": true,
  "message": "Erro de atividade criado com sucesso",
  "data": {
    "id": 42,
    "usuario_id": 1,
    "atividade_id": 1,
    "data_hora": "2023-01-01T12:00:00",
    "tipo_automacao": "Automação de Relatórios",
    "titulo": "Erro ao gerar relatório",
    "detalhes": "O sistema falhou ao gerar o relatório solicitado devido a um timeout."
  }
}

Escopo: activity_errors:write

`GET /activity_errors/{error_id}`

Detalha um erro de atividade pelo ID inteiro. Quando não encontrado, retorna o envelope de erro com message: "Erro de atividade não encontrado.".

Parâmetros

Parâmetro	Tipo	Local	Obrigatório	Descrição
`error_id`	`int`	path	sim	ID interno do erro de atividade

Request

Sem corpo de requisição.

Response 200 OK

{
  "success": true,
  "message": "Erro de atividade encontrado com sucesso",
  "data": {
    "id": 42,
    "usuario_id": 1,
    "atividade_id": 1,
    "data_hora": "2023-01-01T12:00:00",
    "tipo_automacao": "Automação de Relatórios",
    "titulo": "Erro ao gerar relatório",
    "detalhes": "O sistema falhou ao gerar o relatório solicitado devido a um timeout."
  }
}

Escopo: activity_errors:read

`GET /activity_errors/`

Lista todos os erros de atividades registrados. Lista vazia é um estado válido - sempre retorna 200 OK, inclusive com data: [] e a mensagem "Nenhum erro de atividade encontrado.".

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 erros de atividades recuperada com sucesso",
  "data": [
    {
      "id": 42,
      "usuario_id": 1,
      "atividade_id": 1,
      "data_hora": "2023-01-01T12:00:00",
      "tipo_automacao": "Automação de Relatórios",
      "titulo": "Erro ao gerar relatório",
      "detalhes": "O sistema falhou ao gerar o relatório solicitado devido a um timeout."
    }
  ]
}

Escopo: activity_errors:read

`PUT /activity_errors/{error_id}`

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

Parâmetros

Parâmetro	Tipo	Local	Obrigatório	Descrição
`error_id`	`int`	path	sim	ID do erro de atividade

Request (ActivityErrorUpdate - todos os campos opcionais)

{
  "titulo": "Erro ao gerar relatório mensal",
  "detalhes": "Timeout ao consultar a base de dados de faturamento."
}

Response 200 OK

{
  "success": true,
  "message": "Erro de atividade atualizado com sucesso",
  "data": {
    "id": 42,
    "usuario_id": 1,
    "atividade_id": 1,
    "data_hora": "2023-01-01T12:00:00",
    "tipo_automacao": "Automação de Relatórios",
    "titulo": "Erro ao gerar relatório mensal",
    "detalhes": "Timeout ao consultar a base de dados de faturamento."
  }
}

Escopo: activity_errors:write

`DELETE /activity_errors/{error_id}`

Remove um erro de atividade pelo ID. Quando não encontrado, retorna o envelope de erro com message: "Erro de atividade não encontrado.".

Parâmetros

Parâmetro	Tipo	Local	Obrigatório	Descrição
`error_id`	`int`	path	sim	ID do erro de atividade

Request

Sem corpo de requisição.

Response 200 OK

{
  "success": true,
  "message": "Erro de atividade deletado com sucesso",
  "data": null
}

Escopo: activity_errors:write

`GET /activity_errors/activity/{activity_id}`

Lista todos os erros vinculados a uma atividade específica, pelo ID da atividade. Retorna data: [] quando não há erros para a atividade.

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": "Erros de atividade recuperados com sucesso",
  "data": [
    {
      "id": 42,
      "usuario_id": 1,
      "atividade_id": 1,
      "data_hora": "2023-01-01T12:00:00",
      "tipo_automacao": "Automação de Relatórios",
      "titulo": "Erro ao gerar relatório",
      "detalhes": "O sistema falhou ao gerar o relatório solicitado devido a um timeout."
    }
  ]
}

Escopo: activity_errors:read

Schemas

`ActivityErrorCreate`

Herda todos os campos de ActivityErrorBase. Todos são opcionais.

Campo	Tipo	Obrigatório	Observações
`usuario_id`	`int`	não	ID do usuário associado ao erro.
`atividade_id`	`int`	não	ID da atividade que gerou o erro.
`data_hora`	`datetime`	não	Momento do erro. Ex.: `2023-01-01T12:00:00`.
`tipo_automacao`	`str`	não	Categoria da automação. Ex.: `Automação de Relatórios`.
`titulo`	`str`	não	Título curto do erro. Ex.: `Erro ao gerar relatório`.
`detalhes`	`str`	não	Descrição livre (mensagem, stack trace). Truncado pelo servidor - ver Notas.

`ActivityErrorUpdate`

Todos os campos são opcionais; apenas os enviados são atualizados. Mesma estrutura de ActivityErrorCreate.

Campo	Tipo	Observações
`usuario_id`	`int`	Reatribui o erro a outro usuário.
`atividade_id`	`int`	Reatribui o erro a outra atividade.
`data_hora`	`datetime`	Novo momento do erro.
`tipo_automacao`	`str`	Nova categoria de automação.
`titulo`	`str`	Novo título.
`detalhes`	`str`	Novos detalhes. Truncado pelo servidor - ver Notas.

`ActivityErrorRead`

Estende ActivityErrorBase acrescentando o id.

Campo	Tipo	Notas
`id`	`int`	Identificador do erro de atividade.
`usuario_id`	`int`	Usuário associado ao erro.
`atividade_id`	`int`	Atividade que gerou o erro.
`data_hora`	`datetime`	Momento do erro.
`tipo_automacao`	`str`	Categoria da automação.
`titulo`	`str`	Título do erro.
`detalhes`	`str`	Descrição livre (mensagem, stack trace).

Notas

Toda resposta segue o envelope { success, message, data } (ou { success: false, message, details } em erro).
O campo detalhes é truncado defensivamente pelo servidor para caber na coluna TEXT do MySQL: acima de 60.000 caracteres, o conteúdo é cortado e recebe o sufixo ...[truncado pelo sistema], evitando o erro DataError 1406.
GET /activity_errors/activity/{activity_id} filtra por atividade, não pelo ID do próprio erro - não confundir activity_id com error_id.