Desenvolver a API - Integrador SST (v2)

Esta documentação é destinada aos desenvolvedores do prestador SST que desejam criar uma API para fazer a integração e comunicação entre o sistema do prestador e o Integrador SST da Senior, e que também desejam acessar ao ambiente de homologação e testes.

Você precisará desenvolver no sistema do prestador os web services (REST) responsáveis pela comunicação com o sistema da Senior. Sua API será responsável por integrar as pendências de envio das informações de colaboradores e dos eventos de SST do eSocial.

Imagem

Para testar os serviços desenvolvidos você pode usar qualquer API Client de sua preferência (esta documentação utiliza o Postman para fins de exemplo).

Acesse a documentação de conceitos da API para obter informações complementares, ou continue nesta página para ver a documentação de referência dos endpoints.


Dados dos colaboradores

Passos para a integração:

Passos para a integração de dados dos colaboradores: 1) Autenticação; 2) Buscar pendências de integração; 3) Enviar resposta.

Passo 1 - Autenticação

O primeiro passo é implementar a autenticação com a plataforma de homologação da Senior. Isso é feito pelo serviço loginWithKey, responsável por realizar o login na plataforma com chave e segredo informados pelo usuário.

Para obter a chave e o segredo que serão usados na sua implementação entre em contato com a Senior pelo e-mail: [integradorsst.devs@senior.com.br](/integrador-sst/desenvolvedores/mailto:integradorsst.devs@senior.com.br?subject=Integrador SST - Contato via Portal de Documentação). Este é um canal de comunicação voltado para desenvolvedores, respondendo exclusivamente questões de caráter técnico e de arquitetura do Integrador SST.

Web service disponibilizado na plataforma da Senior: loginWithKey

[ POST ]
https://platform-homologx.senior.com.br:8243/t/senior.com.br/bridge/1.0/anonymous/rest/platform/authentication/actions/loginWithKey

Estrutura das credenciais:

    {
            "accessKey": "XXX",
            "secret": "XXX",
            "tenantName": "XXX"
    }
Exemplo:

Execução no API Client:

Imagem
Imagem
Imagem

Passo 2 - Obter as pendências de integração da plataforma da Senior

Cada pendência de integração tem um motivo para ser gerada. O motivo da pendência determina o tipo de integração.

O tipo de integração é identificado pelo parâmetro integrationType, presente na resposta ou no envio de algumas requisições.

Para saber quais tipos de integração existem e qual a ação esperada do sistema do prestador SST para cada tipo, acesse a documentação de tipos de integração (integrationType).

Existem duas maneiras de obter as pendências de integração da plataforma da Senior. Você pode escolher uma das opções descritas a seguir:

2.1) Buscar as pendências periodicamente (opção 1)

A primeira opção é fazer com que o sistema do prestador busque de tempo em tempo, no sistema da Senior, as pendências que ainda não foram integradas.

É preciso implementar a busca dos registros da plataforma senior X com um intervalo mínimo de 3 minutos entre cada chamada do web service.

Web service disponibilizado na plataforma da Senior: retrieveSentIntegrationsQuery

[ POST ]
https://platform-homologx.senior.com.br/t/senior.com.br/bridge/1.0/rest/hcm/esocial4integration/queries/retrieveSentIntegrationsQuery

Parâmetros de entrada

Cabeçalho (Header):

ParâmetroValor
Content-Typeapplication/json
AuthorizationBearer Token

Corpo (Body):

ParâmetroTipoObrigatórioDescriçãoValores permitidos
paginationGrupo de parâmetros com a definição da paginação dos registros - Opcional
pagination.currentNuméricoSimPágina atual de registros
pagination.sizeNuméricoSimQuantidade de registros por página
pagination.orderByGrupo de parâmetros com a definição da ordenação - Opcional
pagination.orderBy.fieldAlfanuméricoSimNome do campo pelo qual os registros serão ordenados
pagination.orderBy.directionEnumeraçãoNãoOrientação da ordenação

ASC (Ascendente)

DESC (Descendente)

Exemplo JSON:

    {
        "pagination": {
                "current": 0,
                "size": 10,
                "orderBy": [
                    {
                            "field": "receiptDate",
                            "direction": "ASC"
                    }
                ]
        }
    }

Resposta

CodeDescription
200
    {
        "totalElements": 3,
        "totalPages": 5,
        "contents": [
                {
                    "id": "b5640edc-49aa-4579-a8f0-34818265f3f8",
                    "externalId": "926D9F8A83A34AC898A8CB27C6D38A5E",
                    "externalHistoricId": "",
                    "operationType": "INSERT",
                    "employee": {
                            "id": "94698ef5-11b0-4c5a-a593-c2212039ab68",
                            "externalId": "926D9F8A83A34AC898A8CB27C6D38A5E",
                            "employeeType": "EMPLOYEE",
                            "code": 3,
                            "name": "Maria Eduarda Freitas",
                            "cpfNumber": "37874381068",
                            "nisNumber": "12152212837",
                            "birthday": "1974-04-03",
                            "hireDate": "1998-02-03",
                            "maritalStatusType": "MARRIED",
                            "genderType": "FEMALE",
                            "situationType": "WORKING",
                            "contractType": "EMPLOYEE",
                            "eSocialCategory": {
                                "id": "bb02db50-16cc-4d80-902c-50084945e74f",
                                "code": "Category_101",
                                "dateWhen": "1998-02-03",
                                "_discriminator": "eSocialCategory"
                            },
                            "isDeficient": false,
                            "company": {
                                "id": "ccb03e9d-40c2-4c6a-ad99-0b0bd0d63abf",
                                "code": 1,
                                "name": "Demonstra Ind.& Com. Têxtil S/A",
                                "_discriminator": "company"
                            },
                            "companyBranch": {
                                "id": "6581bd86-edd5-4557-8dea-7baf3b3a852e",
                                "code": 2,
                                "name": "Demonstra S/A - Filial RJ",
                                "companyBranchName": "Filial RJ",
                                "subscriptionType": "CNPJ",
                                "subscriptionNumber": "12345678010239",
                                "dateWhen": "1998-02-03",
                                "_discriminator": "companyBranch"
                            },
                            "department": {
                                "id": "b98bc6af-4c2a-4be8-bc82-093f9bbe3c63",
                                "code": "1.02.01",
                                "structureCode": 1,
                                "name": "Recursos Humanos",
                                "dateWhen": "1998-02-03",
                                "_discriminator": "department"
                            },
                            "jobPosition": {
                                "id": "250b9566-34c8-4b3f-abd6-338f32dc630f",
                                "code": "2",
                                "cboCode": "142210",
                                "name": "Gerente Recursos Humanos",
                                "dateWhen": "1998-02-03",
                                "_discriminator": "jobPosition"
                            },
                            "shift": {
                                "id": "0349c4ba-f24e-4209-b619-c78d06900cf6",
                                "code": 2,
                                "name": "08:00 1200-1330 1800/Móvel",
                                "dateWhen": "1998-02-03",
                                "_discriminator": "shift"
                            },
                            "workstation": {
                                "id": "84df96d1-df1a-4830-9b3e-9dcdc89cc4fd",
                                "code": "ADM006",
                                "structureCode": 2,
                                "name": "Gerente Recursos Humanos",
                                "dateWhen": "2011-04-01",
                                "_discriminator": "workstation"
                            },
                            "deficiencies": [],
                            "ctpsNumber": "000546761",
                            "ctpsSerie": "216",
                            "ctpsIssuanceDate": "1990-01-01",
                            "ctpsSerieDigit": "",
                            "ctpsState": "SC",
                            "rgNumber": "99999",
                            "rgIssuer": "SSP",
                            "rgState": "SC",
                            "rgIssuanceDate": "1990-01-01",
                            "numberContractSameHireDate": 1,
                            "workEnvironment": {
                                "id": "43184710-b69a-4d97-88f3-1e57fe474247",
                                "location": "THIRD",
                                "code": "17",
                                "name": "Ambiente CAEPF",
                                "subscriptionType": "CAEPF",
                                "subscriptionNumber": "12345678911212",
                                "dateWhen": "2023-02-01",
                                "_discriminator": "workEnvironment"
                            },
                            "_discriminator": "employee",
                            "previousEmployeeType": "employee",
                            "previousCode": 0
                    },
                    "statusType": "SENT_TO_PROVIDER",
                    "integrationType": "HISTORICAL_COMPANY",
                    "receiptDate": "2019-11-28T12:46:12.919Z",
                    "sendDate": "2019-11-28T12:48:14.19Z",
                    "scheduledDate": "2019-11-28",
                    "integrationMessage": "2019-11-28T12:46:13.491636801 - INITIAL_LOAD - IN_ANALYSIS\n",
                    "companyCode": 1,
                    "companyName": "Demonstra Ind.& Com. Têxtil S/A",
                    "companyBranchCode": 2,
                    "companyBranchName": "Demonstra S/A - Filial RJ",
                    "branchName": "Filial RJ",
                    "employeeCode": 3,
                    "eSocialRegistration": "",
                    "cpfNumber": "37874381068",
                    "employeeName": "Maria Eduarda Freitas",
                    "providerCompanyIdentification": "100",
                    "providerEmployeeIdentification": "123b",
                    "providerPreviousEmployeeIdentification": "123a",
                    "integrationSequence": 1,
                    "previewSendDate": "2019-11-28T12:48:14.19Z",
                    "_discriminator": "integration"
                },
                {
                    "id": "aefb9820-ac2e-44c9-8d53-4579946ca20e",
                    "externalId": "A4EE1196F61E414394EEBBB4771B6566",
                    "externalHistoricId": "",
                    "operationType": "INSERT",
                    "employee": {
                            "id": "e45eda70-5283-4f10-8452-2d4e8d631bb7",
                            "externalId": "A4EE1196F61E414394EEBBB4771B6566",
                            "employeeType": "EMPLOYEE",
                            "code": 28,
                            "name": "Carolina de Abreu",
                            "cpfNumber": "49064495068",
                            "nisNumber": "12199266453",
                            "birthday": "1972-02-27",
                            "hireDate": "1998-03-05",
                            "maritalStatusType": "MARRIED",
                            "genderType": "FEMALE",
                            "situationType": "WORKING",
                            "contractType": "EMPLOYEE",
                            "eSocialCategory": {
                                "id": "9d15c38e-5a98-4b29-a1c9-0e154509f1ba",
                                "code": "Category_101",
                                "dateWhen": "1998-03-05",
                                "_discriminator": "eSocialCategory"
                            },
                            "isDeficient": false,
                            "company": {
                                "id": "0c79c9c8-7a08-48bb-947b-e63096f018b5",
                                "code": 1,
                                "name": "Demonstra Ind.& Com. Têxtil S/A",
                                "_discriminator": "company"
                            },
                            "companyBranch": {
                                "id": "9020573b-4ea7-4f29-b81a-f45295635aa7",
                                "code": 2,
                                "name": "Demonstra S/A - Filial RJ",
                                "companyBranchName": "Filial RJ",
                                "subscriptionType": "CNPJ",
                                "subscriptionNumber": "12345678010239",
                                "dateWhen": "1998-03-05",
                                "_discriminator": "companyBranch"
                            },
                            "department": {
                                "id": "4a0fbfcf-abad-4986-b36e-0c82cf1d8185",
                                "code": "1.03.01.04",
                                "structureCode": 1,
                                "name": "Costura",
                                "dateWhen": "1998-03-05",
                                "_discriminator": "department"
                            },
                            "jobPosition": {
                                "id": "13012d85-e082-4cf7-bf2e-6e0339c0794a",
                                "code": "36",
                                "cboCode": "760505",
                                "name": "Supervisora de Costura",
                                "dateWhen": "1998-03-05",
                                "_discriminator": "jobPosition"
                            },
                            "shift": {
                                "id": "22229ce2-ed5c-4180-92c5-5d3ab57c37b6",
                                "code": 8,
                                "name": "14:00 1800-1900 22:00/2.Turno",
                                "dateWhen": "2002-08-26",
                                "_discriminator": "shift"
                            },
                            "workstation": {
                                "id": "3c5fb778-5fc4-4d85-92f1-e83742603f99",
                                "code": "PRO007",
                                "structureCode": 2,
                                "name": "Supervisora Costura",
                                "dateWhen": "2011-04-01",
                                "_discriminator": "workstation"
                            },
                            "deficiencies": [],
                            "ctpsNumber": "000056464",
                            "ctpsSerie": "4654",
                            "ctpsIssuanceDate": "1990-01-01",
                            "ctpsSerieDigit": "",
                            "ctpsState": "SC",
                            "rgNumber": "99999",
                            "rgIssuer": "SSP",
                            "rgState": "SC",
                            "rgIssuanceDate": "2010-01-01",
                            "numberContractSameHireDate": 1,
                            "_discriminator": "employee",
                            "previousEmployeeType": "employee",
                            "previousCode": 0
                    },
                    "statusType": "SENT_TO_PROVIDER",
                    "integrationType": "HISTORICAL_COMPANY",
                    "receiptDate": "2019-11-28T12:46:13.519Z",
                    "sendDate": "2019-11-28T12:48:15.228Z",
                    "scheduledDate": "2019-11-28",
                    "integrationMessage": "2019-11-28T12:46:14.467435466 - INITIAL_LOAD - IN_ANALYSIS\n",
                    "companyCode": 1,
                    "companyName": "Demonstra Ind.& Com. Têxtil S/A",
                    "companyBranchCode": 2,
                    "companyBranchName": "Demonstra S/A - Filial RJ",
                    "branchName": "Filial RJ",
                    "employeeCode": 28,
                    "eSocialRegistration": "",
                    "cpfNumber": "49064495068",
                    "employeeName": "Carolina de Abreu",
                    "providerCompanyIdentification": "100",
                    "providerEmployeeIdentification": "123d",
                    "providerPreviousEmployeeIdentification": "123c",
                    "integrationSequence": 1,
                    "previewSendDate": "2019-11-28T12:48:15.228Z",
                    "_discriminator": "integration"
                },
                {
                    "id": "4e0adff6-fd3a-4720-8895-a2d214b286de",
                    "externalId": "CF6EA792C3E34E699F9665C28EA3BE50",
                    "externalHistoricId": "",
                    "operationType": "INSERT",
                    "employee": {
                            "id": "1302f000-1bb2-4402-b91f-59086d50a128",
                            "externalId": "CF6EA792C3E34E699F9665C28EA3BE50",
                            "employeeType": "EMPLOYEE",
                            "code": 11,
                            "name": "Roberto Mattos",
                            "cpfNumber": "22157735020",
                            "nisNumber": "10256524502",
                            "birthday": "1969-05-17",
                            "hireDate": "1999-01-05",
                            "maritalStatusType": "MARRIED",
                            "genderType": "MALE",
                            "situationType": "AWAY",
                            "contractType": "EMPLOYEE",
                            "eSocialCategory": {
                                "id": "5da1a1c4-faf3-4a08-857d-517285b27799",
                                "code": "Category_101",
                                "dateWhen": "1999-01-05",
                                "_discriminator": "eSocialCategory"
                            },
                            "isDeficient": false,
                            "company": {
                                "id": "6033b282-5f26-460f-af85-8589eb06bd6c",
                                "code": 1,
                                "name": "Demonstra Ind.& Com. Têxtil S/A",
                                "_discriminator": "company"
                            },
                            "companyBranch": {
                                "id": "9fd691f7-0706-405b-b3b7-327aa2cadcbf",
                                "code": 2,
                                "name": "Demonstra S/A - Filial RJ",
                                "companyBranchName": "Filial RJ",
                                "subscriptionType": "CNPJ",
                                "subscriptionNumber": "12345678010239",
                                "dateWhen": "1999-01-05",
                                "_discriminator": "companyBranch"
                            },
                            "department": {
                                "id": "9c29a5b0-df57-48c1-be4f-331da5071e9c",
                                "code": "2.01.01",
                                "structureCode": 1,
                                "name": "Vendas",
                                "dateWhen": "1999-01-05",
                                "_discriminator": "department"
                            },
                            "jobPosition": {
                                "id": "05fa09e7-a37e-4f71-a7d7-27b387a96398",
                                "code": "3",
                                "cboCode": "521105",
                                "name": "Vendedor",
                                "dateWhen": "1999-01-05",
                                "_discriminator": "jobPosition"
                            },
                            "shift": {
                                "id": "79b0224d-97c1-470b-8223-fa86e376b96f",
                                "code": 5,
                                "name": "08:00 1200-1330 1800/Móvel-Ref",
                                "dateWhen": "2002-08-26",
                                "_discriminator": "shift"
                            },
                            "workstation": {
                                "id": "dc67daeb-0b9d-415a-b453-857f7eee1f5c",
                                "code": "ADM022",
                                "structureCode": 2,
                                "name": "Vendedores",
                                "dateWhen": "2011-04-01",
                                "_discriminator": "workstation"
                            },
                            "reasonLeave": {
                                "id": "1e7b2c7a-3fe1-4974-9e12-39d760e80266",
                                "code": 3,
                                "name": "Auxílio Doença",
                                "startDate": "2017-12-20T00:00:00Z",
                                "_discriminator": "reasonLeave"
                            },
                            "deficiencies": [],
                            "ctpsNumber": "000654232",
                            "ctpsSerie": "4564",
                            "ctpsIssuanceDate": "1990-01-01",
                            "ctpsSerieDigit": "",
                            "ctpsState": "SC",
                            "rgNumber": "99999",
                            "rgIssuer": "SSP",
                            "rgState": "SC",
                            "rgIssuanceDate": "1990-01-01",
                            "numberContractSameHireDate": 1,
                            "_discriminator": "employee",
                            "previousEmployeeType": "employee",
                            "previousCode": 0
                    },
                    "statusType": "SENT_TO_PROVIDER",
                    "integrationType": "HISTORICAL_COMPANY",
                    "receiptDate": "2019-11-28T12:46:14.495Z",
                    "sendDate": "2019-11-28T12:48:12.277Z",
                    "scheduledDate": "2019-11-28",
                    "integrationMessage": "2019-11-28T12:46:15.502259404 - INITIAL_LOAD - IN_ANALYSIS\n",
                    "companyCode": 1,
                    "companyName": "Demonstra Ind.& Com. Têxtil S/A",
                    "companyBranchCode": 2,
                    "companyBranchName": "Demonstra S/A - Filial RJ",
                    "branchName": "Filial RJ",
                    "employeeCode": 11,
                    "eSocialRegistration": "",
                    "cpfNumber": "22157735020",
                    "employeeName": "Roberto Mattos",
                    "providerCompanyIdentification": "100",
                    "providerEmployeeIdentification": "123f",
                    "providerPreviousEmployeeIdentification": "123e",
                    "integrationSequence": 1,
                    "previewSendDate": "2019-11-28T12:48:12.277Z",
                    "_discriminator": "integration"
                }
        ]
    }

Notas

  • O campo numberContractSameHireDate retorna o número de contratos que o colaborador tem. Isso define como o sistema do prestador deve tratar a ocorrência de múltiplos contratos, conforme respondido na página de Perguntas frequentes.
  • Para saber mais sobre as possíveis respostas dessa API, acesse a documentação do serviço esocial4integration no Portal de APIs da Senior e procure pela API retrieveSentIntegrationsQuery.
default

Error response

Valor de exemplo:

    {
        "message": "string",
        "reason": "BAD_REQUEST"
    }

Observação

Se a integração com o prestador não estiver ativa nas configurações do Integrador SST, a resposta do web service não retornará nenhuma pendência de integração.

Exemplo:

Execução no API Client:

Imagem
Imagem
Imagem

2.2) Receber as pendências de integração em tempo real (opção 2)

A segunda opção é receber as pendências de integração em tempo real. Para isso é necessário seguir esses passos:

Implemente este serviço para receber as pendências de integração de dados dos colaboradores a medida em que ocorrerem admissões, movimentações ou desligamentos no sistema da Senior.

Ao receber a integração dos dados, o sistema do prestador deve enviar uma confirmação do status da integração (Passo 3). Caso essa confirmação não seja enviada, o sistema da Senior fará mais três tentativas de envio da pendência de integração ao prestador, com intervalo de 10 minutos entre cada tentativa.

Web service disponibilizado no prestador SST: pendency

[ POST ]
[url-prestador-sst]/integration/pendency

Exemplo: http://www.prestador-sst.com.br/integration/pendency

Parâmetros

A pendência de integração é enviada pela plataforma da Senior com os parâmetros abaixo:

Cabeçalho (Header):

ParâmetroValor
Content-Typeapplication/json
AuthorizationBearer Token

Corpo (Body):

ParâmetroTipoObrigatórioDescriçãoValores permitidos
integration.idAlfanuméricoSimIdentificador único da pendência de integração na API
integration.externalIdAlfanuméricoSimIdentificador da pendência de integração entre os sistemas
integration.externalHistoricIdAlfanuméricoNãoIdentificador anterior da pendência de integração entre os sistemas
integration.operationTypeEnumeraçãoSimTipo de operação

INSERT
UPDATE
DELETE

integration.statusTypeEnumeraçãoNãoStatus da pendência de integração

SENT_TO_PROVIDER (Pendência enviada ao prestador SST)
ON_PROVIDER (Pendência recebida com sucesso pelo prestador SST)

integration.integrationTypeEnumeraçãoSim

Motivo da integração

Para saber mais sobre os tipos de integração deste campo, confira a documentação:

NEW_EMPLOYEE (Novo colaborador)
EMPLOYEE_CHANGE (Alteração do colaborador)
DISMISSAL (Demissão do colaborador)
HISTORICAL_COST_CENTER (Histórico de centro de custo)
HISTORICAL_DEPARTMENT (Histórico de departamento)
HISTORICAL_ESOCIAL_CATEGORY (Histórico de categoria eSocial)
HISTORICAL_JOB_POSITION (Histórico de cargo)
HISTORICAL_WORKSTATION (Histórico de posto de trabalho)
HISTORICAL_COMPANY_BRANCH (Histórico de filial)
HISTORICAL_COMPANY (Histórico de empresa)
HISTORICAL_WORKSHIFT (Histórico de escala)
HISTORICAL_LEAVE (Histórico de afastamento)
HISTORICAL_SALARY_PREMIUM (Histórico de informações adicionais)
HISTORICAL_WORKENVIRONMENT (Histórico de ambiente de trabalho)
EMPLOYEE_ESOCIAL_REGISTRATION (Alteração da matrícula eSocial)
INITIAL_LOAD (Carga inicial)
REINTEGRATION (Reintegração do colaborador)

integration.receiptDateDataSimData de criação da pendência de integração
integration.previewSendDateDataSimData prevista para envio da pendência de integração
integration.scheduledDateDataSimData do agendamento para envio da pendência de integração
integration.sendDateDataSimData de envio da pendência de integração
integration.providerCompanyIdentificationAlfanuméricoSimIdentificação da empresa no prestador SST
integration.providerEmployeeIdentificationAlfanuméricoNãoIdentificação do colaborador no prestador SST
integration.providerPreviousCompanyIdentificationAlfanuméricoNãoIdentificação da empresa anterior no prestador SST (enviada caso o colaborador tenha alguma transferência entre empresas no seu histórico)
integration.integrationSequenceNuméricoNãoNúmero sequencial da integração
integration.cancelationReasonAlfanuméricoNãoMotivo do cancelamento da pendência de integração
integration.integrationMessageAlfanuméricoNãoObservações da integração
integration.stackTraceAlfanuméricoNãoDetalhes de eventuais erros
integration.employeeGrupo de parâmetros com dados do colaborador - Obrigatório
integration.employee.idAlfanuméricoSimIdentificador do colaborador para o sistema de folha
integration.employee.externalIdAlfanuméricoSimIdentificador do colaborador para integrações entre os sistemas
integration.employee.employeeTypeEnumeraçãoSimTipo do colaboradorEMPLOYEE (Colaborador)
THIRD (Terceiro)
PARTNER (Parceiro)
integration.employee.codeAlfanuméricoSimCódigo do cadastro do colaborador no sistema de folha
integration.employee.eSocialRegistrationAlfanuméricoNão Matrícula do eSocial
integration.employee.nameAlfanuméricoSimNome do colaborador
integration.employee.socialNameAlfanuméricoNão Nome Social do colaborador
integration.employee.cpfNumberNuméricoNãoNúmero do CPF
integration.employee.nisNumberNuméricoNãoNúmero do NIS
integration.employee.birthdayDataNãoData de nascimento
integration.employee.hireDateDataNãoData de admissão
integration.employee.dismissalDateDataNãoData de demissão
integration.employee.maritalStatusTypeEnumeraçãoNãoEstado civilSINGLE (Solteiro)
MARRIED (Casado)
DIVORCED (Divorciado)
WIDOWER (Viúvo)
SEPARATED (Separado)
STABLE_UNION (União estável)
OTHER (Outro tipo de estado civil)
CONCUBINAGE (Concubinato)
integration.employee.genderTypeEnumeraçãoNãoGênero do colaboradorMALE (Masculino)
FEMALE (Feminino)
integration.employee.situationTypeEnumeraçãoSimSituação do colaboradorPRE_ADMISSION (Registro de pré-admissão)
PRE_ADMISSION_CANCELED (Pré-admissão cancelada)
WORKING (Trabalhando)
VACATION (Férias)
FIRED (Demitido)
AWAY (Afastado)
LICENSE (Licença)
integration.employee.contractTypeEnumeraçãoNãoTipo do contratoEMPLOYEE (Empregado)
MANAGER (Diretor)
FARMWORKER (Trabalhador rural)
RETIRED (Aposentado)
TRAINEE (Estagiário)
APPRENTICE (Aprendiz)
FIXEDDUEDATE (Prazo determinado)
RETIREDMANAGER (Diretor aposentado)
PUBLICAGENT (Agente público)
TEACHER (Professor)
COOPERATIVEWORKER (Cooperado)
DOMESTICWORKER (Trabalhador doméstico)
TEACHERFIXEDDUEDATE (Professor com prazo determinado)
integration.employee.eSocialCategoryGrupo de parâmetros com dados da categoria eSocial do colaborador - Obrigatório
integration.employee.eSocialCategory.idAlfanuméricoSimIdentificador único do registro
integration.employee.eSocialCategory.codeEnumeraçãoSimCategoria do colaborador no eSocial, conforme a Tabela 01 (Categorias de Trabalhadores)

Category_XXX (onde “XXX” equivale ao código da categoria)

Clique aqui para ver a lista de valores possíveis

integration.employee.eSocialCategory.dateWhenDataSimData de início do colaborador na categoria eSocial (A partir de)
integration.employee.isDeficientBooleanoNãoColaborador é deficiente?true
false
integration.employee.companyGrupo de parâmetros com dados da empresa atual do colaborador - Obrigatório
integration.employee.company.idAlfanuméricoSimIdentificador único do registro
integration.employee.company.codeNuméricoSimCódigo da empresa
integration.employee.company.nameAlfanuméricoSimNome da empresa
integration.employee.previousCompanyGrupo de parâmetros com os dados da empresa anterior do colaborador (enviado caso o colaborador tenha alguma transferência entre empresas no seu histórico) - Opcional
integration.employee.previousCompany.idAlfanuméricoSimIdentificador único do registro
integration.employee.previousCompany.codeNuméricoSimCódigo da empresa
integration.employee.previousCompany.nameAlfanuméricoSimNome da empresa
integration.employee.companyBranchGrupo de parâmetros com dados da filial atual do colaborador - Obrigatório
integration.employee.companyBranch.idAlfanuméricoSimIdentificador único do registro
integration.employee.companyBranch.codeNuméricoSimCódigo da filial
integration.employee.companyBranch.companyBranchNameAlfanuméricoSimNome da filial
integration.employee.companyBranch.nameAlfanuméricoSimRazão social da filial
integration.employee.companyBranch.subscriptionTypeEnumeraçãoSimTipo de inscrição da filialCNPJ (Cadastro Nacional da Pessoa Jurídica)
CPF (Cadastro de Pessoas Físicas)
CAEPF (Cadastro de Atividade Econômica da Pessoa Física)
CNO (Cadastro Nacional de Obras)
CEI (Cadastro Específico do INSS)
integration.employee.companyBranch.subscriptionNumberAlfanuméricoSimNúmero da inscrição
integration.employee.companyBranch.dateWhenDataSimData de início do colaborador na filial (A partir de)
integration.employee.previousCompanyBranchGrupo de parâmetros com os dados da filial anterior do colaborador (enviado caso o colaborador tenha alguma transferência entre filiais no seu histórico) - Opcional
integration.employee.previousCompanyBranch.idAlfanuméricoSimIdentificador único do registro
integration.employee.previousCompanyBranch.codeNuméricoSimCódigo da filial
integration.employee.previousCompanyBranch.companyBranchNameAlfanuméricoSimNome da filial
integration.employee.previousCompanyBranch.nameAlfanuméricoSimRazão social da filial
integration.employee.previousCompanyBranch.subscriptionTypeEnumeraçãoSimTipo de inscrição da filialCNPJ (Cadastro Nacional da Pessoa Jurídica)
CPF (Cadastro de Pessoas Físicas)
CAEPF (Cadastro de Atividade Econômica da Pessoa Física)
CNO (Cadastro Nacional de Obras)
CEI (Cadastro Específico do INSS)
integration.employee.previousCompanyBranch.subscriptionNumberAlfanuméricoSimNúmero da inscrição
integration.employee.previousCompanyBranch.dateWhenDataSimData de início do colaborador na filial (A partir de)
integration.employee.costCenterGrupo de parâmetros com dados do centro de custo do colaborador - Opcional
integration.employee.costCenter.idAlfanuméricoNãoIdentificador único do registro
integration.employee.costCenter.codeAlfanuméricoNãoCódigo do centro de custo
integration.employee.costCenter.nameAlfanuméricoNãoNome do centro de custo
integration.employee.costCenter.dateWhenDataNãoData de início do colaborador no centro de custo (A partir de)
integration.employee.departmentGrupo de parâmetros com dados do setor do colaborador - Opcional
integration.employee.department.idAlfanuméricoNãoIdentificador único do registro
integration.employee.department.codeAlfanuméricoNãoCódigo do setor
integration.employee.department.structureCodeNuméricoNãoCódigo de organograma do setor
integration.employee.department.nameAlfanuméricoNãoNome do setor
integration.employee.department.dateWhenDataNãoData de início do colaborador no setor (A partir de)
integration.employee.jobPositionGrupo de parâmetros com dados do cargo do colaborador - Opcional
integration.employee.jobPosition.idAlfanuméricoNãoIdentificador único do registro
integration.employee.jobPosition.codeAlfanuméricoNãoCódigo do cargo
integration.employee.jobPosition.structureCodeAlfanuméricoNãoCódigo da estrutura de cargos
integration.employee.jobPosition.cboCodeAlfanuméricoNãoCódigo do CBO do cargo
integration.employee.jobPosition.nameAlfanuméricoNãoNome do cargo
integration.employee.jobPosition.dateWhenDataNãoData de início do colaborador no cargo (A partir de)
integration.employee.shiftGrupo de parâmetros com dados do turno do colaborador - Opcional
integration.employee.shift.idAlfanuméricoNãoIdentificador único do registro
integration.employee.shift.codeNuméricoNãoCódigo do turno
integration.employee.shift.nameAlfanuméricoNãoNome do turno
integration.employee.shift.dateWhenDataNãoData de início do colaborador no turno (A partir de)
integration.employee.workstationGrupo de parâmetros com dados do posto de trabalho do colaborador - Opcional
integration.employee.workstation.idAlfanuméricoNãoIdentificador único do registro
integration.employee.workstation.codeAlfanuméricoNãoCódigo do posto de trabalho
integration.employee.workstation.structureCodeNuméricoNãoEstrutura do posto de trabalho
integration.employee.workstation.nameAlfanuméricoNãoNome do posto de trabalho
integration.employee.workstation.dateWhenDataNãoData de início do colaborador no posto de trabalho (A partir de)
integration.employee.reasonLeaveGrupo de parâmetros com dados do motivo de afastamento do colaborador - Opcional
integration.employee.reasonLeave.idAlfanuméricoNãoIdentificador único do registro
integration.employee.reasonLeave.codeNuméricoNãoCódigo do motivo do afastamento (sistema da Senior)
integration.employee.reasonLeave.nameAlfanuméricoNãoEstrutura do motivo
integration.employee.reasonLeave.startDateDataNãoData de início do afastamento
integration.employee.reasonLeave.estimatedEndDateDataNãoData de previsão de término do afastamento
integration.employee.reasonLeave.endDateDataNãoData de término do afastamento
integration.employee.deficienciesLista de deficiências do colaborador - Opcional
integration.employee.deficiencies.idAlfanuméricoNãoIdentificador único do registro
integration.employee.deficiencies.codeNuméricoNãoCódigo da deficiência
integration.employee.deficiencies.nameAlfanuméricoNãoNome da deficiência
integration.employee.deficiencies.isMainDeficiencyBooleanoNãoÉ a deficiência principal? true
false
integration.employee.deficiencies.deficiencyTypeEnumeraçãoNãoTipo da deficiência no eSocial PHYSICAL (Física)
AUDITORY (Auditiva)
VISUAL (Visual)
MENTAL (Mental)
INTELLECTUAL (Intelectual)
OTHER (Outro tipo de deficiência)
integration.employee.deficiencies.dateWhenDataNãoData de início da deficiência
integration.employee.deficiencies.isRehabilitatedBooleanoNãoReabilitadotrue
false
integration.employee.deficiencies.employeeAlfanuméricoNãoIdentificador único do colaborador
integration.employee.ctpsNumberAlfanuméricoNãoNúmero da carteira de trabalho
integration.employee.ctpsSerieAlfanuméricoNãoSérie da carteira de trabalho
integration.employee.ctpsIssuanceDateDataNãoData da emissão da carteira de trabalho
integration.employee.ctpsSerieDigitAlfanuméricoNãoDígito da carteira de trabalho
integration.employee.ctpsStateEnumeraçãoNãoEstado (UF) da carteira de trabalhoAC, AL, AP, AM, BA, CE, DF, ES, GO, MA, MT, MS, MG, PA, PB, PR, PE, PI, RJ, RN, RS, RO, RR, SC, SP, SE, TO
integration.employee.rgNumberAlfanuméricoNãoCarteira de identidade
integration.employee.rgIssuerAlfanuméricoNãoÓrgão emissor da carteira de identidade
integration.employee.rgStateEnumeraçãoNãoEstado (UF) de emissão da carteira de identidadeAC, AL, AP, AM, BA, CE, DF, ES, GO, MA, MT, MS, MG, PA, PB, PR, PE, PI, RJ, RN, RS, RO, RR, SC, SP, SE, TO
integration.employee.rgIssuanceDateDataNãoData de emissão da carteira de identidade
integration.employee.numberContractSameHireDateNuméricoNãoNúmero de contratos do colaborador
integration.employee.previousEmployeeTypeAlfanuméricoNãoTipo de cadastro anterior do colaborador no sistema de folha (enviado caso o colaborador tenha alguma transferência entre empresas no seu histórico)
integration.employee.previousCodeNuméricoNãoCódigo de cadastro anterior do colaborador no sistema de folha (enviado caso o colaborador tenha alguma transferência entre empresas no seu histórico)
integration.employee.workEnvironmentLista de ambientes de trabalho do colaborador - Opcional
Caso o colaborador não tenha um histórico de ambientes de trabalho, serão usadas as informações da empresa atual desse colaborador.
integration.employee.workEnvironment.idAlfanuméricoNãoIdentificador único do registro
integration.employee.workEnvironment.locationEnumeraçãoSimLocal de trabalhoOWN_EMPLOYER (Estabelecimento do próprio empregador)
THIRD (Estabelecimento de terceiros)
integration.employee.workEnvironment.codeAlfanuméricoSimCódigo do ambiente de trabalho
integration.employee.workEnvironment.nameAlfanuméricoSimNome do ambiente de trabalho
integration.employee.workEnvironment.subscriptionTypeEnumeraçãoSimTipo de inscriçãoCNPJ (Cadastro Nacional da Pessoa Jurídica)
CPF (Cadastro de Pessoas Físicas)
CAEPF (Cadastro de Atividade Econômica da Pessoa Física)
CNO (Cadastro Nacional de Obras)
CEI (Cadastro Específico do INSS)
integration.employee.workEnvironment.subscriptionNumberAlfanuméricoSimNúmero de inscrição
integration.employee.workEnvironment.dateWhenDataSimData do histórico de ambiente de trabalho (A partir de)
integration.employee.reintegrationCompanyOriginEmpresa origem da reintegração do colaborador
integration.employee.reintegrationCompanyOrigin.idAlfanuméricoNãoIdentificador (ID) interno da entidade
integration.employee.reintegrationCompanyOrigin.codeNuméricoNãoCódigo da empresa
integration.employee.reintegrationCompanyOrigin.nameAlfanuméricoNãoNome da empresa
integration.employee.reintegrationEmployeeTypeOriginEnumeraçãoNãoTipo do colaborador origem da reintegraçãoEMPLOYEE (Colaborador)
THIRD (Terceiro)
PARTNER (Parceiro)
integration.employee.reintegrationCodeOriginNuméricoNãoCódigo origem da reintegração do colaborador
integration.companyNameAlfanuméricoSimNome da empresa usado para localização rápida (filtro) de uma pendência de integração
integration.companyBranchCodeNuméricoSimCódigo da filial usado para localização rápida (filtro) de uma pendência de integração
integration.companyBranchNameAlfanuméricoSimNome da filial usado para localização rápida (filtro) de uma pendência de integração
integration.employeeCodeNuméricoSimCódigo do colaborador usado para localização rápida (filtro) de uma pendência de integração
integration.eSocialRegistrationAlfanuméricoNãoMatrícula do colaborador no eSocial usado para localização rápida (filtro) de uma pendência de integração
integration.cpfNumberAlfanuméricoNãoNúmero do CPF do colaborador usado para localização rápida (filtro) de uma pendência de integração
integration.employeeNameAlfanuméricoSimNome do colaborador usado para localização rápida (filtro) de uma pendência de integração
integration.lotWorkstationAlfanuméricoNãoIdentificador (lote) de alterações de históricos ocasionadas por mudança de posto de trabalho

Exemplo JSON:

    {
        "integration":{
            "id":"eb1b5638-c9d0-4d00-9250-ab2b630da4da",
            "externalId":"86E7BE0CE78F4ABAA56533B5BBD34BEF",
            "externalHistoricId":"",
            "operationType":"INSERT",
            "employee":{
                "id":"34d0e267-dfb2-4834-8bbe-0f175d426bc7",
                "externalId":"86E7BE0CE78F4ABAA56533B5BBD34BEF",
                "employeeType":"EMPLOYEE",
                "code":48,
                "name":"João da Silva",
                "cpfNumber":"27100337046",
                "nisNumber":"60233579250",
                "birthday":"1991-01-01",
                "hireDate":"2019-01-01",
                "maritalStatusType":"SINGLE",
                "genderType":"MALE",
                "situationType":"WORKING",
                "contractType":"EMPLOYEE",
                "eSocialCategory":{
                    "id":"b3447abb-a29f-4692-8e35-b053c728bb1d",
                    "code":"Category_101",
                    "dateWhen":"2019-01-01",
                    "_discriminator":"eSocialCategory"
                },
                "isDeficient":false,
                "company":{
                    "id":"e89781a8-fd5f-46b0-b3fb-4f13aaffe462",
                    "code":1,
                    "name":"Demonstra Ind.& Com. Têxtil S/A",
                    "_discriminator":"company"
                },
                "companyBranch":{
                    "id":"d6e87895-0112-4963-a2c8-3eda9b30a64b",
                    "code":1,
                    "name":"Demonstra S/A - Matriz",
                    "subscriptionType":"CNPJ",
                    "subscriptionNumber":"12345678010158",
                    "dateWhen":"2019-01-01",
                    "_discriminator":"companyBranch"
                },
                "department":{
                    "id":"26e11e0d-db28-4576-b114-34027ea56fc0",
                    "code":"1.02",
                    "structureCode":1,
                    "name":"Administração",
                    "dateWhen":"2019-01-01",
                    "_discriminator":"department"
                },
                "jobPosition":{
                    "id":"e6afbaf2-1482-4883-86bf-c10e4f8857bb",
                    "code":"29",
                    "structureCode":"1",
                    "cboCode":"241005",
                    "name":"Advogado",
                    "dateWhen":"2019-01-01",
                    "_discriminator":"jobPosition"
                },
                "shift":{
                    "id":"99a6987a-a09c-4b1f-9d26-8611a93ee901",
                    "code":2,
                    "name":"08:00 1200-1330 1800/Móvel",
                    "dateWhen":"2019-01-01",
                    "_discriminator":"shift"
                },
                "workstation":{
                    "id":"2ccd614a-4ca5-4f44-ace1-70e98f8bc19d",
                    "code":"ADM004",
                    "structureCode":2,
                    "name":"Advogado",
                    "dateWhen":"2019-01-01",
                    "_discriminator":"workstation"
                },
                "deficiencies":[
                    
                ],
                "ctpsNumber":"12345678",
                "ctpsSerie":"1",
                "ctpsIssuanceDate":"2001-12-12",
                "ctpsSerieDigit":"",
                "ctpsState":"SC",
                "rgNumber":"124405447",
                "rgIssuer":"SSPSC",
                "rgState":"SC",
                "numberContractSameHireDate":1,
                "_discriminator":"employee",
                "workstation":{
                    "id":"2ccd614a-4ca5-4f44-ace1-70e98f8bc19d",
                    "code":"ADM004",
                    "structureCode":2,
                    "name":"Advogado",
                    "dateWhen":"2019-01-01",
                    "_discriminator":"workstation"
                }
            },
            "statusType":"ON_PROVIDER",
            "integrationType":"NEW_EMPLOYEE",
            "receiptDate":"2019-09-23T19:50:31.194278Z",
            "sendDate":"2019-09-23T19:52:01.833552Z",
            "scheduledDate":"2019-09-23",
            "dateWhen":"2019-09-23",
            "integrationMessage":"",
            "companyCode":1,
            "companyName":"Demonstra Ind.& Com. Têxtil S/A",
            "companyBranchCode":1,
            "companyBranchName":"Demonstra S/A - Matriz",
            "employeeCode":48,
            "eSocialRegistration":"",
            "cpfNumber":"27100337046",
            "employeeName":"João da Silva",
            "providerCompanyIdentification":"1",
            "providerEmployeeIdentification":"123456",
            "integrationSequence":2,
            "previewSendDate":"2019-09-23T19:52:01.833552Z",
            "integrationOrigin":"70a1c560-955d-4a16-8857-e838b9f5bebb",
            "regenerateAttempts":1
        }
        }
Resposta
CodeDescription
200

OK

Valor de exemplo:

    { }
default

Error response

Valor de exemplo:

    {
        "message": "string",
        "reason": "BAD_REQUEST"
    }
Exemplo:

Execução no API Client:

Imagem
Imagem
Imagem

Passo 3 - Enviar a resposta para a plataforma da Senior

Enviar a resposta para a plataforma da Senior indicando se a integração ocorreu com sucesso ou com erros.

Web service disponibilizado na plataforma da Senior: integrationUpdateStatus

[ POST ]
https://platform-homologx.senior.com.br/t/senior.com.br/bridge/1.0/rest/hcm/esocial4integration/signals/integrationUpdateStatus

Parâmetros de entrada

Cabeçalho (Header):

ParâmetroValor
Content-Typeapplication/json
AuthorizationBearer Token

Corpo (Body):

ParâmetroTipoObrigatórioDescrição
providerXmlIdAlfanuméricoNãoIdentificador único do envio do XML no prestador SST
idAlfanuméricoNãoIdentificador único do registro na plataforma da Senior

Observação

Os parâmetros de entrada são opcionais. Porém, no mínimo um dos dois parâmetros sempre precisa ser informado. Caso sejam informados os dois parâmetros, será considerado apenas o id.

Exemplo JSON

    {
        "providerXmlId" : "123456789",
        "id" : "91e89d6d-9bad-4f63-91c8-f0b6940f4d31"
    }

Resposta

CodeDescription
200

Resposta retornada pelo sistema da Senior:

ParâmetroTipoDescriçãoValores permitidos
idAlfanumérico

Identificador único do registro na plataforma da Senior.

providerXmlIdAlfanumérico

Identificador único do envio do XML no prestador SST, conforme informado no envio do evento para a plataforma da Senior.

eventIdAlfanumérico

Identificador único do registro na plataforma da Senior.

Exemplo: “ID1123456780101582019120411291600001”

xmlStatusAlfanumérico

Indica o status da validação e de envio do XML.

IN_ANALYSIS (Em validação no sistema da Senior)
VALIDATION_SUCCESS (Validado pela Senior e está ok para enviar ao Governo)
VALIDATION_ERROR (Validado pela Senior e apresentou erros no XML)
SENDING_TO_GOVERNMENT (Em processo de envio para o Governo)
WAITING_GOVERNMENT_RETURN (Enviado e aguardando retorno do Governo)
GOVERNMENT_RETURN (Retorno do Governo após receber o evento - recibo (sucesso) ou críticas (erro))

validationMessageAlfanumérico

Para as situações em que o status do XML é VALIDATION_ERROR, apresenta a mensagem relacionada ao erro.

governmentReturnTypeAlfanumérico

Indica o tipo de retorno do Governo para o evento que foi enviado.

RECEIPT_RETURNED (Número do recibo retornado pelo Governo)
MESSAGE_RETURNED (Mensagem ou crítica retornada pelo Governo)

governmentReceiptNumberAlfanumérico

Número do recibo retornado do governo, para o tipo RECEIPT_RETURNED.

governmentMessageAlfanumérico

Mensagens ou críticas retornadas do governo, para o tipo MESSAGE_RETURNED.

rawGovernmentReturnAlfanumérico

Conteúdo retornado pelo Governo na íntegra. Este parâmetro só contém dados se:

  • o conteúdo retornado é um recibo (governmentReturnType = RECEIPT_RETURNED)
  • o novo modo de configuração do eDocs está em uso (eDocs consome eventos da plataforma senior X)
companyProviderIdAlfanumérico

Código de identificação da empresa no sistema do prestador SST.

Valor de exemplo:

    {
        "result":[
            {
                "id":"91e89d6d-9bad-4f63-91c8-f0b6940f4d31",
                "providerXmlId":"123456789",
                "xmlStatus":"VALIDATION_SUCCESS",
                "eventId":"ID1123456780101582019120411291600001",
                "governmentReturnType":"RECEIPT_RETURNED",
                "governmentReceiptNumber":"999999",
                "rawGovernmentReturn":"<returnGovernment> ... </returnGovernment>",
                "companyProviderId":"1234"
            }
        ]
    }
default

Error response

Valor de exemplo:

    {
        "message": "string",
        "reason": "BAD_REQUEST"
    }
Exemplo:

Execução no API Client:

Imagem
Imagem
Imagem

Eventos do eSocial (arquivos XML)

Passos para a integração:

Passos para a integração de eventos do eSocial: 1) Autenticação; 2) Enviar eventos do eSocial; 3) Buscar status dos eventos; 3) Enviar resposta para a plataforma.

Passo 1 - Autenticação

O primeiro passo é implementar a autenticação com a plataforma de homologação da Senior. Isso é feito pelo serviço loginWithKey, responsável por realizar o login na plataforma com chave e segredo informados pelo usuário.

Para obter a chave e o segredo que serão usados na sua implementação entre em contato com a Senior pelo e-mail: [integradorsst.devs@senior.com.br](/integrador-sst/desenvolvedores/mailto:integradorsst.devs@senior.com.br?subject=Integrador SST - Contato via Portal de Documentação). Este é um canal de comunicação voltado para desenvolvedores, respondendo exclusivamente questões de caráter técnico e de arquitetura do Integrador SST.

Web service disponibilizado na plataforma da Senior: loginWithKey

URL:

Estrutura das credenciais:

    {
            "accessKey": "XXX",
            "secret": "XXX",
            "tenantName": "XXX"
    }
Exemplo:

Execução no API Client:

Imagem
Imagem
Imagem

Passo 2 - Enviar os eventos do eSocial (XML) para a plataforma da Senior

Enviar os eventos do eSocial (XML) para a Senior. Os arquivos XML devem ser enviados individualmente (um a um) do prestador para a Senior.

Cada XML enviado é validado, conforme estrutura e atributos do seu leiaute, antes de ser enviado ao Governo. Caso o XML esteja inválido, ele não será considerado para envio ao eSocial.

Web service disponibilizado na plataforma da Senior: sendEsocialXml

Parâmetros de entrada

Cabeçalho (Header):

ParâmetroValor
Content-Typeapplication/json
AuthorizationBearer Token

Corpo (Body):

ParâmetroTipoObrigatórioDescriçãoValores permitidos
providerXmlIdAlfanuméricoSimID do XML no prestador SST
providerCompanyIdAlfanuméricoSimCódigo da empresa no prestador SST
subscriptionTypeAlfanuméricoSimTipo de inscrição da empresaCNPJ

CPF

CAEPF

CNO

CEI
subscriptionNumberAlfanuméricoSimNúmero de inscrição da empresa, sem máscara de formatação
xmlAlfanuméricoSimXML do evento do eSocial, sem quebras de linhas

Exemplo JSON:

{

          “providerXmlId” : “11”,

          “providerCompanyId” : “1”,

          “subscriptionType” : “CNPJ”,

          “subscriptionNumber” : “12345678010158”,

          “xml” : “<eSocial xmlns=“http://www.esocial.gov.br/schema/evt/evtMonit/v01_00_00\”>

<evtMonit Id=“ID1123456780101582020071711131000003”> <ideEvento> <indRetif>1</indRetif> <tpAmb>2</tpAmb> <procEmi>1</procEmi>

<verProc>6.2.0</verProc> </ideEvento> <ideEmpregador> <tpInsc>1</tpInsc> <nrInsc>12345678010158</nrInsc> </ideEmpregador>

<ideVinculo> <matricula>123456789</matricula> </ideVinculo> <exMedOcup> <tpExameOcup>0</tpExameOcup> <aso>

<dtAso>2020-07-20</dtAso> <resAso>1</resAso> <exame> <dtExm>2020-07-01</dtExm> <procRealizado>0001</procRealizado>

<ordExame>1</ordExame> </exame> <medico> <nmMed>teste</nmMed> <nrCRM>1231213</nrCRM> <ufCRM>AC</ufCRM>

</medico> </aso> </exMedOcup> </evtMonit></eSocial>“

{

Resposta

CodeDescription
200

Resposta retornada pelo sistema da Senior:

ParâmetroTipoDescriçãoValores permitidos
idAlfanuméricoIdentificador único do registro na plataforma da Senior
providerXmlIdAlfanuméricoIdentificador único do envio do XML no prestador SST, conforme informado no envio do evento para a plataforma da Senior
xmlStatusAlfanuméricoStatus da validação do XMLIN_ANALYSIS (Em validação no sistema da Senior)

VALIDATION_SUCCESS (Validado pela Senior e está ok para enviar ao Governo)

VALIDATION_ERROR (Validado pela Senior e apresentou erros no XML)

SENDING_TO_GOVERNMENT (Em processo de envio para o Governo)

WAITING_GOVERNMENT_RETURN (Enviado e aguardando retorno do Governo)

GOVERNMENT_RETURN (Retorno do Governo após receber o evento - recibo (sucesso) ou críticas (erro))

Valor de exemplo:

{

          “totalPages”: 1,

          “totalElements”: 1,

          “contents”: [

               {

                    “id”: “91e89d6d-9bad-4f63-91c8-f0b6940f4d31”,

                    “providerXmlId”: “123456789”,

                    “xmlStatus”: “IN_ANALYSIS”,

               {

          ]

{

default

Error response

Valor de exemplo:

{

      “message”: “string”,

      “reason”: “BAD_REQUEST”

{

Exemplo:

Execução no API Client:

Imagem
Imagem
Imagem

Passo 3 - Obter os status dos eventos (XML) da plataforma da Senior

Existem duas maneiras de obter os status dos eventos da plataforma da Senior. Você pode escolher uma das opções descritas a seguir:

3.1) Buscar os status dos eventos periodicamente (opção 1)

A primeira opção é buscar, de tempo em tempo, os status dos eventos (XML) que foram enviados ao sistema da Senior.

É preciso implementar a busca dos registros da plataforma senior X com um intervalo mínimo de 3 minutos entre cada chamada do web service.

Web service disponibilizado na plataforma da Senior: statusEsocialXml
Parâmetros de entrada

Cabeçalho (Header):

ParâmetroValor
Content-Typeapplication/json
AuthorizationBearer Token

Corpo (Body):

ParâmetroTipoObrigatórioDescrição
providerXmlIdAlfanuméricoNãoIdentificador único do envio do XML no prestador SST
idAlfanuméricoNãoIdentificador único do registro na plataforma da Senior

Observação

Os parâmetros de entrada são opcionais. Porém, no mínimo um dos dois parâmetros sempre precisa ser informado. Caso sejam informados os dois parâmetros, será considerado apenas o id.

Exemplo JSON:

{

          “providerXmlId” : “123456789”,

          “id” : “91e89d6d-9bad-4f63-91c8-f0b6940f4d31”

{

Resposta
CodeDescription
200

Resposta retornada pelo sistema da Senior:

ParâmetroTipoDescriçãoValores permitidos
idAlfanuméricoIdentificador único do registro na plataforma da Senior.
providerXmlIdAlfanuméricoIdentificador único do envio do XML no prestador SST, conforme informado no envio do evento para a plataforma da Senior.
eventIdAlfanumérico

Identificador do evento enviado no XML do eSocial.

Exemplo:

“ID1123456780101582019120411291600001”

xmlStatusAlfanuméricoIndica o status da validação e de envio do XML.IN_ANALYSIS (Em validação no sistema da Senior)

VALIDATION_SUCCESS (Validado pela Senior e está ok para enviar ao Governo)

VALIDATION_ERROR (Validado pela Senior e apresentou erros no XML)

SENDING_TO_GOVERNMENT (Em processo de envio para o Governo)

WAITING_GOVERNMENT_RETURN (Enviado e aguardando retorno do Governo)

GOVERNMENT_RETURN (Retorno do Governo após receber o evento - recibo (sucesso) ou críticas (erro))
validationMessageAlfanumérico

Para as situações em que o status do XML é VALIDATION_ERROR, apresenta a mensagem relacionada ao erro.

governmentReturnTypeAlfanuméricoIndica o tipo de retorno do Governo para o evento que foi enviado.RECEIPT_RETURNED (Número do recibo retornado pelo Governo)

MESSAGE_RETURNED (Mensagem ou crítica retornada pelo Governo)
governmentReceiptNumberAlfanuméricoNúmero do recibo retornado do governo, para o tipo RECEIPT_RETURNED.
governmentMessageAlfanuméricoMensagens ou críticas retornadas do governo, para o tipo MESSAGE_RETURNED.
rawGovernmentReturnAlfanumérico

Conteúdo retornado pelo Governo na íntegra. Este parâmetro só contém dados se:

  • o conteúdo retornado é um recibo (governmentReturnType = RECEIPT_RETURNED)
  • o novo modo de configuração do eDocs está em uso (eDocs consome eventos da plataforma senior X)
companyProviderIdAlfanuméricoCódigo de identificação da empresa no sistema do prestador SST.

Valor de exemplo:

{

          “result”: [

               {

                    “id”: “91e89d6d-9bad-4f63-91c8-f0b6940f4d31”,

                    “providerXmlId”: “123456789”,

                    “xmlStatus”: “VALIDATION_SUCCESS”,

                    “eventId”: “ID1123456780101582019120411291600001”,

                    “governmentReturnType”: “RECEIPT_RETURNED”,

                    “governmentReceiptNumber”: “999999”,

                    “rawGovernmentReturn”: “<returnGovernment> … </returnGovernment>”

                    “companyProviderId”: “1234”

               {

          ]

{

default

Error response

Valor de exemplo:

{

      “message”: “string”,

      “reason”: “BAD_REQUEST”

{

Exemplos:

Execução no API Client:

Preenchimento dos parâmetros do cabeçalho (Header) da mensagem:

Imagem

Evento validado com sucesso pelo sistema da Senior (VALIDATION_SUCCESS):

Imagem

Evento validado com erro pelo sistema da Senior (VALIDATION_ERROR):

Imagem

Evento em processo de envio para o Governo (SENDING_TO_GOVERNMENT):

Imagem

3.2) Receber os status dos eventos em tempo real (opção 2)

A segunda opção é receber os status dos eventos (XML) em tempo real. Para isso é necessário seguir esses passos:

Implemente este serviço para receber as atualizações do status dos eventos do eSocial (XML) a medida em que elas ocorrem no sistema da Senior. Por exemplo, quando o Governo retorna para a Senior o recibo ou as críticas do evento do eSocial.

Web service disponibilizado no prestador SST: statusIntegration

[ POST ]

[url-prestador-sst]/esocial/statusIntegration

Exemplo: http://www.prestador-sst.com.br/esocial/statusIntegration

Parâmetros

A pendência de integração é enviada pela plataforma da Senior com os parâmetros abaixo:

Cabeçalho (Header):

ParâmetroObservações
Content-TypeValor padrão: application/json
x-senior-key

Chave de acesso da empresa referente à pendência de integração na plataforma da Senior. Essa chave identifica a qual empresa pertence a pendência.

Exemplo:

x-senior-key : FpfBNem2Fw8vaVIEByOpiK_eKOYa

Corpo (Body):

CodeDescription
200

Resposta retornada pelo sistema da Senior:

ParâmetroTipoDescriçãoValores permitidos
idAlfanuméricoIdentificador único do registro na plataforma da Senior.
providerXmlIdAlfanuméricoIdentificador único do envio do XML no prestador SST, conforme informado no envio do evento para a plataforma da Senior.
eventIdAlfanumérico

Identificador do evento enviado no XML do eSocial.

Exemplo:

“ID1123456780101582019120411291600001”

xmlStatusAlfanuméricoIndica o status da validação e de envio do XML.IN_ANALYSIS (Em validação no sistema da Senior)

VALIDATION_SUCCESS (Validado pela Senior e está ok para enviar ao Governo)

VALIDATION_ERROR (Validado pela Senior e apresentou erros no XML)

SENDING_TO_GOVERNMENT (Em processo de envio para o Governo)

WAITING_GOVERNMENT_RETURN (Enviado e aguardando retorno do Governo)

GOVERNMENT_RETURN (Retorno do Governo após receber o evento - recibo (sucesso) ou críticas (erro))
validationMessageAlfanumérico

Para as situações em que o status do XML é VALIDATION_ERROR, apresenta a mensagem relacionada ao erro.

governmentReturnTypeAlfanuméricoIndica o tipo de retorno do Governo para o evento que foi enviado.RECEIPT_RETURNED (Número do recibo retornado pelo Governo)

MESSAGE_RETURNED (Mensagem ou crítica retornada pelo Governo)
governmentReceiptNumberAlfanuméricoNúmero do recibo retornado do governo, para o tipo RECEIPT_RETURNED.
governmentMessageAlfanuméricoMensagens ou críticas retornadas do governo, para o tipo MESSAGE_RETURNED.
rawGovernmentReturnAlfanumérico

Conteúdo retornado pelo Governo na íntegra. Este parâmetro só contém dados se:

  • o conteúdo retornado é um recibo (governmentReturnType = RECEIPT_RETURNED)
  • o novo modo de configuração do eDocs está em uso (eDocs consome eventos da plataforma senior X)
companyProviderIdAlfanuméricoCódigo de identificação da empresa no sistema do prestador SST.

Valor de exemplo:

{

          “result”: [

               {

                    “id”: “91e89d6d-9bad-4f63-91c8-f0b6940f4d31”,

                    “providerXmlId”: “123456789”,

                    “xmlStatus”: “VALIDATION_SUCCESS”,

                    “eventId”: “ID1123456780101582019120411291600001”,

                    “governmentReturnType”: “RECEIPT_RETURNED”,

                    “governmentReceiptNumber”: “999999”,

                    “rawGovernmentReturn”: “<returnGovernment> … </returnGovernment>”

                   “companyProviderId”: “1234”

               {

          ]

{

default

Error response

Valor de exemplo:

{

      “message”: “string”,

      “reason”: “BAD_REQUEST”

{

Resposta
CodeDescription
200

Ok

Valor de exemplo:

{ {

default

Error response

Valor de exemplo:

{

      “message”: “string”,

      “reason”: “BAD_REQUEST”

{

Passo 4 - Enviar resposta para a plataforma da Senior indicando o recebimento dos status

Enviar a resposta para a plataforma da Senior indicando se os status dos eventos do eSocial (XML) foram recebidos com sucesso ou com erros no sistema do prestador.

Web service disponibilizado na plataforma da Senior: statusEsocialXmlReceived

Parâmetros de entrada

Cabeçalho (Header):

ParâmetroValor
Content-Typeapplication/json
AuthorizationBearer Token

Corpo (Body):

ParâmetroTipoDescriçãoObservaçõesValores permitidos
providerXmlIdAlfanuméricoIdentificador único do evento no prestador SSTIdentificador único do evento do eSocial (XML) no prestador SST
providerStatusTypeEnumeraçãoSituação da integração do status do evento do eSocial para o prestador SSTSituação do status do evento do eSocial em relação ao prestador SST.ON_PROVIDER (A situação do evento foi recebida pelo prestador SST)

PROVIDER_ERROR (Houve problemas no recebimento da situação do evento pelo prestador SST)
providerErrorMessageAlfanuméricoMensagem de erroMensagem de erro enviada para a plataforma da Senior com o motivo do problema no recebimento da situação do evento pelo prestador SST.

Exemplo JSON:

Indicação que o status do evento foi recebido com sucesso:

{

          “providerXmlId”: “123456789”,

          “providerStatusType” : “ON_PROVIDER”,

          “providerErrorMessage” : ""

}

Indicação que houve problema no recebimento do status do evento:

{

          “providerXmlId”: “123456789”,

          “providerStatusType” : “PROVIDER_ERROR”,

          “providerErrorMessage” : “Não foi possível integrar o status do evento do eSocial por indisponibilidade do serviço do sistema do prestador SST.”

}

Resposta

CodeDescription
202

Ok

Valor de exemplo:

{ }

default

Error response

Valor de exemplo:

{

      “message”: “string”,

      “reason”: “BAD_REQUEST”

}

Exemplo:

Execução no API Client:

Indicação que o status do evento foi recebido com sucesso:

Imagem
Imagem

Indicação que houve problema no recebimento do status do evento:

Imagem

Projeto Template

Caso não queira implementar a sua API como descrito nesta documentação, disponibilizamos também o projeto sst-consumer-example. Este projeto é um template que facilita a implementação da API do Integrador SST em Java.

O projeto sst-consumer-example está disponível no GitHub , basta fazer o download e alterá-lo de acordo com as suas necessidades, seguindo a documentação disponível dentro do próprio template.


Ambiente de homologação

Após implementar a API, você pode solicitar o acesso ao ambiente de homologação e testes.

Se este é o seu primeiro contato com a equipe do Integrador SST da Senior, faça sua solicitação preenchendo o formulário disponível na documentação de passos para a integração.

Dúvidas?

Caso ainda tenha algum questionamento sobre o desenvolvimento desta API entre em contato com a Senior através do e-mail: integradorsst.devs@senior.com.br.

Este é um canal de comunicação voltado para desenvolvedores, respondendo exclusivamente questões de caráter técnico e de arquitetura do Integrador SST. Antes de entrar em contato é importante ter feito a leitura de todas as orientações e exemplos disponíveis nesta documentação.

Outros assuntos, comerciais ou de negócio, devem ser encaminhados para os canais apropriados da Senior.


Esta é a documentação da versão mais atual desta API. Clique aqui se quiser consultar a documentação da versão anterior (descontinuada).

Este artigo ajudou você?