Motivos de Recusa

Os motivos de recusa formam o catálogo padronizado da instância para registrar por que uma candidatura foi rejeitada. Ao rejeitar uma candidatura (PATCH /v1/ats/user/applications/:id/reject), a equipe informa um motivo deste catálogo, o que mantém os dados consistentes e alimenta o gráfico de motivos de recusa nas métricas do funil.

Cada motivo pode ser ativado ou desativado: motivos inativos deixam de aparecer na lista simples usada nos formulários, mas permanecem no histórico das candidaturas já rejeitadas.

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} com o token do usuário do ATS (guard atsUser).

---

Estrutura de Dados Principal

Um motivo de recusa contém as seguintes informações principais:

Campo	Tipo	Descrição
id	Number	Identificador do motivo.
name	String	Nome do motivo (máx. 150 caracteres).
isActive	Boolean	Indica se o motivo está ativo (padrão: true).
createdAt	String	Data de criação (ISO 8601).
updatedAt	String	Data da última atualização (ISO 8601).

---

Endpoints de Consulta

Endpoints de leitura, disponíveis para qualquer usuário autenticado da instância.

Listar Motivos de Recusa

Lista os motivos de recusa da instância, com paginação, busca por nome e filtro por status.

GET /v1/ats/user/rejection-reasons

Parâmetros de Query

Nome	Tipo	Obrigatório	Descrição
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, padrão: 25).
search	string	Não	Busca por termo no nome (máx. 150 caracteres).
isActive	boolean	Não	Filtra por motivos ativos (true) ou inativos (false).

Exemplo de Requisição

curl -X GET "https://api.us.basis.tavares.in/v1/ats/user/rejection-reasons?page=1&perPage=25&isActive=true" \
  -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 a lista de motivos.

{
  "meta": {
    "currentPage": 1,
    "perPage": 25
  },
  "data": [
    {
      "id": 1,
      "atsId": 1,
      "name": "Salário fora do orçamento",
      "isActive": true,
      "createdAt": "2026-09-11T03:14:02.654+00:00",
      "updatedAt": "2026-09-11T03:14:02.654+00:00"
    }
  ]
}

Listar Motivos de Recusa (Lista Simples)

Retorna somente os motivos ativos, em formato simplificado (value/label), ideal para o select exibido ao rejeitar uma candidatura.

GET /v1/ats/user/rejection-reasons/list

Parâmetros de Query

Nome	Tipo	Obrigatório	Descrição
search	string	Não	Filtra por prefixo do nome (máx. 150 caracteres).

Exemplo de Requisição

curl -X GET "https://api.us.basis.tavares.in/v1/ats/user/rejection-reasons/list?search=Sal" \
  -H "X-Ats-Id: 3fa85f64-5717-4562-b3fc-2c963f66afa6" \
  -H "Authorization: Bearer {token}" \
  -H "Accept: application/json"

Respostas

200 OK

Retorna um array com os motivos ativos em formato value/label.

[
  {
    "value": 1,
    "label": "Salário fora do orçamento"
  }
]

Obter Motivo de Recusa por ID

Recupera os detalhes de um motivo de recusa da instância.

GET /v1/ats/user/rejection-reasons/:id

Parâmetros de Rota

Nome	Tipo	Obrigatório	Descrição
id	number	Sim	O ID do motivo de recusa.

Exemplo de Requisição

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

Respostas

200 OK

Retorna os dados do motivo de recusa.

{
  "id": 1,
  "atsId": 1,
  "name": "Salário fora do orçamento",
  "isActive": true,
  "createdAt": "2026-09-11T03:14:02.654+00:00",
  "updatedAt": "2026-09-11T03:14:02.654+00:00"
}

404 Not Found

Ocorre quando o motivo de recusa não existe na instância.

---

Endpoints de Gerenciamento

Endpoints de escrita do catálogo, restritos a usuários owner/admin da instância — demais roles recebem 403 Forbidden.

Criar Novo Motivo de Recusa

Cria um novo motivo de recusa na instância.

POST /v1/ats/user/rejection-reasons

Payload (Body)

Atributo	Tipo	Obrigatório	Descrição
name	string	Sim	Nome do motivo (máx. 150 caracteres).
isActive	boolean	Não	Indica se o motivo está ativo (padrão: true).

Exemplo de Requisição

curl -X POST "https://api.us.basis.tavares.in/v1/ats/user/rejection-reasons" \
  -H "X-Ats-Id: 3fa85f64-5717-4562-b3fc-2c963f66afa6" \
  -H "Authorization: Bearer {token}" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "Salário fora do orçamento",
    "isActive": true
  }'

Respostas

201 Created

Retorna o ID do motivo de recusa criado.

{
  "id": 1
}

403 Forbidden

O usuário autenticado não é owner/admin da instância.

422 Unprocessable Entity

Erro de validação nos campos enviados.

{
  "errors": [
    {
      "message": "Nome é obrigatório",
      "rule": "required",
      "field": "name"
    }
  ]
}

Atualizar Motivo de Recusa

Atualiza o nome ou o status de um motivo de recusa existente. Desativar um motivo (isActive: false) o remove da lista simples sem afetar o histórico das candidaturas.

PUT /v1/ats/user/rejection-reasons/:id

Parâmetros de Rota

Nome	Tipo	Obrigatório	Descrição
id	number	Sim	O ID do motivo de recusa.

Payload (Body)

Atributo	Tipo	Obrigatório	Descrição
name	string	Sim	Nome do motivo (máx. 150 caracteres).
isActive	boolean	Não	Indica se o motivo está ativo.

Exemplo de Requisição

curl -X PUT "https://api.us.basis.tavares.in/v1/ats/user/rejection-reasons/1" \
  -H "X-Ats-Id: 3fa85f64-5717-4562-b3fc-2c963f66afa6" \
  -H "Authorization: Bearer {token}" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "Salário fora do orçamento",
    "isActive": true
  }'

Respostas

204 No Content

Atualização concluída com sucesso.

404 Not Found

Ocorre quando o motivo de recusa não existe na instância.

422 Unprocessable Entity

Erro de validação nos campos enviados.

Remover Motivo de Recusa

Remove um motivo de recusa da instância (exclusão lógica).

DELETE /v1/ats/user/rejection-reasons/:id

Parâmetros de Rota

Nome	Tipo	Obrigatório	Descrição
id	number	Sim	O ID do motivo de recusa.

Exemplo de Requisição

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

Respostas

204 No Content

Remoção concluída com sucesso.

404 Not Found

Ocorre quando o motivo de recusa não existe na instância.