Histórico da Página
01. VISÃO GERAL
RESUMO
A integração possibilita a criação e utilização dos dados de candidatos, candidaturas e vagas no TOTVS RH Atração de Talentos.
Os grupos de dados relacionados à Candidaturas irão permitir que o sistema de origem envie as informações de candidatos que estão aptos para iniciar o processo de admissão. Estes candidatos por regras devem estar inseridos na etapa de contratação em uma vaga de status Publicada no TOTVS RH Atração de Talentos.
Os grupos de dados relacionados à vagas, por sua vez, receberão as informações de uma nova requisição de vaga vindo do sistema de origem e, com isso irá criar uma vaga no status rascunho dentro do TOTVS RH Atração de Talentos.
Os dados que atualmente são possíveis realizar a integração com o produto são:
- Candidaturas
- Relacionado aos candidatos:
- Dados pessoais;
- Informações de localização;
- Informações complementares relacionadas à Diversidade e Inclusão, sendo essas de preenchimento opcional para o candidato.
- Relacionado à vaga:
- Informações específicas da vaga;
- Informações da empresa;
- Informações de cadastro.
- Relacionado à candidatura em uma vaga:
- Atualização do status do candidato.
- Relacionado aos candidatos:
- Vagas
- Informações específicas da vaga;
- Informações de cadastro.
- Área
- Informações específicas da área;
- Informações de cadastro.
- Unidade
- Informações específicas da unidade;
- Informações de cadastro.
- Cargo
- Informações específicas da cargo;
- Informações de cadastro.
- Localidade
- Informações dos estados
- Informações das cidades
Quando houver mudanças significativas no contrato da API, a versão dessas API's serão alteradas e o sistema de origem deverá se certificar que a versão que está sendo utilizada ainda é mantida pela TOTVS.
HISTÓRICO DE ALTERAÇÕES
- Criação do endpoint para retornar os dados das candidaturas que possuem status “contratado” em vagas abertas.
- Criação do endpoint para receber os dados para criação da vaga.
- Criação do endpoint para atualizar o status da candidatura.
- Inclusão dos campos isCLT, isPJ e isInternship referentes ao regime de contratação na API de GET de candidaturas.
- Adição dos endpoints de Cargo, Área, Unidade e Localidades
02. FLUXO DE INTEGRAÇÃO
A solicitação de sincronização (envio de dados) deve ocorrer em uma opção dentro do sistema de origem, não havendo como solicitar a sincronização a partir do ATS, portanto, esta sincronização ocorre via ação do usuário-cliente, não havendo um fluxo automático.
Os endpoints de integração funcionam de forma assíncrona, portanto o envio de dados sempre irá ocorrer em lotes de no máximo 100 registros. Para cada lote enviado o endpoint de integração irá devolver um ID do processo, sendo possível realizar a sua consulta do status do lote através de endpoints de consulta.
Os registros que estiverem válidos serão gravados na base de dados enquanto os que tiverem erros de validação não serão gravados, neste caso será retornado no endpoint de consulta qual validação falhou, o integration ID do registro e um código do erro que poderá ser utilizado para obter mais detalhes na seção 04 de erros de validação que se encontra neste documento.
Este documento apresenta os parâmetros de entrada e o retorno da API de GET de candidatura.
...
02.
ENDPOINT E PARÂMETROS DE ENTRADA
Endpoint da API que será utilizado para inserir e atualizar dados:
| URL base | Endpoint |
|---|---|
| https://api-centraldorecrutador.dev.totvs.app/recruitment-integration/swagger |
| {URL base}/api/v1/job-application |
201
| / |
| search |
2
...
1 - CANDIDATURA
1.1 - DADOS ENVIADOS NO ENDPOINT DE CANDIDATURAENVIADOS
Parâmetro | Descrição |
|---|---|
| jobOpportunityStatus | Filtrar pelo status da vaga (Padrão é status Publicado) |
| jobApplicationStatus | Filtrar pelo status da candidatura (Padrão é status Contratado) |
| jobApplicantId | Filtrar pelo identificador do candidato |
| jobApplicationChangeStatus | Filtrar para pegar todos os candidatos com data de alteração posterior a informada |
| page | Número da página que deseja obter os dados |
...
| Campo | Descrição |
|---|---|
| integrationId | ID único de integração |
| hiringDate | Data de contratação |
| jobOpportunity.code | Código da vaga ATS |
| jobOpportunity.internalClientCode | Código da vaga (interno ERP) |
| jobOpportunity.title | Título da vaga |
| jobOpportunity.jobOpportunityType | Tipo da vaga |
| jobOpportunity.invitationLanguage | Idioma do convite |
| jobOpportunity.facility.name | Nome unidade (Filial) |
| jobOpportunity.facility.cnpj | CNPJ unidade |
| jobOpportunity.facility.stateSmallName | Estado (UF) |
| jobOpportunity.facility.cityName | Cidade |
| jobOpportunity.facility.integrationId | Código unidade (interno ERP) |
| jobOpportunity.department.name | Nome da área/departamento |
| jobOpportunity.department.integrationId | Código da área/departamento (interno ERP) |
| jobOpportunity.position.name | Nome do cargo |
| jobOpportunity.position.integrationId | Código do cargo (interno ERP) |
| jobOpportunity.isCLT | Regime de contratação CLT |
| jobOpportunity.isPJ | Regime de contratação Pessoa jurídica |
| jobOpportunity.IsInternship | Regime de contratação Estágio |
| jobOpportunity.isFreelancer | Regime de contratação Freelancer |
| jobOpportunity.isCooperated | Regime de contratação Cooperado |
| fullName | Nome do candidato |
| applicant.id | Código do candidato |
| applicant.cpf | CPF do candidato |
| applicant.email | E-mail do candidato |
| applicant.birthday | Data de nascimento |
| applicant.telephoneNumber | Telefone |
| applicant.zipCode | CEP |
| applicant.address | Endereço |
| applicant.cityName | Cidade |
| applicant.stateName | Estado |
| applicant.gender | Gênero |
| applicant.diversity | Deficiência |
1.2 - DADOS ENVIADOS NO ENDPOINT DE ATUALIZAÇÃO DO STATUS DA CANDIDATURA
...
Parâmetro
...
Descrição
...
Novo status desejado para a candidatura, com as seguintes opções:
- AdmissionInProgress - para Admissão iniciada
- Hired - para Contratado
- AdmissionCanceled - para Admissão cancelada
Retorno:
...
Descrição
...
O retorno é uma string que é o identificador do processo que será utilizado no endpoint de consulta para checar o status do processamento do lote
2 - VAGA
2.1 - DADOS ENVIADOS NO ENDPOINT DE VAGA
...
Título da vaga
...
isInternship
Tipo da vaga
...
isPJ
...
Modelo de trabalho
...
Justificativa da requisição
Retorno:
...
Descrição
...
O retorno é uma string que é o identificador do processo que será utilizado no endpoint de consulta para checar o status do processamento do lote
3 - Área
3.1 - DADOS ENVIADOS NO ENDPOINT CRIAÇÂO DE ÁREAS
...
Nome da área
...
ID único de integração
Retorno:
...
Descrição
...
O retorno é uma string que é o identificador do processo que será utilizado no endpoint de consulta para checar o status do processamento do lote
3.1 - DADOS ENVIADOS NO ENDPOINT ATUALIZAÇÂO DE ÁREA
...
Nome da área
...
ID único de integração
Retorno:
...
Campo
...
Descrição
...
Identificador da área atualizada
4 - Unidade
4.1 - DADOS ENVIADOS NO ENDPOINT CRIAÇÂO DE UNIDADES
...
Nome da unidade
...
ID único de integração
...
Retorno:
...
Descrição
...
O retorno é uma string que é o identificador do processo que será utilizado no endpoint de consulta para checar o status do processamento do lote
4.1 - DADOS ENVIADOS NO ENDPOINT ATUALIZAÇÂO DE UNIDADE
...
Nome da unidade
...
ID único de integração
...
Retorno:
...
Campo
...
Descrição
...
Identificador da área atualizada
5 - Cargo
5.1 - DADOS ENVIADOS NO ENDPOINT CRIAÇÂO DE CARGOS
...
Nome da cargo
...
ID único de integração
...
Retorno:
...
Descrição
...
O retorno é uma string que é o identificador do processo que será utilizado no endpoint de consulta para checar o status do processamento do lote
5.1 - DADOS ENVIADOS NO ENDPOINT ATUALIZAÇÂO DE CARGO
...
Nome da cargo
...
ID único de integração
...
Retorno:
...
Campo
...
Descrição
...
Identificador da área atualizada
| Nota |
|---|
O detalhamento do formato dos objetos JSON que serão trafegados no envio e retorno dos endpoints devem ser consultados na documentação do swagger do ambiente citado no início desta seção. A URL para acesso a documentação é - https://api-centraldorecrutador.dev.totvs.app/recruitment-integration/swagger/index.html |
04. ERROS DE VALIDAÇÃO
Em situações onde há má formatação do corpo da requisição, ou seja, ao não informar os dados citados abaixo de forma válida, será retornado um erro do tipo Bad Request 400 na requisição acompanhado de mensagens informando quais campos estão inconsistentes.
05. TOKEN DE ACESSO
A autorização da API é gerenciada por um token de acesso do RAC sendo um token de fluxo ClientCredentials, portanto é um token de aplicação que não contém usuário sendo necessário apenas o ClientID e SecretID para geração. Durante o desenvolvimento recomendamos que o token de acesso seja gerado através do postman conforme as instruções a seguir:
1 - No Postman, criar uma requisição POST com o endereço do endpoint de geração do ambiente de desenvolvimento da TOTVS. O environment deve ser informado dev, caso esteja em ambiente de desenvolvimento: https://admin.rac.dev.totvs.app/totvs.rac/connect/token
2 - Na aba Headers inclua a Key: Content-Type com o Value: application/x-www-form-urlencoded; charset=UTF-8
3 - Na aba Body acrescente as Key abaixo com seus respectivos valores.
client_id: b25b85b238c448d6bcbdcab2a73201de
client_secret: a5d704614d2648c5a4aca07ca5a480b0
4 - Com estes dados preenchidos, ao clicar no botão SEND será retornado um JSON com o token de autorização para ser utilizado no Swagger ou nas requisições criadas no sistema de origem.
...
Visão Geral
Import HTML Content
Conteúdo das Ferramentas
Tarefas