🚀 Admitah API

API REST para integração com o sistema Admitah

Versão 1.0 | Documentação Completa

🔐 Autenticação

⚠️ A API usa autenticação JWT (Bearer Token)

Para acessar os endpoints da API, você precisa:

  1. Obter seu ClientId e ClientSecret com o administrador do sistema
  2. Fazer uma requisição POST para /api/auth/token com suas credenciais
  3. Receber um token JWT (válido por 60 minutos)
  4. Incluir o token no header Authorization: Bearer {token} em todas as requisições

Importante: O token expira após 60 minutos. Quando expirar, você deve solicitar um novo token.

POST Obter Token de Acesso

/api/auth/token
Autentica com ClientId e ClientSecret e retorna um token JWT Bearer.

Exemplo de Request Body:

{
  "clientId": "client_a1b2c3d4e5f6g7h8",
  "clientSecret": "AbCdEfGhIjKlMnOpQrStUvWxYz123456"
}

Exemplo de Resposta (200 OK):

{
  "sucesso": true,
  "mensagem": "Token gerado com sucesso",
  "dados": {
    "accessToken": "eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9...",
    "tokenType": "Bearer",
    "expiresIn": 3600,
    "expiresAt": "2025-12-16T11:30:00Z"
  }
}

Como usar o token nas requisições:

Inclua o header Authorization com o prefixo Bearer seguido do token:

{
  "Authorization": "Bearer eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9...",
  "Content-Type": "application/json"
}

Exemplo completo com cURL:

# 1. Obter token
curl -X POST https://seudominio.com/api/auth/token \
  -H "Content-Type: application/json" \
  -d '{
    "clientId": "client_a1b2c3d4e5f6g7h8",
    "clientSecret": "AbCdEfGhIjKlMnOpQrStUvWxYz123456"
  }'

# 2. Usar token para acessar API
curl -X GET https://seudominio.com/api/candidatos \
  -H "Authorization: Bearer eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9..." \
  -H "Content-Type: application/json"

👥 Candidatos

GET Listar Candidatos

/api/candidatos?status=Aprovado&dataInicio=2025-01-01&dataFim=2025-12-31&incluirCampos=true
Lista todos os candidatos do cliente autenticado com filtros opcionais.
Parâmetro Tipo Obrigatório Descrição
status string Opcional Filtrar por status: LinkEnviado, EmPreenchimento, Enviado, Aprovado, Reprovado
dataInicio date Opcional Data de admissão início (formato: yyyy-MM-dd)
dataFim date Opcional Data de admissão fim (formato: yyyy-MM-dd)
incluirCampos boolean Opcional Incluir campos personalizados e administrativos. Default: true

Exemplo de Resposta (200 OK):

{
  "sucesso": true,
  "mensagem": "Operação realizada com sucesso",
  "dados": [
    {
      "id": 123,
      "clienteId": 1,
      "nomeCompleto": "João Silva Santos",
      "cpf": "12345678900",
      "email": "joao.silva@example.com",
      "cargoId": 5,
      "cargo": "Analista de Sistemas",
      "status": "Aprovado",
      "dataCriacao": "2025-01-15T10:30:00",
      "camposAdministrativos": [
        {
          "campoId": 10,
          "nomeCampo": "Matrícula",
          "valor": "2025001"
        },
        {
          "campoId": 11,
          "nomeCampo": "Centro de Custo",
          "valor": "TI-001"
        }
      ],
      "camposPersonalizados": [
        {
          "respostaId": 100,
          "campoId": 20,
          "nomeCampo": "Tamanho da Camisa",
          "valorTexto": "M",
          "nomeArquivo": null,
          "urlDownload": null,
          "dataResposta": "2025-01-15T14:20:00"
        },
        {
          "respostaId": 101,
          "campoId": 21,
          "nomeCampo": "Certificado de Curso",
          "valorTexto": null,
          "nomeArquivo": "certificado_curso.pdf",
          "urlDownload": "/api/candidatos/123/campos-personalizados/101/download",
          "dataResposta": "2025-01-15T14:25:00"
        }
      ],
      "documentos": [
        {
          "id": 50,
          "candidatoId": 123,
          "tipoDocumento": "RG",
          "nomeArquivo": "rg_frente.jpg",
          "tipoConteudo": "image/jpeg",
          "tamanhoArquivo": 245760,
          "dataUpload": "2025-01-15T14:30:00",
          "urlDownload": "/api/candidatos/123/documentos/50"
        },
        {
          "id": 51,
          "candidatoId": 123,
          "tipoDocumento": "CPF",
          "nomeArquivo": "cpf.pdf",
          "tipoConteudo": "application/pdf",
          "tamanhoArquivo": 102400,
          "dataUpload": "2025-01-15T14:35:00",
          "urlDownload": "/api/candidatos/123/documentos/51"
        }
      ]
    }
  ]
}

POST Criar Candidato

/api/candidatos
Cria um novo candidato para o cliente autenticado e envia email com link de preenchimento.

Exemplo de Request Body:

{
  "email": "maria.oliveira@example.com",
  "cargoId": 5,
  "telefone": "(11) 98765-4321",
  "celular": "(11) 99876-5432"
}
Campo Tipo Obrigatório Descrição
email string Obrigatório Email do candidato (único no sistema)
cargoId integer Opcional ID do cargo para o qual está sendo contratado
telefone string Opcional Telefone fixo do candidato
celular string Opcional Celular do candidato

Exemplo de Resposta (200 OK):

{
  "sucesso": true,
  "mensagem": "Candidato criado com sucesso",
  "dados": {
    "id": 124,
    "clienteId": 1,
    "nomeCompleto": null,
    "cpf": null,
    "email": "maria.oliveira@example.com",
    "cargoId": 5,
    "cargo": "Analista de Sistemas",
    "status": "LinkEnviado",
    "dataCriacao": "2025-12-16T10:00:00",
    "camposAdministrativos": [],
    "camposPersonalizados": [],
    "documentos": []
  }
}

GET Listar Documentos de um Candidato

/api/candidatos/{candidatoId}/documentos
Lista todos os documentos anexados a um candidato específico.

Exemplo de Resposta (200 OK):

{
  "sucesso": true,
  "mensagem": "Operação realizada com sucesso",
  "dados": [
    {
      "id": 50,
      "candidatoId": 123,
      "tipoDocumento": "RG",
      "nomeArquivo": "rg_frente.jpg",
      "tipoConteudo": "image/jpeg",
      "tamanhoArquivo": 245760,
      "dataUpload": "2025-01-15T14:30:00",
      "urlDownload": "/api/candidatos/123/documentos/50"
    },
    {
      "id": 51,
      "candidatoId": 123,
      "tipoDocumento": "CPF",
      "nomeArquivo": "cpf.pdf",
      "tipoConteudo": "application/pdf",
      "tamanhoArquivo": 102400,
      "dataUpload": "2025-01-15T14:35:00",
      "urlDownload": "/api/candidatos/123/documentos/51"
    }
  ]
}

GET Download de Documento

/api/candidatos/{candidatoId}/documentos/{documentoId}
Faz o download de um documento específico. Retorna o arquivo com headers apropriados para download.
Importante: Este endpoint valida se o documento pertence ao candidato informado e se o candidato pertence ao cliente autenticado.
Parâmetro Tipo Descrição
candidatoId integer ID do candidato (na URL)
documentoId integer ID do documento obtido na listagem (na URL)

Resposta:

Retorna o arquivo binário com headers:

Content-Type: application/pdf (ou image/jpeg, etc.)
Content-Disposition: attachment; filename="nome_arquivo.pdf"

GET Download de Arquivo de Campo Personalizado

/api/candidatos/{candidatoId}/campos-personalizados/{respostaId}/download
Faz o download de um arquivo anexado a um campo personalizado. Retorna o arquivo com headers apropriados para download.
Importante: Este endpoint valida se o campo pertence ao candidato informado e se o candidato pertence ao cliente autenticado.
Parâmetro Tipo Descrição
candidatoId integer ID do candidato (na URL)
respostaId integer ID da resposta do campo personalizado (respostaId obtido na listagem do candidato)

Resposta:

Retorna o arquivo binário com headers:

Content-Type: application/pdf (ou image/jpeg, etc.)
Content-Disposition: attachment; filename="nome_arquivo.pdf"

📋 Cargos

GET Listar Cargos

/api/cargos?somenteAtivos=true
Lista todos os cargos disponíveis para o cliente autenticado.
Parâmetro Tipo Obrigatório Descrição
somenteAtivos boolean Opcional Retornar apenas cargos ativos. Default: true

Exemplo de Resposta (200 OK):

{
  "sucesso": true,
  "mensagem": "Operação realizada com sucesso",
  "dados": [
    {
      "id": 5,
      "empresaId": 1,
      "nome": "Analista de Sistemas",
      "descricao": "Responsável pela análise e desenvolvimento de sistemas",
      "ativo": true,
      "dataCriacao": "2025-01-01T08:00:00"
    },
    {
      "id": 6,
      "empresaId": 1,
      "nome": "Desenvolvedor Full Stack",
      "descricao": "Desenvolvimento de aplicações web completas",
      "ativo": true,
      "dataCriacao": "2025-01-01T08:00:00"
    }
  ]
}

POST Criar Cargo

/api/cargos
Cria um novo cargo para o cliente autenticado.

Exemplo de Request Body:

{
  "nome": "Gerente de Projetos",
  "descricao": "Responsável pela gestão de projetos de TI",
  "ativo": true
}
Campo Tipo Obrigatório Descrição
nome string Obrigatório Nome do cargo (máx. 100 caracteres)
descricao string Opcional Descrição do cargo (máx. 500 caracteres)
ativo boolean Opcional Se o cargo está ativo. Default: true

Exemplo de Resposta (200 OK):

{
  "sucesso": true,
  "mensagem": "Cargo criado com sucesso",
  "dados": {
    "id": 7,
    "empresaId": 1,
    "nome": "Gerente de Projetos",
    "descricao": "Responsável pela gestão de projetos de TI",
    "ativo": true,
    "dataCriacao": "2025-12-16T10:00:00"
  }
}

📝 Campos Personalizados

GET Listar Campos Personalizados

/api/campos-personalizados?somenteAtivos=true
Lista todos os campos personalizados do cliente autenticado.
Parâmetro Tipo Obrigatório Descrição
somenteAtivos boolean Opcional Retornar apenas campos ativos. Default: true

Exemplo de Resposta (200 OK):

{
  "sucesso": true,
  "mensagem": "Operação realizada com sucesso",
  "dados": [
    {
      "id": 20,
      "clienteId": 1,
      "nome": "Tamanho da Camisa",
      "tipoCampo": "Select",
      "secao": "Outros",
      "placeholder": "Selecione o tamanho",
      "obrigatorio": true,
      "descricao": "Tamanho da camisa para uniforme",
      "ordem": 1,
      "ativo": true,
      "dataCriacao": "2025-01-01T08:00:00",
      "opcoes": [
        {
          "id": 1,
          "texto": "Pequeno (P)",
          "valor": "P",
          "ordem": 1,
          "ativo": true
        },
        {
          "id": 2,
          "texto": "Médio (M)",
          "valor": "M",
          "ordem": 2,
          "ativo": true
        },
        {
          "id": 3,
          "texto": "Grande (G)",
          "valor": "G",
          "ordem": 3,
          "ativo": true
        }
      ]
    },
    {
      "id": 21,
      "clienteId": 1,
      "nome": "Certificado de Curso",
      "tipoCampo": "Arquivo",
      "secao": "Documentos",
      "placeholder": "Envie o certificado em PDF",
      "obrigatorio": false,
      "descricao": "Certificado de curso técnico ou superior",
      "ordem": 2,
      "ativo": true,
      "dataCriacao": "2025-01-01T08:00:00",
      "opcoes": null
    }
  ]
}

POST Criar Campo Personalizado

/api/campos-personalizados
Cria um novo campo personalizado para o cliente autenticado. Para campos do tipo Select, é obrigatório incluir a lista de opções.

Exemplo 1: Campo tipo Texto

{
  "nome": "Número do Calçado",
  "tipoCampo": "Texto",
  "secao": "Outros",
  "secaoCustomizada": null,
  "placeholder": "Ex: 40",
  "obrigatorio": true,
  "descricao": "Número do calçado para uniforme",
  "ordem": 3,
  "ordemSecao": 1,
  "ativo": true
}

Exemplo 2: Campo tipo Select com Opções

{
  "nome": "Tamanho da Camisa",
  "tipoCampo": "Select",
  "secao": "Outros",
  "placeholder": "Selecione o tamanho",
  "obrigatorio": true,
  "descricao": "Tamanho da camisa para uniforme",
  "ordem": 1,
  "ativo": true,
  "opcoes": [
    {
      "texto": "Pequeno (P)",
      "valor": "P",
      "ordem": 1,
      "ativo": true
    },
    {
      "texto": "Médio (M)",
      "valor": "M",
      "ordem": 2,
      "ativo": true
    },
    {
      "texto": "Grande (G)",
      "valor": "G",
      "ordem": 3,
      "ativo": true
    },
    {
      "texto": "Extra Grande (GG)",
      "valor": "GG",
      "ordem": 4,
      "ativo": true
    }
  ]
}
Campo Tipo Obrigatório Descrição
nome string Obrigatório Nome do campo (máx. 100 caracteres)
tipoCampo string Obrigatório Tipo: Texto, Email, Telefone, CPF, RG, Data, Arquivo, Select
secao string Obrigatório Seção: DadosPessoais, Endereco, Documentos, Contato, Outros
obrigatorio boolean Opcional Se o campo é obrigatório. Default: false
placeholder string Opcional Texto de exemplo no campo (máx. 200 caracteres)
descricao string Opcional Descrição do campo (máx. 500 caracteres)
ordem integer Opcional Ordem de exibição. Default: 0
ordemSecao integer Opcional Ordem dentro da seção. Default: 0
ativo boolean Opcional Se o campo está ativo. Default: true
opcoes array Obrigatório* *Obrigatório apenas para campos tipo Select. Array de objetos com: texto, valor, ordem, ativo

Exemplo de Resposta para Campo tipo Texto (200 OK):

{
  "sucesso": true,
  "mensagem": "Campo criado com sucesso",
  "dados": {
    "id": 22,
    "clienteId": 1,
    "nome": "Número do Calçado",
    "tipoCampo": "Texto",
    "secao": "Outros",
    "placeholder": "Ex: 40",
    "obrigatorio": true,
    "descricao": "Número do calçado para uniforme",
    "ordem": 3,
    "ativo": true,
    "dataCriacao": "2025-12-16T10:00:00",
    "opcoes": null
  }
}

Exemplo de Resposta para Campo tipo Select (200 OK):

{
  "sucesso": true,
  "mensagem": "Campo criado com sucesso",
  "dados": {
    "id": 23,
    "clienteId": 1,
    "nome": "Tamanho da Camisa",
    "tipoCampo": "Select",
    "secao": "Outros",
    "placeholder": "Selecione o tamanho",
    "obrigatorio": true,
    "descricao": "Tamanho da camisa para uniforme",
    "ordem": 1,
    "ativo": true,
    "dataCriacao": "2025-12-16T10:00:00",
    "opcoes": [
      {
        "id": 1,
        "texto": "Pequeno (P)",
        "valor": "P",
        "ordem": 1,
        "ativo": true
      },
      {
        "id": 2,
        "texto": "Médio (M)",
        "valor": "M",
        "ordem": 2,
        "ativo": true
      },
      {
        "id": 3,
        "texto": "Grande (G)",
        "valor": "G",
        "ordem": 3,
        "ativo": true
      },
      {
        "id": 4,
        "texto": "Extra Grande (GG)",
        "valor": "GG",
        "ordem": 4,
        "ativo": true
      }
    ]
  }
}

POST Adicionar Opção a Campo Select

/api/campos-personalizados/{id}/opcoes
Adiciona uma nova opção a um campo do tipo Select existente. Apenas campos do tipo Select podem ter opções.

Exemplo de Request Body:

{
  "texto": "Extra Extra Grande (EXG)",
  "valor": "EXG",
  "ordem": 5,
  "ativo": true
}
Campo Tipo Obrigatório Descrição
texto string Obrigatório Texto exibido ao usuário (máx. 200 caracteres)
valor string Obrigatório Valor armazenado no banco de dados (máx. 200 caracteres)
ordem integer Opcional Ordem de exibição. Default: 0
ativo boolean Opcional Se a opção está ativa. Default: true

Exemplo de Resposta (200 OK):

{
  "sucesso": true,
  "mensagem": "Opção adicionada com sucesso",
  "dados": {
    "id": 5,
    "texto": "Extra Extra Grande (EXG)",
    "valor": "EXG",
    "ordem": 5,
    "ativo": true
  }
}

PUT Atualizar Opção

/api/campos-personalizados/{campoId}/opcoes/{opcaoId}
Atualiza uma opção existente de um campo do tipo Select.

Exemplo de Request Body:

{
  "texto": "Extra Grande (XG)",
  "valor": "XG",
  "ordem": 4,
  "ativo": true
}
Campo Tipo Obrigatório Descrição
texto string Obrigatório Texto exibido ao usuário (máx. 200 caracteres)
valor string Obrigatório Valor armazenado no banco de dados (máx. 200 caracteres)
ordem integer Opcional Ordem de exibição. Default: 0
ativo boolean Opcional Se a opção está ativa. Default: true

Exemplo de Resposta (200 OK):

{
  "sucesso": true,
  "mensagem": "Opção atualizada com sucesso",
  "dados": {
    "id": 4,
    "texto": "Extra Grande (XG)",
    "valor": "XG",
    "ordem": 4,
    "ativo": true
  }
}

DELETE Remover Opção

/api/campos-personalizados/{campoId}/opcoes/{opcaoId}
Remove (desativa) uma opção de um campo do tipo Select. A opção não é excluída fisicamente, apenas marcada como inativa.
Parâmetro Tipo Descrição
campoId integer ID do campo personalizado (na URL)
opcaoId integer ID da opção a ser removida (na URL)

Exemplo de Resposta (200 OK):

{
  "sucesso": true,
  "mensagem": "Opção removida com sucesso",
  "dados": null
}

⚙️ Campos Administrativos

GET Listar Campos Administrativos

/api/campos-administrativos?somenteAtivos=true
Lista todos os campos administrativos (visíveis apenas para administradores) do cliente autenticado.
Parâmetro Tipo Obrigatório Descrição
somenteAtivos boolean Opcional Retornar apenas campos ativos. Default: true

Exemplo de Resposta (200 OK):

{
  "sucesso": true,
  "mensagem": "Operação realizada com sucesso",
  "dados": [
    {
      "id": 10,
      "empresaId": 1,
      "nome": "Matrícula",
      "tipoCampo": "Texto",
      "opcoes": null,
      "obrigatorio": true,
      "descricao": "Número da matrícula do funcionário",
      "ordem": 1,
      "ativo": true,
      "dataCriacao": "2025-01-01T08:00:00"
    },
    {
      "id": 11,
      "empresaId": 1,
      "nome": "Centro de Custo",
      "tipoCampo": "Select",
      "opcoes": "[\"TI-001\", \"RH-002\", \"FIN-003\", \"OPS-004\"]",
      "obrigatorio": true,
      "descricao": "Centro de custo do departamento",
      "ordem": 2,
      "ativo": true,
      "dataCriacao": "2025-01-01T08:00:00"
    }
  ]
}

POST Criar Campo Administrativo

/api/campos-administrativos
Cria um novo campo administrativo para o cliente autenticado.

Exemplo de Request Body:

{
  "nome": "Salário",
  "tipoCampo": "Numero",
  "opcoes": null,
  "obrigatorio": true,
  "descricao": "Salário base do funcionário",
  "ordem": 3,
  "ativo": true
}
Campo Tipo Obrigatório Descrição
nome string Obrigatório Nome do campo (máx. 100 caracteres)
tipoCampo string Obrigatório Tipo: Texto, Numero, Data, SimNao, Select
opcoes string Opcional JSON array com opções para tipo Select. Ex: ["Opção 1", "Opção 2"]
obrigatorio boolean Opcional Se o campo é obrigatório. Default: false
descricao string Opcional Descrição do campo (máx. 500 caracteres)
ordem integer Opcional Ordem de exibição. Default: 0
ativo boolean Opcional Se o campo está ativo. Default: true

Exemplo de Resposta (200 OK):

{
  "sucesso": true,
  "mensagem": "Campo criado com sucesso",
  "dados": {
    "id": 12,
    "empresaId": 1,
    "nome": "Salário",
    "tipoCampo": "Numero",
    "opcoes": null,
    "obrigatorio": true,
    "descricao": "Salário base do funcionário",
    "ordem": 3,
    "ativo": true,
    "dataCriacao": "2025-12-16T10:00:00"
  }
}

⚠️ Códigos de Erro

Código HTTP Descrição Exemplo de Resposta
401 Não autorizado - Credenciais inválidas 
{
  "sucesso": false,
  "mensagem": "ClientId inválido ou cliente inativo."
}
400 Requisição inválida - Dados incorretos 
{
  "sucesso": false,
  "mensagem": "O campo Email é obrigatório."
}
404 Recurso não encontrado 
{
  "sucesso": false,
  "mensagem": "Candidato não encontrado."
}
500 Erro interno do servidor 
{
  "sucesso": false,
  "mensagem": "Erro ao processar requisição: [detalhes]"
}

ℹ️ Informações Adicionais

Formato de Data e Hora

Todas as datas são retornadas no formato ISO 8601: yyyy-MM-ddTHH:mm:ss

Exemplo: 2025-12-16T10:30:00

Charset e Codificação

Todas as requisições e respostas utilizam codificação UTF-8.

Rate Limiting

Não há limitação de taxa implementada atualmente, mas recomenda-se uso responsável da API.

Segurança

  • Todas as credenciais devem ser armazenadas de forma segura
  • O ClientSecret é exibido apenas uma vez após geração
  • Use HTTPS em produção para proteger as credenciais em trânsito
  • Cada cliente acessa apenas seus próprios dados