Módulo de ATS (Recrutamento)

O módulo de ATS (Applicant Tracking System) é uma solução completa de recrutamento headless. Ele permite que um workspace publique vagas em um job board e gerencie candidaturas em um funil (pipeline) de etapas — da inscrição à contratação.

Este módulo foi projetado para ser flexível e escalável, permitindo que cada workspace tenha sua própria instância do ATS com configurações, empresas, usuários e candidatos totalmente isolados.

Por que utilizar este módulo?

Antes de mergulharmos nos detalhes técnicos, é importante entender que este módulo não é apenas um job board. Ele foi construído com foco em:

Isolamento Total: Os dados são isolados por instância do ATS e, internamente, por empresa — um recrutador da Empresa A não enxerga dados da Empresa B (RBAC via vínculos de empresa).
Três Públicos, Três APIs: O dono da conta gerencia a instância, o time de recrutamento opera o funil e o candidato interage com o job board — cada um com sua própria autenticação.
Liberdade de Frontend: Sendo 100% headless, você consome o job board e o portal do candidato e decide como e onde exibi-los.

As Três Áreas do Módulo

O ATS possui três áreas independentes, cada uma com seu prefixo de rotas e seu contexto de autenticação:

Área	Prefixo das rotas	Público	Guard
Gestão da instância	`/user/ats`	Dono da conta (módulo `user`)	`user`
Staff (recrutadores)	`/v1/ats/user`	Recrutadores, hiring managers e entrevistadores	`atsUser`
Candidato	`/v1/ats/candidate`	Candidatos (job board e portal)	`atsCandidate`

A gestão da instância cria e configura as instâncias do ATS (domínios autorizados, storage, e-mail, localização) e segue a autenticação da plataforma.
A área de staff concentra a operação do recrutamento: empresas, departamentos, pipelines, vagas, candidatos, candidaturas, entrevistas, avaliações e métricas.
A área do candidato expõe o job board público (vagas abertas e detalhes) e o portal autenticado (candidaturas, perfil, currículos).

Autenticação e Contexto

Identificação da Instância

Todas as requisições para os endpoints /v1/ats/** (públicos ou privados) devem incluir o identificador da instância:

Header	Tipo	Obrigatório	Descrição
`X-Ats-Id`	`UUID`	Sim	O `tokenHeader` da instância, obtido no painel administrativo do workspace.

Como funciona o X-Ats-Id

O middleware resolve a instância pelo tokenHeader e valida se o domínio (ou IP) de origem está na lista de domínios autorizados do workspace, conforme a configuração allowBy (domain ou ip). Requisições sem o header, com instância inexistente ou com origem não autorizada recebem 401 Unauthorized. Instâncias inativas recebem 503 Service Unavailable.

bash

curl -X GET "https://api.us.basis.tavares.in/v1/ats/candidate/jobs/public" \
  -H "X-Ats-Id: 123e4567-e89b-12d3-a456-426614174000" \
  -H "Accept: application/json"

Tokens de Acesso

Staff e candidato possuem tokens e credenciais separados, obtidos em endpoints de login distintos:

Contexto	Endpoint de login	Credenciais
Staff	`POST /v1/ats/user/users/login`	`email` + `password`
Candidato	`POST /v1/ats/candidate/candidates/login` (ou `register`)	`email` + `password`

Ambos retornam um token Bearer com validade de 30 dias. O logout invalida o token imediatamente.

Para endpoints protegidos, forneça o token do contexto correspondente:

Header	Valor	Descrição
`Authorization`	`Bearer <token>`	Token obtido no login do staff ou do candidato.

Tokens não são intercambiáveis

Um token de staff não acessa endpoints de candidato e vice-versa. Cada contexto possui seu próprio endpoint de login e sua própria base de credenciais.

Resumo dos Headers

http

GET /v1/ats/user/jobs
X-Ats-Id: 123e4567-e89b-12d3-a456-426614174000
Authorization: Bearer {token}
Accept: application/json

Controle de Acesso (RBAC)

O vínculo entre usuário staff e empresa define o papel (role) do usuário naquela empresa:

Role	Escopo
`owner` / `admin`	Acesso total a todas as empresas da instância, incluindo configurações (empresas, pipelines, usuários e motivos de recusa).
`recruiter` / `hiring_manager`	Gerenciam vagas, candidaturas, departamentos e conteúdo das empresas vinculadas.
`interviewer`	Leitura das empresas vinculadas + criar e gerenciar entrevistas e avaliações.
`viewer`	Somente leitura, nas empresas vinculadas.

Regras adicionais:

Listagens de recursos ligados a empresa (vagas, candidaturas, entrevistas, métricas) são filtradas pelas empresas do usuário; owner/admin veem tudo.
Não é permitido remover ou rebaixar o único owner de uma empresa — a tentativa falha com 422 LAST_OWNER.
Notas, avaliações e edições sensíveis só podem ser alteradas pelo autor ou por owner/admin.

Billing e Limites de Plano

Todas as rotas do módulo (públicas e privadas) passam por limite de plano e contabilização de uso. Quando o plano não permite a operação, a API responde 402 Payment Required com um dos seguintes códigos:

Code	Significado
`PENDING_INVOICES`	Existem faturas pendentes no workspace.
`PLAN_REQUIRED`	O workspace não possui um plano ativo para o módulo.
`USAGE_LIMIT_EXCEEDED`	O limite de uso do plano foi atingido.

Convenções da API

Os endpoints /v1/ats/** seguem convenções consistentes em todas as áreas:

Paginação: parâmetros page/perPage (máx. 100) com resposta no formato { "meta": { "currentPage", "perPage" }, "data": [...] }.
Listas para dropdown: endpoints GET .../list retornam [{ "value", "label" }], com search opcional — ideais para selects e filtros no frontend.
Ordenação: orderBy (campos permitidos por recurso) + orderDirection (asc/desc).
Soft delete: registros removidos não aparecem em nenhuma consulta.
Erros de validação: 422 Unprocessable Entity com errors: [{ "message", "rule", "field" }] (mensagens em pt/en via i18n).
Datas: sempre em ISO 8601; filtros de período usam YYYY-MM-DD.
IDs: tratados como números, sem assumir tamanho (algumas tabelas usam inteiros, outras bigint).
Rate limit: 3000 req/min para o módulo (global); as rotas de gestão da instância (/user/ats) seguem o throttle do módulo user (100 req/min).
Busca full-text: vagas e candidatos usam o idioma simple — buscas não diferenciam acentos.

Códigos de Erro de Negócio

Erros de regra de negócio retornam status 4xx com um code identificador no corpo da resposta:

Code	Status	Significado
`FORBIDDEN`	403	Papel sem permissão para a ação/empresa.
`LAST_OWNER`	422	Remover ou rebaixar o único owner da empresa.
`APPLIED_STAGE_EXISTS`	422	Já existe etapa `applied` no pipeline.
`INVALID_STAGE_IDS`	422	Reorder com lista incompleta ou inválida de etapas.
`APPLIED_STAGE_LOCKED`	422	Tentativa de remover a etapa `applied`.
`STAGE_IN_USE`	422	Etapa com candidaturas vinculadas.
`JOB_NOT_FOUND`	422	Vaga inexistente.
`JOB_NOT_OPEN`	422	Vaga não está `open`.
`JOB_CLOSED`	422	Prazo de inscrição encerrado.
`ALREADY_APPLIED`	422	Candidato já inscrito na vaga.
`APPLICATION_NOT_FOUND`	404	Candidatura inexistente (ou de outro candidato).
`APPLICATION_CLOSED`	422	Candidatura encerrada (`hired`/`withdrawn`).
`STAGE_PIPELINE_MISMATCH`	422	Etapa não pertence ao pipeline da candidatura.
`INVALID_STAGE_MOVE`	422	Pulo de etapas em pipeline sequencial.
`INVALID_PERIOD`	422	Entrevista com `endsAt` anterior ou igual a `startsAt`.

Próximos Passos

Agora que você entende a base do módulo, explore as funcionalidades detalhadas:

Módulo de ATS (Recrutamento) ​

Por que utilizar este módulo? ​

As Três Áreas do Módulo ​

Autenticação e Contexto ​

Identificação da Instância ​

Tokens de Acesso ​

Resumo dos Headers ​

Controle de Acesso (RBAC) ​

Billing e Limites de Plano ​

Convenções da API ​

Códigos de Erro de Negócio ​

Próximos Passos ​