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
- Adição dos endpoints sobre as pessoas candidatas do Banco de talentos
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.
03. ENDPOINT E PARÂMETROS DE ENTRADA
Endpoint da API que será utilizado para inserir e atualizar dados:
| Método | Endpoint | Descrição | Status Code de Sucesso | Documentação | |
|---|---|---|---|---|---|
| 1 | CANDIDATURA | ||||
| 1.1 | GET | {URL base}/api/v1/job-application/search | Retorna todos os candidatos que estão na etapa de contratação e se encaixam nos filtros inseridos na chamada. | 200 | GET Candidatura |
| 1.2 | POST | {URL base}/api/v1/job-application/change-status | Envia os dados para atualizar o status da candidatura em uma vaga publicada. | 201 | POST Candidatura |
| 2 | VAGA | ||||
| 2.1 | POST | {URL base}/api/v1/job-opportunity | Envia os dados para cadastrar uma vaga em rascunho no ATS. | 201 | |
| 3 | ÁREA | ||||
| 3.1 | POST | {URL base}/api/v1/department | Envia os dados para cadastrar áreas no ATS | 201 | POST Área |
| 3.2 | PUT | {URL base}/api/v1/department/{id} | Envia os dados para atualizar uma área no ATS | 200 | PUT Área |
| 3.3 | GET | {URL base}/api/v1/department/search | Retorna todas as áreas com possibilidade de filtro | 200 | GET Área |
| 4 | UNIDADE | ||||
| 4.1 | POST | {URL base}/api/v1/facility | Envia os dados para cadastrar unidades no ATS | 201 | POST Unidade |
| 4.2 | PUT | {URL base}/api/v1/facility/{id} | Envia os dados para atualizar uma unidade no ATS | 200 | PUT Unidade |
| 4.3 | GET | {URL base}/api/v1/facility/search | Retorna todas as unidades com possibilidade de filtro | 200 | GET Unidade |
| 5 | CARGO | ||||
| 5.1 | POST | {URL base}/api/v1/position | Envia os dados para cadastrar cargos no ATS | 201 | POST Cargo |
| 5.2 | PUT | {URL base}/api/v1/position/{id} | Envia os dados para atualizar uma cargo no ATS | 200 | PUT Cargo |
| 5.3 | GET | {URL base}/api/v1/position/search | Retorna todas as cargos com possibilidade de filtro | 200 | GET Cargo |
| 6 | LOCALIDADE | ||||
| 6.1 | GET | {URL base}/api/v1/locality/state | Busca todos os estados do Brasil | 200 | GET Estados |
| 6.2 | GET | {URL base}/api/v1/locality/state/{stateId}/city | Busca todas as cidades de um estado | 200 | GET Cidades |
| 7 | BANCO DE TALENTOS | ||||
| 7.1 | GET | {URL base}/api/v1/talent-bank/get-all | Busca informações sobre as pessoas candidatas que estão no banco de talentos | 200 | GET Pessoas Candidatas |
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.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, 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, que pode ser recuperado na página de Chaves da integraçã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, para produção utilizar a url: https://admin.rac.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 para client_id e client_secret. Para ter acesso aos valores que devem ser inseridos, é necessário entrar em contato com o time de desenvolvimento do produto.
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