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-atendimento

Escopos necessários

  • atividade_atendimento:read - listagem e consulta por ID (rotas GET).
  • 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âmetroTipoDefaultObservações
id_clienteint-Filtra por cliente.
setorstr (enum)-Um dos valores de setor em Valores permitidos. Valor fora da lista → 422.
id_usuarioint-Filtra pelo usuário que atendeu.
id_palavra_chaveint-Filtra por palavra-chave.
data_iniciodate (AAAA-MM-DD)-Início do período, sobre a data do atendimento.
data_fimdate (AAAA-MM-DD)-Fim do período, sobre a data do atendimento.
limitint (1-500)100Itens por página.
offsetint (≥ 0)0Deslocamento.

Request

GET /api/v1/atividade-atendimento/?id_cliente=123&data_inicio=2026-10-01&data_fim=2026-10-31&limit=50

Response 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âmetroTipoLocalObrigatórioDescrição
atividade_idintrotasimID da atividade de atendimento.

Request

GET /api/v1/atividade-atendimento/3051

Response 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âmetroTipoLocalObrigatórioDescrição
atividade_idintrotasimID 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âmetroTipoLocalObrigatórioDescrição
atividade_idintrotasimID da atividade de atendimento.

Request

DELETE /api/v1/atividade-atendimento/3051

Response 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

CampoValores
canalZapContábil, Ligação, Presencial, E-mail, WhatsApp Pessoal, Reunião Online
quem_iniciouAlcance, Cliente
setor e setor_transferenciaPessoal, Contábil, Fiscal, Sucesso do Cliente, Atendimento, Procuradoria, Diretoria Operações, Diretoria Geral, Desenvolvimento
servico_inclusoSim, Não, Não se aplica

Schemas

AtividadeAtendimentoCreate

CampoTipoObrigatórioObservações
canalstr (enum)simVer Valores permitidos.
data_atendimentodatesimAAAA-MM-DD.
quem_inicioustr (enum)simAlcance ou Cliente.
id_clienteintsimCliente atendido.
nome_clientestrsim1 a 200 caracteres.
setorstr (enum)simSetor que atendeu.
id_usuariointsimUsuário que atendeu.
mensagem_inicialstrsim1 a 5000 caracteres.
demandastrsim1 a 5000 caracteres.
id_palavra_chaveintsimVeja Palavras-chave de Atendimento.
servico_inclusostr (enum)simSim, Não ou Não se aplica.
resolvido_atendimentostr | nullnãoAté 5000 caracteres.
encaminhamentostr | nullnãoAté 100 caracteres.
setor_transferenciastr | nullnãoExige id_usuario_transferencia e prazo_retorno.
id_usuario_transferenciaint | nullnãoExige setor_transferencia e prazo_retorno.
prazo_retornodate | nullnãoExige setor_transferencia e id_usuario_transferencia.
orientacao_transferenciastr | nullnãoAté 5000 caracteres.
resolvido_setorstr | nullnãoAté 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:

CampoTipoObrigatórioObservações
idintsimID da atividade.
id_usuario_createdintsimUsuário autenticado que registrou.
data_hora_criacaodatetimesimData/hora do registro.
data_hora_atualizacaodatetimesimData/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_transferencia e id_palavra_chave precisam existir.