Palavras-chave de Atendimento

Endpoints da WebApiAlcance para o catálogo de palavras-chave de atendimento, usado para classificar cada atividade de atendimento. Cobrem criação, listagem em ordem alfabética, consulta por ID, atualização e remoção.

Todos os endpoints exigem autenticação. Veja Autenticação para o fluxo de API Key.

Base path

/api/v1/palavras-chave-atendimento

Escopos necessários

  • palavras_chave_atendimento:read - listagem e consulta por ID (rotas GET).
  • palavras_chave_atendimento:write - criação, atualização e remoção (POST, PUT, DELETE).

O escopo é derivado do prefixo público da rota: /palavras-chave-atendimento vira o recurso palavras_chave_atendimento (hífen → underscore), e o método HTTP define a ação (read para GET, write para POST/PUT/DELETE).

Criar, atualizar e remover são restritos a usuários com permissão adicional; sem ela, a resposta é 403.

Envelope de resposta

Toda resposta de sucesso segue o envelope padrão da WebApi:

{
  "status": "success",
  "message": "Mensagem em PT-BR",
  "data": {}
}

Erros de regra de negócio (404, 409, 422) vêm como { "message": ... }. Erros de validação do corpo ou da query vêm como 422 no formato { "detail": [...] }. Quando o registro não existe nas rotas de consulta, atualização e remoção por ID, a resposta é 200 OK com o envelope de erro { "status": "error", "message": "Palavra-chave não encontrada.", "details": null }.

Endpoints

POST /palavras-chave-atendimento/

Cria uma palavra-chave. Responde 201 Created.

Parâmetros

Sem parâmetros de rota ou query - os dados vão no corpo da requisição (ver PalavraChaveCreate).

Request

{
  "palavra": "Certidão negativa"
}

Response 201 Created

{
  "status": "success",
  "message": "Palavra-chave criada com sucesso",
  "data": {
    "id": 4,
    "palavra": "Certidão negativa",
    "data_hora_criacao": "2026-10-09T10:15:00",
    "data_hora_atualizacao": "2026-10-09T10:15:00"
  }
}

O data segue PalavraChaveRead. 409 se a palavra-chave já existir.

Escopo: palavras_chave_atendimento:write

Restrita a usuários com permissão adicional; sem ela, a resposta é 403.

GET /palavras-chave-atendimento/

Lista as palavras-chave em ordem alfabética, com paginação por limit/offset.

Parâmetros de query

ParâmetroTipoDefaultObservações
limitint (1-500)100Itens por página.
offsetint (≥ 0)0Deslocamento.

Request

GET /api/v1/palavras-chave-atendimento/?limit=100&offset=0

Response 200 OK

{
  "status": "success",
  "message": "Palavras-chave recuperadas com sucesso",
  "data": [
    {
      "id": 4,
      "palavra": "Certidão negativa",
      "data_hora_criacao": "2026-10-09T10:15:00",
      "data_hora_atualizacao": "2026-10-09T10:15:00"
    }
  ]
}

Sem resultados, data é [] e a message é "Nenhuma palavra-chave encontrada.". Os itens seguem PalavraChaveRead.

Escopo: palavras_chave_atendimento:read

GET /palavras-chave-atendimento/{palavra_id}

Retorna uma palavra-chave pelo ID.

Parâmetros

ParâmetroTipoLocalObrigatórioDescrição
palavra_idintrotasimID da palavra-chave.

Request

GET /api/v1/palavras-chave-atendimento/4

Response 200 OK

{
  "status": "success",
  "message": "Palavra-chave encontrada com sucesso",
  "data": {
    "id": 4,
    "palavra": "Certidão negativa",
    "data_hora_criacao": "2026-10-09T10:15:00",
    "data_hora_atualizacao": "2026-10-09T10:15:00"
  }
}

ID inexistente retorna 200 OK com o envelope de erro ("Palavra-chave não encontrada.").

Escopo: palavras_chave_atendimento:read

PUT /palavras-chave-atendimento/{palavra_id}

Atualiza o texto de uma palavra-chave.

Parâmetros

ParâmetroTipoLocalObrigatórioDescrição
palavra_idintrotasimID da palavra-chave.

O corpo segue PalavraChaveUpdate.

Request

{
  "palavra": "Certidão negativa de débitos"
}

Response 200 OK

{
  "status": "success",
  "message": "Palavra-chave atualizada com sucesso",
  "data": {
    "id": 4,
    "palavra": "Certidão negativa de débitos",
    "data_hora_criacao": "2026-10-09T10:15:00",
    "data_hora_atualizacao": "2026-10-20T09:00:00"
  }
}

409 se o novo texto já existir em outra palavra-chave. ID inexistente retorna 200 OK com o envelope de erro.

Escopo: palavras_chave_atendimento:write

Restrita a usuários com permissão adicional; sem ela, a resposta é 403.

DELETE /palavras-chave-atendimento/{palavra_id}

Remove uma palavra-chave.

Parâmetros

ParâmetroTipoLocalObrigatórioDescrição
palavra_idintrotasimID da palavra-chave.

Request

DELETE /api/v1/palavras-chave-atendimento/4

Response 200 OK

{
  "status": "success",
  "message": "Palavra-chave deletada com sucesso",
  "data": null
}

Palavra-chave em uso

Uma palavra-chave vinculada a alguma atividade de atendimento não pode ser removida: a resposta é 409 com a mensagem "Palavra-chave em uso por atividade de atendimento.". ID inexistente retorna 200 OK com o envelope de erro.

Escopo: palavras_chave_atendimento:write

Restrita a usuários com permissão adicional; sem ela, a resposta é 403.

Schemas

PalavraChaveCreate

CampoTipoObrigatórioObservações
palavrastrsim1 a 100 caracteres. Espaços nas pontas são removidos.

PalavraChaveUpdate

CampoTipoObrigatórioObservações
palavrastr | nullnão1 a 100 caracteres. Espaços nas pontas são removidos.

PalavraChaveRead

CampoTipoObrigatórioObservações
idintsimID da palavra-chave.
palavrastrsimTexto da palavra-chave.
data_hora_criacaodatetimesimData/hora da criação.
data_hora_atualizacaodatetimesimData/hora da última atualização.

Notas

  • Unicidade. Não existem duas palavras-chave iguais; criar ou renomear para um texto existente retorna 409.
  • Uso nas atividades. O id da palavra-chave é o id_palavra_chave informado ao registrar uma atividade de atendimento.