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-atendimentoEscopos necessários
palavras_chave_atendimento:read- listagem e consulta por ID (rotasGET).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âmetro | Tipo | Default | Observações |
|---|---|---|---|
limit | int (1-500) | 100 | Itens por página. |
offset | int (≥ 0) | 0 | Deslocamento. |
Request
GET /api/v1/palavras-chave-atendimento/?limit=100&offset=0Response 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âmetro | Tipo | Local | Obrigatório | Descrição |
|---|---|---|---|---|
palavra_id | int | rota | sim | ID da palavra-chave. |
Request
GET /api/v1/palavras-chave-atendimento/4Response 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âmetro | Tipo | Local | Obrigatório | Descrição |
|---|---|---|---|---|
palavra_id | int | rota | sim | ID 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âmetro | Tipo | Local | Obrigatório | Descrição |
|---|---|---|---|---|
palavra_id | int | rota | sim | ID da palavra-chave. |
Request
DELETE /api/v1/palavras-chave-atendimento/4Response 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
| Campo | Tipo | Obrigatório | Observações |
|---|---|---|---|
palavra | str | sim | 1 a 100 caracteres. Espaços nas pontas são removidos. |
PalavraChaveUpdate
| Campo | Tipo | Obrigatório | Observações |
|---|---|---|---|
palavra | str | null | não | 1 a 100 caracteres. Espaços nas pontas são removidos. |
PalavraChaveRead
| Campo | Tipo | Obrigatório | Observações |
|---|---|---|---|
id | int | sim | ID da palavra-chave. |
palavra | str | sim | Texto da palavra-chave. |
data_hora_criacao | datetime | sim | Data/hora da criação. |
data_hora_atualizacao | datetime | sim | Data/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
idda palavra-chave é oid_palavra_chaveinformado ao registrar uma atividade de atendimento.