Child pages
  • DI Protheus - Cadastro de Currículos
Skip to end of metadata
Go to start of metadata

INTEGRAÇÃO RSPA010API

Contexto de negócio (Introdução)

Cada vez mais o mercado exige que operações complexas e manipulação de dados sejam mais ágeis e com custos reduzidos. Com o RH não é diferente, os processos cada vez mais complexos,  com muitas variáveis a serem analisadas na contratação, os recrutadores precisam de agilidade na análise e uma avaliação mais crítica no momento de contratar um novo recurso.

Com essa necessidade e a importância desta área dentro da empresa, softwares especializados em recrutamento e seleção estão cada vez mais presentes no mercado e foi neste contexto que surgiu a necessidade da criação de uma interface que possibilite automatizar o cadastro base dos candidatos dentro do ERP através de uma interface de integração.

Sistemas Envolvidos

  • Protheus (módulo Recrutamento e Seleção - RSP): responsável por controlar os processos de recrutamento e seleção, auxiliando desde o cadastramento do currículo do candidato até a contratação do funcionário na empresa, vinculado a uma vaga específica.


Integração

O objetivo desta integração é permitir que o RH ou área responsável pelo recrutamento e seleção do Protheus, recebam os dados básicos de currículo dos candidatos de outros sistemas especializados, reduzindo assim o trabalho de inclusão manual de todas as informações dentro do sistema;

  • Benefícios do Recrutador
    • O recrutador poderá fazer uso de um sistema mais robusto para recrutamento.
    • Não terá um investimento alto de tempo para o cadastramento, pois os dados básicos do currículo serão enviados através da API de Candidatos.
  • Arquitetura (Tecnologia)

Toda integração entre o Protheus e o Sistema é feita por intermédio de comunicação direta com os Web Services(que são fixos) REST(Representation State Transfer) utilizando o formato JSON(JavaScript  Object Notation) de serialização de dados, onde através da ativação do serviço do REST do Protheus esteja disponível para utilizar o serviço.

Escopo

Por intermédio desta integração será disponibilizada a seguinte funcionalidade:

  • Cadastramento de Currículo no módulo SIGARSP;


Fora do escopo

  • Automatização de consultas de currículos ou candidatos.
  • Importação de base cadastral - cadastro de currículo.
  • Informações do candidato que não se enquadram dentro da tabela de currículo.
  • Atualização de currículo já cadastrado.

Pré-requisitos instalação/implantação/utilização

  • Versões mínimas do Protheus: 12.1.25
  • Possuir acesso à Internet, caso o sistema que venha a utilizar a integração com a aplicação Protheus.
  • Estrutura de rede estável, para que haja tráfego de dados sem interrupção.
  • Protheus devidamente configurado e serviço Rest habilitado em seu server.

Instalação/Atualização

Este tópico tem por objetivo orientar a instalação da integração, visando o seu funcionamento completo. Instalação de produtos ou ferramentas necessárias podem referenciar outros documentos existentes, desde que estejam disponíveis no repositório de documentação da TOTVS ou sejam enviados junto com o documento da integração em si.

As informações mínimas necessárias para este tópico são:

Ativação/Desativação da integração

Por padrão esta integração estará em repositório, porém demanda realizar a devida configuração conforme abaixo:

Controle de Ambiente

Exige que os seguintes pontos sejam revisados:

  • Protheus com sua arquitetura devidamente estruturada.
  • Módulo de Recrutamento e Seleção com suas entidades base, devidamente populadas por dados que no momento da integração serão utilizados na criação do registro de currículo.(Para melhor compreensão, analise o cadastro de currículo e verifique os campos que possuem consultas em outras tabelas se as mesmas estão com os seus dados devidamente cadastrados).

Controle de Versão

O grupo TOTVS, representado por suas marcas, irá administrar as demandas de evolução dos layouts e demais ajustes, acordando junto aos solicitantes o prazo de liberação de release.

Todas as evoluções programadas deverão ser discutidas e aprovadas pelas marcas antes do início do desenvolvimento e somente serão desenvolvidas em caso de concordância das marcas e alinhamento com as diretivas definidas pelo Comitê de Integração TOTVS.


Suporte

O suporte aos recursos da Integração será de responsabilidade da linha MicroSiga Protheus, onde será analisada pela equipe de suporte da Totvs.

Fluxo das Informações

Esta integração traz a funcionalidade exclusivamente a área de recrutamento e seleção, no processo de cadastramento de currículo.

Cadastro

Esta integração contempla apenas o cadastramento de currículo dentro do módulo SIGARSP. 

Processos

O Sistema requisitante enviará as informações via json para a interface de integração, desta forma será gerado um novo registro na tabela de currículo no Protheus, caso tenha êxito na geração do registro, será retornado a mesma estrutura de json confirmando sua gravação, caso contrário enviará as informações de inconsistências citadas nos próximos tópicos.

Limitações / Restrições Gerais

  • Com o objetivo de manter a estrutura e a agilidade da estrutura Rest, o Web Service Rest receberá registro individual de cada currículo de candidato.
  • A integração não contemplará exclusão de registros no Protheus, para isso o usuário deverá acessar o ERP e excluir manualmente o mesmo.

Como realizar a chamada da API REST

Para realizar a integração com o parceiro TOTVS é necessário as informações básicas de consulta para retorno dos funcionários desejados.

  • Preenchimento do EndPoint da API RSPA010API;
  • Utilizar a chamada do método Post, Put, Delete, Get e do Serviço candidate;
  • Preenchimento dos parâmetros obrigatórios da API;




Parâmetros de Entrada POST:

Parâmetro

Valor de Exemplo

Obrigatório

Tipo

Valor Default

Descrição
authorization usuario:senhaSim

header


autenticação é importante para o funcionamento correto da API em casos de ambientes com autenticação Http Basic.
contentrequest da apisimbody

Estrutura json com informações de cadastro do currículo:

Propriedades Obrigatórias:

Dados de preparação de ambiente.

  • companyId: Grupo de empresa
  • branchId: Empresa+Unidade de negócio+Filial

Dados de currículo.

  • cpf: Informação pertinente ao candidato
  • name: Nome do candidato.

Parâmetros e Chamada do Método:

Para a realização de testes foi utilizado a ferramenta SOAP UI e após a configuração do server protheus a API Rest, a  requisição deverá ser semelhante a imagem abaixo:

{protocolo}://{host}/{api}/rh/v2/candidates

Request da API:

Exemplo de Request da API
{
	"companyId":"T1",
	"branchId":"D MG 01",
    "id": "000001",
    "Name": "JOÃO PEREIRA DA SILVAI",
    "Birth": "01/01/1990",
    "HomeState": "MG",
    "Naturalness": "Belo Horizonte",
    "NickName": "Jão",
    "Sex": "M",
    "Nationality": "10",
    "EducationalLevel": "9",
    "Street": "Rua Mata Atlantica",
    "Number": "333",
    "District": "Planalto",
    "State": "MG",
    "City": "Belo Horizonte",
    "Cep": "30100020",
    "Country": "Brasil",
    "ProfessionalRegistrationNumber": "Reg-00098",
    "Cpf": "51427362653",
    "ImageId": 844,
    "PhoneNumber1": "4613636",
    "PhoneNumber2": "4613636",
    "identityNumber": "M 267392",
    "IdentityNumberEmitterState": "MG",
    "IdentityNumberEmitterAgency": "SSP",
    "IdentityNumberEmissionDate": "1993-04-25T00:00:00",
    "ElectoralCard": "123.334",
    "ElectoralWard": "0012",
    "ElectoralSection": "0006",
    "WorkCard": "015116",
    "WorkCardSerialNumber": "00001",
    "WorkCardEmitterState": "MG",
    "WorkCardEmissionDate": "1993-03-01T00:00:00",
    "Nit": 0,
    "DriversLicense": "13.344.543",
    "DriversLicenseType": "A",
    "DriversLicenseExpirationDate": "1997-02-05T00:00:00",
    "MilitaryDischargeCertificate": "12856945678",
    "MilitaryGrade": "CDI",
    "BrazilConsort": 0,
    "Naturalized": 0,
    "BrazilianChildren": 0,
    "BrazilianChildrenNumber": "2",
    "Email": "teste@totvs.com.br",
    "PreviousTrainingInvestment": "2300.00",
    "ShadeRace": "0",
    "Disabled": 0,
    "UserCode": "simone",
    "PhoneNumber3": "21229000",
    "Company": "RM SISTEMAS S.A",
    "OccupationCode": "10",
    "Rehabilitated": 0,
    "Smoker": 0,
    "AdjustsImageSize": 0,
    "DeafPerson": 0,
    "MutePerson": 0,
    "BlindPerson": 0,
    "MentallyImpairedPerson": 0,
    "CurriculumApprovalDate": "2005-04-01T09:36:02.66",
    "Student": 1,
    "Teacher": 1,
    "Candidate": 1,
    "BibliosUser": 1,
    "Employee": 1,
    "FormerEmployee": 0,
    "IntellectualImpairedPerson": 0,
    "Deceased": 0,
    "Age": 53,
    "RegistryDate": "2019-05-02T20:32:12.931Z",
    "WageExpectation": "1111.32",
    "AreaOfInterestCode1": "15",
    "AreaOfInterestCode2": "15",
    "WageExpectationTradable": "1",
    "azerienceTime": "15",
    "WorkExperienceTimeArea1": "15",
    "WorkExperienceTimeArea2": "15",
    "ContraIndicated": "1",
    "ContraindicationReason": "string",
    "Available": "1",
    "FormOfRecruitment": "string",
    "ResumeSkillsId": "15",
    "HierarchyLevelCode": "15",
    "ProfessionalProfileDescription": "string",
    "AreaOfInterestDescription1": "string",
    "AreaOfInterestDescription2": "string",
    "HierarchyLevelDescription": "string",
    "ProfessionalSkillsResumeDescription": "string",
    "Employee1": "string",
    "PersonalEmail": "string",
    "MaritalState": "string",
    "Complement": "string",
    "ArrivalDate": "2019-05-02T20:32:12.931Z",
    "LetterModel19": "string",
    "Rne": "string",
    "ImmigrationDecree": "string",
    "RneExpirationDate": "2019-05-02T20:32:12.931Z",
    "WorkCardExpirationDate": "2019-05-02T20:32:12.931Z",
    "VisaType": "string",
    "PassportNumber": "string",
    "NativeCountry": "string",
    "PassportExpirationDate": "2019-05-02T20:32:12.931Z",
    "AccessibilityFeaturesForJobLocal": "string",
    "MilitaryDivision": "string",
    "MilitaryCertificateEmissionDate": "2019-05-02T20:32:12.931Z",
    "MilitaryCertificateEmitterAgency": "2019-05-02T20:32:12.931Z",
    "MilitaryRegion": "string",
    "MilitarySituation": "string",
    "ElectoralCardEmitterState": "string",
    "BloodType": "string",
    "Image": "string",
    "NeighborhoodTypeCode": "15",
    "NaturalnessCode": "string",
    "NaturalisationDate": "2019-05-02T20:32:12.931Z",
    "DriversLicenseEmitterAgency": "string",
    "RneEmitterAgency": "string",
    "CountryId": "1",
    "DeceaseDate": "2019-05-02T20:32:12.931Z",
    "DeathCertificateNumber": "string",
    "NaturalisationGatehouse": "string",
    "BrazilConditionClassification": "string",
    "DriversLicenseFirstEmissionDate": "2019-05-02T20:32:12.931Z",
    "FirstJobYear": "15"
}


Dados utilizados da API

Por ser uma estrutura única para todos os produtos, há dados que existem em um produto (RM) e não existe no Protheus, desta forma cada produto utilizará os campos pertinentes aos seus ambientes.

Propriedade API RESTCAMPO PROTHEUSDESCRIÇÃOFormato
companyId
Informações de acesso ao sistema, campo contém informação do grupo de empresa
branchId
Informações de acesso ao sistema, campo compõe Empresa+Unidade de Negócio+ Filial
NameQG_NOMENome do Candidato"JOÃO PEREIRA  SILVA"
RegistryDateQG_DTCADData do Registro2019-05-02T20:32:12
DistrictQG_BAIRROBairroBARRA FUNDA
CityQG_MUNICIPMunicipSAO PAULO
StateQG_ESTADOEstadoSP
CepQG_CEPCep12345678
PhoneNumber1QG_FONEFone
PhoneNumber2QG_FONECELFone Celular
PhoneNumber3QG_FONECOMFone Comercial
identityNumberQG_RGRG123456789
CpfQG_CICCPF12345678900
WorkCardQG_NUMCPNum CP
WorkCardSerialNumberQG_SERCPSerie CP
WorkCardEmitterStateQG_UFCPUF CP
DriversLicenseQG_HABILITHabilitação
MilitaryDischargeCertificateQG_RESERVReservista
ElectoralCardQG_TITULOETitulo Eleitor
Street + NumberQG_ENDERECEndereço
ElectoralWard+ElectoralSectionQG_ZONASECZona Eleitoral
SexQG_SEXOSexoF - Feminino; M - Masculino.
MaritalStateQG_ESTCIVEstado Civil

C - Casado; D - Divorciado; M - União Estável; 
Q - Desquitado; S - Solteiro; V - Viúvo. 

HomeStateQG_NATURALNaturalidade - UFSP
NationalityQG_NACIONANacionalidade10
BirthQG_DTNASCData de Nascimento1900-01-01T01:01:01
"001" QG_SITUACSituac (Status Disponível)
EmailQG_EMAILEmailTESTE@TESTE.COM.BR
DisabledQG_DFISICODeficiente fisico

1- Sim; 2 - Não.

NaturalnessQG_MUNNASCNaturalidadeSAO PAULO
AreaOfInterestCode1QG_AREACódigo da área de interesse 1
HierarchyLevelCodeQG_NIVHIERCódigo do nível hierárquico
WorkExperienceTimeQG_TPEXPERTempo de experiência profissional
WageExpectationQG_PRETSALPretensão Salarial1000.00
ArrivalDateQG_ANOCHEGData de chegada no Brasil1900-01-01T01:01:01
ProfessionalSkillsResumeDescriptionQG_MEMO2Descrição do resumo de qualificações

Situações de Erros Tratados

O envio de dados inesperados nos parâmetros de entrada da API REST pode ocasionar alguns erros. Desta forma, foram criados alguns tratamentos de erros, listados abaixo, cada um com sua respectiva mensagem e solução.

Tratamento de erros de integração Protheus:


Mensagens de Pré-Validação

Erro

Mensagem

Solução

API RESPONSE

400

Verificar se a propriedade (name) está preenchida.

Verificar se a propriedade json name está preenchida no pacote enviado .

{
   "errorCode": 400,
   "errorMessage": "VERIFICAR SE A PROPRIEDADE (Name) ESTÁ PREENCHIDA, POIS A MESMA É OBRIGATÓRIA PARA GERAÇÃO DO CADASTRO DE CURRÍCULO.\r\n"
}
400

Verificar se a propriedade (AreaOfInterestCode1)  possui cadastro no Protheus.

É necessário analisar o cadastro dentro do Protheus, para checagem se o código da área de interesse existe no Protheus, é possível checar pela própria tela de currículo.
{
   "errorCode": 400,
   "errorMessage": "VERIFICAR SE A PROPRIEDADE (AreaOfInterestCode1) POSSUI CADASTRO DO PROTHEUS E REENVIAR.\r\n"
}
400

Verificar se a propriedade (Cpf)  está preenchida.

Verificar se a propriedade json cpf está preenchida no pacote enviado .
{
   "errorCode": 400,
  "errorMessage": "VERIFICAR SE A PROPRIEDADE (Cpf) ESTÁ PREENCHIDA, POIS A MESMA É OBRIGATÓRIA PARA GERAÇÃO DO CADASTRO DE CURRÍCULO.\r\n"
}


OBS: Estas mensagens de validações serão retornadas sempre que algum campo passado que seja obrigatório ou que algum campo enviado tenha sua origem de dados em outra tabela e não seja localizado na mesma, vale lembrar que são apenas exemplos de mensagens de erros e podendo variar o nome da propriedade enviada.


Parâmetros de Entrada PUT:

Parâmetro

Valor de Exemplo

Obrigatório

Tipo

Valor Default

Descrição
authorization usuario:senhaSim

header

""autenticação é importante para o funcionamento correto da API em casos de ambientes com autenticação Http Basic.
candidatesId'T1|D MG 01|12345678910'Simrequest""

Composição da string a ser enviada, deve ser ser composta por "GRUPO DE EMPRESA|QG_FILIAL|QG_CIC".

contentlayout jsonsimbody""

Estrutura json com informações de cadastro do currículo:

Propriedades Obrigatórias:

Dados de preparação de ambiente.

  • companyId: Grupo de empresa
  • branchId: Empresa+Unidade de negócio+Filial

Dados de currículo.

  • cpf: Informação pertinente ao candidato
  • name: Nome do candidato.

Parâmetros e Chamada do Método:

Para a realização de testes foi utilizado a ferramenta SOAP UI e após a configuração do server protheus a API Rest, a  requisição deverá ser semelhante a imagem abaixo:

{protocolo}://{host}/{api}/rh/v2/candidates

Request da API:

Exemplo de Request da API
{
	"companyId":"T1",
	"branchId":"D MG 01",
    "id": "000001",
    "Name": "JOÃO PEREIRA DA SILVAI",
    "Birth": "01/01/1990",
    "HomeState": "MG",
    "Naturalness": "Belo Horizonte",
    "NickName": "Jão",
    "Sex": "M",
    "Nationality": "10",
    "EducationalLevel": "9",
    "Street": "Rua Mata Atlantica",
    "Number": "333",
    "District": "Planalto",
    "State": "MG",
    "City": "Belo Horizonte",
    "Cep": "30100020",
    "Country": "Brasil",
    "ProfessionalRegistrationNumber": "Reg-00098",
    "Cpf": "51427362653",
    "ImageId": 844,
    "PhoneNumber1": "4613636",
    "PhoneNumber2": "4613636",
    "identityNumber": "M 267392",
    "IdentityNumberEmitterState": "MG",
    "IdentityNumberEmitterAgency": "SSP",
    "IdentityNumberEmissionDate": "1993-04-25T00:00:00",
    "ElectoralCard": "123.334",
    "ElectoralWard": "0012",
    "ElectoralSection": "0006",
    "WorkCard": "015116",
    "WorkCardSerialNumber": "00001",
    "WorkCardEmitterState": "MG",
    "WorkCardEmissionDate": "1993-03-01T00:00:00",
    "Nit": 0,
    "DriversLicense": "13.344.543",
    "DriversLicenseType": "A",
    "DriversLicenseExpirationDate": "1997-02-05T00:00:00",
    "MilitaryDischargeCertificate": "12856945678",
    "MilitaryGrade": "CDI",
    "BrazilConsort": 0,
    "Naturalized": 0,
    "BrazilianChildren": 0,
    "BrazilianChildrenNumber": "2",
    "Email": "teste@totvs.com.br",
    "PreviousTrainingInvestment": "2300.00",
    "ShadeRace": "0",
    "Disabled": 0,
    "UserCode": "simone",
    "PhoneNumber3": "21229000",
    "Company": "RM SISTEMAS S.A",
    "OccupationCode": "10",
    "Rehabilitated": 0,
    "Smoker": 0,
    "AdjustsImageSize": 0,
    "DeafPerson": 0,
    "MutePerson": 0,
    "BlindPerson": 0,
    "MentallyImpairedPerson": 0,
    "CurriculumApprovalDate": "2005-04-01T09:36:02.66",
    "Student": 1,
    "Teacher": 1,
    "Candidate": 1,
    "BibliosUser": 1,
    "Employee": 1,
    "FormerEmployee": 0,
    "IntellectualImpairedPerson": 0,
    "Deceased": 0,
    "Age": 53,
    "RegistryDate": "2019-05-02T20:32:12.931Z",
    "WageExpectation": "1111.32",
    "AreaOfInterestCode1": "15",
    "AreaOfInterestCode2": "15",
    "WageExpectationTradable": "1",
    "azerienceTime": "15",
    "WorkExperienceTimeArea1": "15",
    "WorkExperienceTimeArea2": "15",
    "ContraIndicated": "1",
    "ContraindicationReason": "string",
    "Available": "1",
    "FormOfRecruitment": "string",
    "ResumeSkillsId": "15",
    "HierarchyLevelCode": "15",
    "ProfessionalProfileDescription": "string",
    "AreaOfInterestDescription1": "string",
    "AreaOfInterestDescription2": "string",
    "HierarchyLevelDescription": "string",
    "ProfessionalSkillsResumeDescription": "string",
    "Employee1": "string",
    "PersonalEmail": "string",
    "MaritalState": "string",
    "Complement": "string",
    "ArrivalDate": "2019-05-02T20:32:12.931Z",
    "LetterModel19": "string",
    "Rne": "string",
    "ImmigrationDecree": "string",
    "RneExpirationDate": "2019-05-02T20:32:12.931Z",
    "WorkCardExpirationDate": "2019-05-02T20:32:12.931Z",
    "VisaType": "string",
    "PassportNumber": "string",
    "NativeCountry": "string",
    "PassportExpirationDate": "2019-05-02T20:32:12.931Z",
    "AccessibilityFeaturesForJobLocal": "string",
    "MilitaryDivision": "string",
    "MilitaryCertificateEmissionDate": "2019-05-02T20:32:12.931Z",
    "MilitaryCertificateEmitterAgency": "2019-05-02T20:32:12.931Z",
    "MilitaryRegion": "string",
    "MilitarySituation": "string",
    "ElectoralCardEmitterState": "string",
    "BloodType": "string",
    "Image": "string",
    "NeighborhoodTypeCode": "15",
    "NaturalnessCode": "string",
    "NaturalisationDate": "2019-05-02T20:32:12.931Z",
    "DriversLicenseEmitterAgency": "string",
    "RneEmitterAgency": "string",
    "CountryId": "1",
    "DeceaseDate": "2019-05-02T20:32:12.931Z",
    "DeathCertificateNumber": "string",
    "NaturalisationGatehouse": "string",
    "BrazilConditionClassification": "string",
    "DriversLicenseFirstEmissionDate": "2019-05-02T20:32:12.931Z",
    "FirstJobYear": "15"
}


Dados utilizados da API

Por ser uma estrutura única para todos os produtos, há dados que existem em um produto (RM) e não existe no Protheus, desta forma cada produto utilizará os campos pertinentes aos seus ambientes.

Propriedade API RESTCAMPO PROTHEUSDESCRIÇÃOFormato
companyId
Informações de acesso ao sistema, campo contém informação do grupo de empresa
branchId
Informações de acesso ao sistema, campo compõe Empresa+Unidade de Negócio+ Filial
NameQG_NOMENome do Candidato"JOÃO PEREIRA  SILVA"
RegistryDateQG_DTCADData do Registro2019-05-02T20:32:12
DistrictQG_BAIRROBairroBARRA FUNDA
CityQG_MUNICIPMunicipSAO PAULO
StateQG_ESTADOEstadoSP
CepQG_CEPCep12345678
PhoneNumber1QG_FONEFone
PhoneNumber2QG_FONECELFone Celular
PhoneNumber3QG_FONECOMFone Comercial
identityNumberQG_RGRG123456789
CpfQG_CICCPF12345678900
WorkCardQG_NUMCPNum CP
WorkCardSerialNumberQG_SERCPSerie CP
WorkCardEmitterStateQG_UFCPUF CP
DriversLicenseQG_HABILITHabilitação
MilitaryDischargeCertificateQG_RESERVReservista
ElectoralCardQG_TITULOETitulo Eleitor
Street + NumberQG_ENDERECEndereço
ElectoralWard+ElectoralSectionQG_ZONASECZona Eleitoral
SexQG_SEXOSexoF - Feminino; M - Masculino.
MaritalStateQG_ESTCIVEstado Civil

C - Casado; D - Divorciado; M - União Estável; 
Q - Desquitado; S - Solteiro; V - Viúvo. 

HomeStateQG_NATURALNaturalidade - UFSP
NationalityQG_NACIONANacionalidade10
BirthQG_DTNASCData de Nascimento1900-01-01T01:01:01
"001" QG_SITUACSituac (Status Disponível)
EmailQG_EMAILEmailTESTE@TESTE.COM.BR
DisabledQG_DFISICODeficiente fisico

1- Sim; 2 - Não.

NaturalnessQG_MUNNASCNaturalidadeSAO PAULO
AreaOfInterestCode1QG_AREACódigo da área de interesse 1
HierarchyLevelCodeQG_NIVHIERCódigo do nível hierárquico
WorkExperienceTimeQG_TPEXPERTempo de experiência profissional
WageExpectationQG_PRETSALPretensão Salarial1000.00
ArrivalDateQG_ANOCHEGData de chegada no Brasil1900-01-01T01:01:01
ProfessionalSkillsResumeDescriptionQG_MEMO2Descrição do resumo de qualificações

Situações de Erros Tratados

O envio de dados inesperados nos parâmetros de entrada da API REST pode ocasionar alguns erros. Desta forma, foram criados alguns tratamentos de erros, listados abaixo, cada um com sua respectiva mensagem e solução.

Tratamento de erros de integração Protheus:


Mensagens de Pré-Validação

Erro

Mensagem

Solução

API RESPONSE

400

Erro genérico de operação.

Analisar disponibilidade de ambiente Protheus e revisar parametrização.

{
   "errorCode": 400,
   "errorMessage": "ERRO NA EXECUÇAO DA OPERAÇÃO."
}
400

Verificar se a propriedade (AreaOfInterestCode1)  possui cadastro no Protheus.

É necessário analisar o cadastro dentro do Protheus, para checagem se o código da área de interesse existe no Protheus, é possível checar pela própria tela de currículo.
{
   "errorCode": 400,
   "errorMessage": "DE-PARA DE EMPRESA E FILIAL NÃO ENCONTRADO NA BASE PARA O COMPANYID E BRANCHID"
}
400

Erro de sistema.

Verificar disponibilidade de ambiente e arquivo console.log
{
   "errorCode": 400,
  "errorMessage": "OCORREU UMA FALHA NO RETORNO DA INFORMAÇÃO."
}


OBS: Estas mensagens de validações serão retornadas sempre que algum campo passado que seja obrigatório ou que algum campo enviado tenha sua origem de dados em outra tabela e não seja localizado na mesma, vale lembrar que são apenas exemplos de mensagens de erros e podendo variar o nome da propriedade enviada.

Parâmetros de Entrada GET:

Parâmetro

Valor de Exemplo

Obrigatório

Tipo

Valor Default

Descrição
authorization usuario:senhaSim

header


autenticação é importante para o funcionamento correto da API em casos de ambientes com autenticação Http Basic.
pagerequest da apiSimquery1


pageSizerequest da apiSimquery2000O Limite 
candidatesIdsT1|D RJ|123456789Simquery""Composição da string a ser enviada, deve ser ser composta por "GRUPO DE EMPRESA|QG_FILIAL|QG_CIC", caso tenha mais de um candidato a ser consultado, se faz necessário adicionar "," e colocar o novo bloco. ex: "GRUPO DE EMPRESA|QG_FILIAL|QG_CIC,GRUPO DE EMPRESA|QG_FILIAL|QG_CIC"

Parâmetros e Chamada do Método:

Para a realização de testes foi utilizado a ferramenta SOAP UI e após a configuração do server protheus a API Rest, a  requisição deverá ser semelhante a imagem abaixo:

{protocolo}://{host}/{api}//rh/v2/candidates

Response da API:

Exemplo de Request da API
{
	"companyId":"T1",
	"branchId":"D MG 01",
    "id": "000001",
    "Name": "JOÃO PEREIRA DA SILVAI",
    "Birth": "01/01/1990",
    "HomeState": "MG",
    "Naturalness": "Belo Horizonte",
    "NickName": "Jão",
    "Sex": "M",
    "Nationality": "10",
    "EducationalLevel": "9",
    "Street": "Rua Mata Atlantica",
    "Number": "333",
    "District": "Planalto",
    "State": "MG",
    "City": "Belo Horizonte",
    "Cep": "30100020",
    "Country": "Brasil",
    "ProfessionalRegistrationNumber": "Reg-00098",
    "Cpf": "51427362653",
    "ImageId": 844,
    "PhoneNumber1": "4613636",
    "PhoneNumber2": "4613636",
    "identityNumber": "M 267392",
    "IdentityNumberEmitterState": "MG",
    "IdentityNumberEmitterAgency": "SSP",
    "IdentityNumberEmissionDate": "1993-04-25T00:00:00",
    "ElectoralCard": "123.334",
    "ElectoralWard": "0012",
    "ElectoralSection": "0006",
    "WorkCard": "015116",
    "WorkCardSerialNumber": "00001",
    "WorkCardEmitterState": "MG",
    "WorkCardEmissionDate": "1993-03-01T00:00:00",
    "Nit": 0,
    "DriversLicense": "13.344.543",
    "DriversLicenseType": "A",
    "DriversLicenseExpirationDate": "1997-02-05T00:00:00",
    "MilitaryDischargeCertificate": "12856945678",
    "MilitaryGrade": "CDI",
    "BrazilConsort": 0,
    "Naturalized": 0,
    "BrazilianChildren": 0,
    "BrazilianChildrenNumber": "2",
    "Email": "teste@totvs.com.br",
    "PreviousTrainingInvestment": "2300.00",
    "ShadeRace": "0",
    "Disabled": 0,
    "UserCode": "simone",
    "PhoneNumber3": "21229000",
    "Company": "RM SISTEMAS S.A",
    "OccupationCode": "10",
    "Rehabilitated": 0,
    "Smoker": 0,
    "AdjustsImageSize": 0,
    "DeafPerson": 0,
    "MutePerson": 0,
    "BlindPerson": 0,
    "MentallyImpairedPerson": 0,
    "CurriculumApprovalDate": "2005-04-01T09:36:02.66",
    "Student": 1,
    "Teacher": 1,
    "Candidate": 1,
    "BibliosUser": 1,
    "Employee": 1,
    "FormerEmployee": 0,
    "IntellectualImpairedPerson": 0,
    "Deceased": 0,
    "Age": 53,
    "RegistryDate": "2019-05-02T20:32:12.931Z",
    "WageExpectation": "1111.32",
    "AreaOfInterestCode1": "15",
    "AreaOfInterestCode2": "15",
    "WageExpectationTradable": "1",
    "azerienceTime": "15",
    "WorkExperienceTimeArea1": "15",
    "WorkExperienceTimeArea2": "15",
    "ContraIndicated": "1",
    "ContraindicationReason": "string",
    "Available": "1",
    "FormOfRecruitment": "string",
    "ResumeSkillsId": "15",
    "HierarchyLevelCode": "15",
    "ProfessionalProfileDescription": "string",
    "AreaOfInterestDescription1": "string",
    "AreaOfInterestDescription2": "string",
    "HierarchyLevelDescription": "string",
    "ProfessionalSkillsResumeDescription": "string",
    "Employee1": "string",
    "PersonalEmail": "string",
    "MaritalState": "string",
    "Complement": "string",
    "ArrivalDate": "2019-05-02T20:32:12.931Z",
    "LetterModel19": "string",
    "Rne": "string",
    "ImmigrationDecree": "string",
    "RneExpirationDate": "2019-05-02T20:32:12.931Z",
    "WorkCardExpirationDate": "2019-05-02T20:32:12.931Z",
    "VisaType": "string",
    "PassportNumber": "string",
    "NativeCountry": "string",
    "PassportExpirationDate": "2019-05-02T20:32:12.931Z",
    "AccessibilityFeaturesForJobLocal": "string",
    "MilitaryDivision": "string",
    "MilitaryCertificateEmissionDate": "2019-05-02T20:32:12.931Z",
    "MilitaryCertificateEmitterAgency": "2019-05-02T20:32:12.931Z",
    "MilitaryRegion": "string",
    "MilitarySituation": "string",
    "ElectoralCardEmitterState": "string",
    "BloodType": "string",
    "Image": "string",
    "NeighborhoodTypeCode": "15",
    "NaturalnessCode": "string",
    "NaturalisationDate": "2019-05-02T20:32:12.931Z",
    "DriversLicenseEmitterAgency": "string",
    "RneEmitterAgency": "string",
    "CountryId": "1",
    "DeceaseDate": "2019-05-02T20:32:12.931Z",
    "DeathCertificateNumber": "string",
    "NaturalisationGatehouse": "string",
    "BrazilConditionClassification": "string",
    "DriversLicenseFirstEmissionDate": "2019-05-02T20:32:12.931Z",
    "FirstJobYear": "15"
}


Dados utilizados da API

Por ser uma estrutura única para todos os produtos, há dados que existem em um produto (RM) e não existe no Protheus, desta forma cada produto utilizará os campos pertinentes aos seus ambientes.

Propriedade API RESTCAMPO PROTHEUSDESCRIÇÃOFormato
companyId
Informações de acesso ao sistema, campo contém informação do grupo de empresa
branchId
Informações de acesso ao sistema, campo compõe Empresa+Unidade de Negócio+ Filial
NameQG_NOMENome do Candidato"JOÃO PEREIRA  SILVA"
RegistryDateQG_DTCADData do Registro2019-05-02T20:32:12
DistrictQG_BAIRROBairroBARRA FUNDA
CityQG_MUNICIPMunicipSAO PAULO
StateQG_ESTADOEstadoSP
CepQG_CEPCep12345678
PhoneNumber1QG_FONEFone
PhoneNumber2QG_FONECELFone Celular
PhoneNumber3QG_FONECOMFone Comercial
identityNumberQG_RGRG123456789
CpfQG_CICCPF12345678900
WorkCardQG_NUMCPNum CP
WorkCardSerialNumberQG_SERCPSerie CP
WorkCardEmitterStateQG_UFCPUF CP
DriversLicenseQG_HABILITHabilitação
MilitaryDischargeCertificateQG_RESERVReservista
ElectoralCardQG_TITULOETitulo Eleitor
Street + NumberQG_ENDERECEndereço
ElectoralWard+ElectoralSectionQG_ZONASECZona Eleitoral
SexQG_SEXOSexoF - Feminino; M - Masculino.
MaritalStateQG_ESTCIVEstado Civil

C - Casado; D - Divorciado; M - União Estável; 
Q - Desquitado; S - Solteiro; V - Viúvo. 

HomeStateQG_NATURALNaturalidade - UFSP
NationalityQG_NACIONANacionalidade10
BirthQG_DTNASCData de Nascimento1900-01-01T01:01:01
"001" QG_SITUACSituac (Status Disponível)
EmailQG_EMAILEmailTESTE@TESTE.COM.BR
DisabledQG_DFISICODeficiente fisico

1- Sim; 2 - Não.

NaturalnessQG_MUNNASCNaturalidadeSAO PAULO
AreaOfInterestCode1QG_AREACódigo da área de interesse 1
HierarchyLevelCodeQG_NIVHIERCódigo do nível hierárquico
WorkExperienceTimeQG_TPEXPERTempo de experiência profissional
WageExpectationQG_PRETSALPretensão Salarial1000.00
ArrivalDateQG_ANOCHEGData de chegada no Brasil1900-01-01T01:01:01
ProfessionalSkillsResumeDescriptionQG_MEMO2Descrição do resumo de qualificações

Situações de Erros Tratados

O envio de dados inesperados nos parâmetros de entrada da API REST pode ocasionar alguns erros. Desta forma, foram criados alguns tratamentos de erros, listados abaixo, cada um com sua respectiva mensagem e solução.

Tratamento de erros de integração Protheus:


Mensagens de Pré-Validação

Erro

Mensagem

Solução

API RESPONSE

400

Problema com a parametrização para abertura de ambiente.

Revisar a composição do parâmetro de candidatesIds

{
   "errorCode": 400,
   "errorMessage":  ERRO AO PREPARAR O AMBIENTE COM A EMPRESA E FILIAL INFORMADOS!.\r\n"
}
400

Problema com parametrização para abertura de ambiente.

Revisar a composição do parâmetro de candidatesIds
{
   "errorCode": 400,
   "errorMessage": ""DE-PARA DE EMPRESA E FILIAL NÃO ENCONTRADO NA BASE PARA O COMPANYID E BRANCHID".\r\n"
}
400

Possíveis falhas genéricas no meio da busca por candidatos

Revisar parâmetros de requisição e se o ambiente protheus está disponível.
{
   "errorCode": 400,
  "errorMessage": " "ERRO AO BUSCAR DADOS DO CURRÍCULO.\r\n"
}


OBS: Estas mensagens de validações serão retornadas sempre que algum campo passado que seja obrigatório ou que algum campo enviado tenha sua origem de dados em outra tabela e não seja localizado na mesma, vale lembrar que são apenas exemplos de mensagens de erros e podendo variar o nome da propriedade enviada.

Parâmetros de Entrada DELETE:

Parâmetro

Valor de Exemplo

Obrigatório

Tipo

Valor Default

Descrição
authorization usuario:senhaSim

header

""autenticação é importante para o funcionamento correto da API em casos de ambientes com autenticação Http Basic.
candidatesidT1|D RJ|123456789Simquery""

Composição da string a ser enviada, deve ser ser composta por "GRUPO DE EMPRESA|QG_FILIAL|QG_CIC".

Parâmetros e Chamada do Método:

Para a realização de testes foi utilizado a ferramenta SOAP UI e após a configuração do server protheus a API Rest, a  requisição deverá ser semelhante a imagem abaixo:

{protocolo}://{host}/{api}//rh/v1/candidates

Situações de Erros Tratados

O envio de dados inesperados nos parâmetros de entrada da API REST pode ocasionar alguns erros. Desta forma, foram criados alguns tratamentos de erros, listados abaixo, cada um com sua respectiva mensagem e solução.

Tratamento de erros de integração Protheus:


Mensagens de Pré-Validação

Erro

Mensagem

Solução

API RESPONSE

400

Erro genérico de ambiente

Verificar parametrização enviada via api e se o ambiente está no ar. 

{
   "errorCode": 400,
   "errorMessage": "ERRO NA EXECUÇAO DA OPERAÇÃO."
}
400

Validação de empresa e filial

Verificar a parametrização de empresa e filial no parâmetro candidatesid.
{
   "errorCode": 400,
   "errorMessage": "DE-PARA DE EMPRESA E FILIAL NÃO ENCONTRADO NA BASE PARA O COMPANYID". STR0014: "E BRANCHID"
}
400

Falha no meio do processo de exclusão.

verificar console.log, dados de empresa e filial.
{
   "errorCode": 400,
  "errorMessage":"OCORREU UMA FALHA NO RETORNO DA INFORMAÇÃO."
}


OBS: Estas mensagens de validações serão retornadas sempre que algum campo passado que seja obrigatório ou que algum campo enviado tenha sua origem de dados em outra tabela e não seja localizado na mesma, vale lembrar que são apenas exemplos de mensagens de erros e podendo variar o nome da propriedade enviada.


Checklist de suporte da aplicação

Itens a serem verificados durante o atendimento:

  • Verificar se os pré-requisitos foram atendidos para a chamada da API;
  • Verificar se na chamada da API o EndPoint, o nome do serviço e todos os campos obrigatórios foram informados;
  • Verificar se o retorno da API apresenta algum erro tratado (códigos e mensagens de erro citados neste documento) e consultar a solução na mesma tabela que descreve o erro;
  • Em caso de erro não tratado, verificar se possui alguma informação de banco de dados, conexão com o servidor ou algo que possa identificar a origem do problema.


Anexos