Avaliações

As avaliações (scorecards) registram o parecer de cada membro do time sobre uma candidatura, geralmente após uma entrevista. Cada avaliação tem nota (rating) de 1 a 5, uma recomendação, critérios estruturados em um objeto livre e um comentário.

O autor da avaliação é sempre o usuário autenticado. A mesma combinação de usuário e entrevista comporta apenas um scorecard: reenviar uma avaliação com atsInterviewId já avaliado atualiza o registro existente (upsert). A edição e a exclusão são permitidas ao autor ou a usuários owner/admin.

Headers obrigatórios

Todas as requisições devem incluir o header X-Ats-Id (UUID) com o identificador da instância ATS, além de Authorization: Bearer {token} (guard atsUser).

---

Estrutura de Dados Principal

Uma avaliação contém as seguintes informações principais:

Campo	Tipo	Descrição
atsApplicationId	Number	ID da candidatura avaliada.
atsInterviewId	Number	ID da entrevista associada (opcional).
atsUserId	Number	ID do autor (sempre o usuário autenticado).
rating	Number	Nota de 1 a 5 (opcional).
recommendation	Enum	Recomendação: strong_no, no, neutral, yes ou strong_yes.
criteria	Object	Critérios de avaliação em formato livre (ex.: notas por competência).
comment	String	Comentário do avaliador.

---

Listar Avaliações de uma Candidatura

Lista as avaliações de uma candidatura, com paginação. O parâmetro atsApplicationId é obrigatório.

GET /v1/ats/user/evaluations

Parâmetros de Query

Nome	Tipo	Obrigatório	Descrição
atsApplicationId	number	Sim	ID da candidatura (deve existir na instância).
page	number	Não	O número da página (mínimo: 1).
perPage	number	Não	Itens por página (entre 1 e 100).

Exemplo de Requisição

curl -X GET "https://api.us.basis.tavares.in/v1/ats/user/evaluations?atsApplicationId=1&page=1&perPage=25" \
  -H "X-Ats-Id: 3fa85f64-5717-4562-b3fc-2c963f66afa6" \
  -H "Authorization: Bearer {token}" \
  -H "Accept: application/json"

Respostas

200 OK

Retorna um objeto de paginação contendo as avaliações da candidatura, com o autor (atsUser) e a entrevista associada (atsInterview).

{
  "meta": {
    "currentPage": 1,
    "perPage": 25
  },
  "data": [
    {
      "id": 1,
      "atsId": 1,
      "atsApplicationId": 1,
      "atsInterviewId": 1,
      "atsUserId": 1,
      "rating": 4,
      "recommendation": "yes",
      "criteria": {
        "comunicacao": 4,
        "fitCultural": 4,
        "conhecimentoTecnico": 5,
        "experienciaRelevante": 3
      },
      "comment": "Candidato com ótimo domínio técnico de Node.js e TypeScript. Comunicação clara e boa postura durante a entrevista. Recomendo avançar para a próxima etapa.",
      "createdAt": "2026-09-11T00:24:24.143-03:00",
      "updatedAt": "2026-09-11T00:24:24.143-03:00",
      "atsUser": {
        "id": 1,
        "firstName": "John",
        "lastName": "Doe (updated)"
      },
      "atsInterview": null
    }
  ]
}

404 Not Found

Ocorre quando a candidatura informada não existe na instância.

Criar Avaliação

Registra o scorecard do usuário autenticado para uma candidatura. Ao enviar atsInterviewId, a combinação usuário + entrevista é única: se já existir uma avaliação sua para aquela entrevista, ela é atualizada em vez de duplicada.

POST /v1/ats/user/evaluations

Payload (Body)

Atributo	Tipo	Obrigatório	Descrição
atsApplicationId	number	Sim	ID da candidatura (deve existir na instância).
atsInterviewId	number	Não	ID da entrevista associada (deve existir na instância). Ativa o comportamento de upsert por usuário/entrevista.
rating	number	Não	Nota de 1 a 5.
recommendation	enum	Sim	Recomendação: strong_no, no, neutral, yes ou strong_yes.
criteria	object	Não	Critérios de avaliação em formato livre (objeto JSON).
comment	string	Não	Comentário do avaliador.

Exemplo de Requisição

curl -X POST "https://api.us.basis.tavares.in/v1/ats/user/evaluations" \
  -H "X-Ats-Id: 3fa85f64-5717-4562-b3fc-2c963f66afa6" \
  -H "Authorization: Bearer {token}" \
  -H "Content-Type: application/json" \
  -d '{
    "atsApplicationId": 1,
    "atsInterviewId": 1,
    "rating": 4,
    "recommendation": "yes",
    "criteria": {
      "comunicacao": 4,
      "conhecimentoTecnico": 5,
      "fitCultural": 4,
      "experienciaRelevante": 3
    },
    "comment": "Candidato com ótimo domínio técnico de Node.js e TypeScript. Comunicação clara e boa postura durante a entrevista. Recomendo avançar para a próxima etapa."
  }'

Respostas

201 Created

Retorna o ID da avaliação criada (ou atualizada, no caso de upsert).

{
  "id": 1
}

403 Forbidden

Ocorre quando o usuário não tem papel de gestão ou interviewer na empresa da vaga.

{
  "message": "Você não tem permissão para realizar esta ação",
  "code": "FORBIDDEN"
}

Atualizar Avaliação

Atualiza uma avaliação existente. Permitido apenas ao autor da avaliação ou a usuários owner/admin.

PUT /v1/ats/user/evaluations/:id

Parâmetros de Rota

Nome	Tipo	Obrigatório	Descrição
id	number	Sim	O ID da avaliação.

Payload (Body)

Aceita os mesmos campos da criação, todos opcionais: rating, recommendation, criteria e comment.

Exemplo de Requisição

curl -X PUT "https://api.us.basis.tavares.in/v1/ats/user/evaluations/1" \
  -H "X-Ats-Id: 3fa85f64-5717-4562-b3fc-2c963f66afa6" \
  -H "Authorization: Bearer {token}" \
  -H "Content-Type: application/json" \
  -d '{
    "rating": 5,
    "recommendation": "strong_yes",
    "criteria": {
      "comunicacao": 5,
      "conhecimentoTecnico": 5,
      "fitCultural": 4,
      "experienciaRelevante": 4
    },
    "comment": "Após revisar a avaliação, subi a nota: o candidato demonstrou conhecimento sênior em arquitetura de APIs e boa liderança técnica. Recomendo fortemente a contratação."
  }'

Respostas

204 No Content

Atualização concluída com sucesso.

403 Forbidden

Ocorre quando o usuário não é o autor da avaliação nem owner/admin.

{
  "message": "Você não tem permissão para editar esta avaliação",
  "code": "FORBIDDEN"
}

404 Not Found

Ocorre quando a avaliação não existe na instância.

Remover Avaliação

Exclui uma avaliação da instância. Permitido apenas ao autor da avaliação ou a usuários owner/admin.

DELETE /v1/ats/user/evaluations/:id

Parâmetros de Rota

Nome	Tipo	Obrigatório	Descrição
id	number	Sim	O ID da avaliação.

Exemplo de Requisição

curl -X DELETE "https://api.us.basis.tavares.in/v1/ats/user/evaluations/1" \
  -H "X-Ats-Id: 3fa85f64-5717-4562-b3fc-2c963f66afa6" \
  -H "Authorization: Bearer {token}"

Respostas

204 No Content

Remoção concluída com sucesso.

403 Forbidden

Ocorre quando o usuário não é o autor da avaliação nem owner/admin.

{
  "message": "Você não tem permissão para excluir esta avaliação",
  "code": "FORBIDDEN"
}

404 Not Found

Ocorre quando a avaliação não existe na instância.