Atividades de Atendimento
Endpoints da WebApiAlcance para o registro das atividades de atendimento prestadas aos clientes: canal, quem iniciou, setor, demanda, palavra-chave, resolução e, quando houver, a transferência para outro setor. Cobrem criação, listagem com filtros, 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/atividade-atendimentoEscopos necessários
atividade_atendimento:read- listagem e consulta por ID (rotasGET).atividade_atendimento:write- criação, atualização e remoção (POST,PUT,DELETE).
O escopo é derivado do prefixo público da rota: /atividade-atendimento vira o recurso atividade_atendimento (hífen → underscore), e o método HTTP define a ação (read para GET, write para POST/PUT/DELETE).
A remoção é restrita 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": "Atividade de atendimento não encontrada.", "details": null }.
Endpoints
POST /atividade-atendimento/
Registra uma atividade de atendimento. O autor do registro (id_usuario_created) é o usuário autenticado. Responde 201 Created.
Parâmetros
Sem parâmetros de rota ou query - os dados vão no corpo da requisição (ver AtividadeAtendimentoCreate).
Transferência: tudo ou nada
Os campos setor_transferencia, id_usuario_transferencia e prazo_retorno devem vir juntos ou nenhum deles. Setor sem usuário e prazo, ou usuário/prazo sem setor, retorna 422.
Request
{
"canal": "ZapContábil",
"data_atendimento": "2026-10-09",
"quem_iniciou": "Cliente",
"id_cliente": 123,
"nome_cliente": "Empresa Exemplo Ltda",
"setor": "Fiscal",
"id_usuario": 7,
"mensagem_inicial": "Cliente pediu a certidão.",
"demanda": "Emissão de certidão negativa.",
"id_palavra_chave": 4,
"servico_incluso": "Sim",
"resolvido_atendimento": "Certidão enviada.",
"setor_transferencia": "Contábil",
"id_usuario_transferencia": 12,
"prazo_retorno": "2026-10-16",
"orientacao_transferencia": "Retornar ao cliente."
}Response 201 Created
{
"status": "success",
"message": "Atividade de atendimento registrada com sucesso",
"data": {
"id": 3051,
"canal": "ZapContábil",
"data_atendimento": "2026-10-09",
"quem_iniciou": "Cliente",
"id_cliente": 123,
"nome_cliente": "Empresa Exemplo Ltda",
"setor": "Fiscal",
"id_usuario": 7,
"mensagem_inicial": "Cliente pediu a certidão.",
"demanda": "Emissão de certidão negativa.",
"id_palavra_chave": 4,
"servico_incluso": "Sim",
"resolvido_atendimento": "Certidão enviada.",
"encaminhamento": null,
"setor_transferencia": "Contábil",
"id_usuario_transferencia": 12,
"prazo_retorno": "2026-10-16",
"orientacao_transferencia": "Retornar ao cliente.",
"resolvido_setor": null,
"id_usuario_created": 7,
"data_hora_criacao": "2026-10-09T10:15:00",
"data_hora_atualizacao": "2026-10-09T10:15:00"
}
}O data segue AtividadeAtendimentoRead.
Erros
422 (transferência incompleta, valor fora dos permitidos ou texto acima do tamanho máximo) e 404 quando o cliente, o usuário ou a palavra-chave informados não existem.
Escopo: atividade_atendimento:write
GET /atividade-atendimento/
Lista as atividades de atendimento, da mais recente para a mais antiga, com filtros opcionais e paginação por limit/offset.
Parâmetros de query
| Parâmetro | Tipo | Default | Observações |
|---|---|---|---|
id_cliente | int | - | Filtra por cliente. |
setor | str (enum) | - | Um dos valores de setor em Valores permitidos. Valor fora da lista → 422. |
id_usuario | int | - | Filtra pelo usuário que atendeu. |
id_palavra_chave | int | - | Filtra por palavra-chave. |
data_inicio | date (AAAA-MM-DD) | - | Início do período, sobre a data do atendimento. |
data_fim | date (AAAA-MM-DD) | - | Fim do período, sobre a data do atendimento. |
limit | int (1-500) | 100 | Itens por página. |
offset | int (≥ 0) | 0 | Deslocamento. |
Request
GET /api/v1/atividade-atendimento/?id_cliente=123&data_inicio=2026-10-01&data_fim=2026-10-31&limit=50Response 200 OK
{
"status": "success",
"message": "Atividades de atendimento recuperadas com sucesso",
"data": [
{
"id": 3051,
"canal": "ZapContábil",
"data_atendimento": "2026-10-09",
"quem_iniciou": "Cliente",
"id_cliente": 123,
"nome_cliente": "Empresa Exemplo Ltda",
"setor": "Fiscal",
"id_usuario": 7,
"mensagem_inicial": "Cliente pediu a certidão.",
"demanda": "Emissão de certidão negativa.",
"id_palavra_chave": 4,
"servico_incluso": "Sim",
"resolvido_atendimento": "Certidão enviada.",
"encaminhamento": null,
"setor_transferencia": null,
"id_usuario_transferencia": null,
"prazo_retorno": null,
"orientacao_transferencia": null,
"resolvido_setor": null,
"id_usuario_created": 7,
"data_hora_criacao": "2026-10-09T10:15:00",
"data_hora_atualizacao": "2026-10-09T10:15:00"
}
]
}Sem resultados, data é [] e a message é "Nenhuma atividade de atendimento encontrada.". Os itens seguem AtividadeAtendimentoRead.
Escopo: atividade_atendimento:read
GET /atividade-atendimento/{atividade_id}
Retorna uma atividade de atendimento pelo ID.
Parâmetros
| Parâmetro | Tipo | Local | Obrigatório | Descrição |
|---|---|---|---|---|
atividade_id | int | rota | sim | ID da atividade de atendimento. |
Request
GET /api/v1/atividade-atendimento/3051Response 200 OK
{
"status": "success",
"message": "Atividade de atendimento encontrada",
"data": {}
}O data segue AtividadeAtendimentoRead. ID inexistente retorna 200 OK com o envelope de erro ("Atividade de atendimento não encontrada.").
Escopo: atividade_atendimento:read
PUT /atividade-atendimento/{atividade_id}
Atualiza uma atividade de atendimento. Todos os campos são opcionais; só os enviados são alterados.
Parâmetros
| Parâmetro | Tipo | Local | Obrigatório | Descrição |
|---|---|---|---|---|
atividade_id | int | rota | sim | ID da atividade de atendimento. |
O corpo segue AtividadeAtendimentoUpdate.
Transferência validada sobre o estado final
A regra "tudo ou nada" da transferência é aplicada ao resultado da atualização: o valor enviado vence e, para o que não foi enviado, vale o que já está gravado. Deixar a transferência pela metade retorna 422.
Request
{
"resolvido_atendimento": "Certidão enviada ao cliente.",
"resolvido_setor": "Retorno realizado."
}Response 200 OK
{
"status": "success",
"message": "Atividade de atendimento atualizada com sucesso",
"data": {}
}O data segue AtividadeAtendimentoRead. 404 quando uma referência informada (cliente, usuário ou palavra-chave) não existe; ID inexistente retorna 200 OK com o envelope de erro.
Escopo: atividade_atendimento:write
DELETE /atividade-atendimento/{atividade_id}
Remove uma atividade de atendimento. A remoção apaga o histórico de atendimento ao cliente e por isso é restrita.
Parâmetros
| Parâmetro | Tipo | Local | Obrigatório | Descrição |
|---|---|---|---|---|
atividade_id | int | rota | sim | ID da atividade de atendimento. |
Request
DELETE /api/v1/atividade-atendimento/3051Response 200 OK
{
"status": "success",
"message": "Atividade de atendimento deletada com sucesso",
"data": null
}ID inexistente retorna 200 OK com o envelope de erro ("Atividade de atendimento não encontrada.").
Escopo: atividade_atendimento:write
Restrita a usuários com permissão adicional; sem ela, a resposta é 403.
Valores permitidos
| Campo | Valores |
|---|---|
canal | ZapContábil, Ligação, Presencial, E-mail, WhatsApp Pessoal, Reunião Online |
quem_iniciou | Alcance, Cliente |
setor e setor_transferencia | Pessoal, Contábil, Fiscal, Sucesso do Cliente, Atendimento, Procuradoria, Diretoria Operações, Diretoria Geral, Desenvolvimento |
servico_incluso | Sim, Não, Não se aplica |
Schemas
AtividadeAtendimentoCreate
| Campo | Tipo | Obrigatório | Observações |
|---|---|---|---|
canal | str (enum) | sim | Ver Valores permitidos. |
data_atendimento | date | sim | AAAA-MM-DD. |
quem_iniciou | str (enum) | sim | Alcance ou Cliente. |
id_cliente | int | sim | Cliente atendido. |
nome_cliente | str | sim | 1 a 200 caracteres. |
setor | str (enum) | sim | Setor que atendeu. |
id_usuario | int | sim | Usuário que atendeu. |
mensagem_inicial | str | sim | 1 a 5000 caracteres. |
demanda | str | sim | 1 a 5000 caracteres. |
id_palavra_chave | int | sim | Veja Palavras-chave de Atendimento. |
servico_incluso | str (enum) | sim | Sim, Não ou Não se aplica. |
resolvido_atendimento | str | null | não | Até 5000 caracteres. |
encaminhamento | str | null | não | Até 100 caracteres. |
setor_transferencia | str | null | não | Exige id_usuario_transferencia e prazo_retorno. |
id_usuario_transferencia | int | null | não | Exige setor_transferencia e prazo_retorno. |
prazo_retorno | date | null | não | Exige setor_transferencia e id_usuario_transferencia. |
orientacao_transferencia | str | null | não | Até 5000 caracteres. |
resolvido_setor | str | null | não | Até 5000 caracteres. |
Espaços nas pontas dos textos são removidos.
AtividadeAtendimentoUpdate
Mesmos campos de AtividadeAtendimentoCreate, todos opcionais, com as mesmas restrições de valor e tamanho.
AtividadeAtendimentoRead
Contém todos os campos de AtividadeAtendimentoCreate e mais:
| Campo | Tipo | Obrigatório | Observações |
|---|---|---|---|
id | int | sim | ID da atividade. |
id_usuario_created | int | sim | Usuário autenticado que registrou. |
data_hora_criacao | datetime | sim | Data/hora do registro. |
data_hora_atualizacao | datetime | sim | Data/hora da última atualização. |
Notas
- Autor do registro.
id_usuario_createdé sempre o usuário autenticado;id_usuarioé quem realizou o atendimento e é informado no corpo. - Ordenação. A listagem vem da data de atendimento mais recente para a mais antiga.
- Referências.
id_cliente,id_usuario,id_usuario_transferenciaeid_palavra_chaveprecisam existir.