English
Español
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.
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:
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. 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
|
|
Estrutura das credenciais:
{
"accessKey": "XXX","secret": "XXX","tenantName": "XXX"}Exemplo:
Execução no API Client:
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
|
|
Parâmetros de entrada
Cabeçalho (Header):
| Parâmetro | Valor |
|---|---|
Content-Type
|
application/json |
Authorization
|
Bearer Token |
Corpo (Body):
| Parâmetro | Tipo | Obrigatório | Descrição | Valores permitidos |
|---|---|---|---|---|
pagination
|
Grupo de parâmetros com a definição da paginação dos registros - Opcional | |||
pagination.current
|
Numérico | Sim | Página atual de registros | |
pagination.size
|
Numérico | Sim | Quantidade de registros por página | |
pagination.orderBy
|
Grupo de parâmetros com a definição da ordenação - Opcional | |||
pagination.orderBy.field
|
Alfanumérico | Sim | Nome do campo pelo qual os registros serão ordenados | |
pagination.orderBy.direction
|
Enumeração | Não | Orientação da ordenação | ASC (Ascendente)DESC (Descendente) |
Exemplo JSON:
|
{ "pagination": { "current": 0, "size": 10, "orderBy": [{ "field": "receiptDate", "direction": "ASC" }] } } |
Resposta
| Code | Description | |
|---|---|---|
200
|
Ok Valor de exemplo:
Notas
|
|
default
|
Error response Valor de exemplo:
|
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:
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
|
|
Parâmetros
A pendência de integração é enviada pela plataforma da Senior com os parâmetros abaixo:
Cabeçalho (Header):
| Parâmetro | Tipo | Descrição | Observações |
|---|---|---|---|
Content-Type
|
Alfanumérico | Especifica o tipo de conteúdo enviado. | Valor padrão: application/json |
x-senior-key
|
Alfanumérico |
Chave de acesso da empresa que enviou a pendência de integração. |
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:
|
Corpo (Body):
| Parâmetro | Tipo | Obrigatório | Descrição | Valores permitidos |
|---|---|---|---|---|
integration.id
|
Alfanumérico | Sim | Identificador único da pendência de integração na API | |
integration.externalId
|
Alfanumérico | Sim | Identificador da pendência de integração entre os sistemas | |
integration.externalHistoricId
|
Alfanumérico | Não | Identificador anterior da pendência de integração entre os sistemas | |
integration.operationType
|
Enumeração | Sim | Tipo de operação | INSERT
UPDATE
DELETE
|
integration.statusType
|
Enumeração | Sim | Status 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.integrationType
|
Enumeração | Sim |
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.receiptDate
|
Data | Sim | Data de criação da pendência de integração | |
integration.previewSendDate
|
Data | Sim | Data prevista para envio da pendência de integração | |
integration.scheduledDate
|
Data | Sim | Data do agendamento para envio da pendência de integração | |
integration.sendDate
|
Data | Sim | Data de envio da pendência de integração | |
integration.providerCompanyIdentification
|
Alfanumérico | Sim | Identificação da empresa no prestador SST | |
itengration.providerEmployeeIdentification
|
Alfanumérico | Não | Identificação do colaborador no prestador SST | |
integration.providerPreviousCompanyIdentification
|
Alfanumérico | Não | Identificação da empresa anterior no prestador SST (enviada caso o colaborador tenha alguma transferência entre empresas no seu histórico) | |
integration.dateWhen
|
Data | Sim | Data de referência das informações do colaborador | |
integration.integrationSequence
|
Numérico | Não | Número sequencial da integração | |
integration.cancelationReason
|
Alfanumérico | Não | Motivo do cancelamento da pendência de integração | |
integration.integrationMessage
|
Alfanumérico | Não | Observações da integração | |
integration.stackTrace
|
Alfanumérico | Não | Detalhes de eventuais erros | |
integration.employee
|
Grupo de parâmetros com dados do colaborador - Obrigatório | |||
integration.employee.id
|
Alfanumérico | Sim | Identificador do colaborador para o sistema de folha | |
integration.employee.externalId
|
Alfanumérico | Sim | Identificador do colaborador para integrações entre os sistemas | |
integration.employee.employeeType
|
Enumeração | Sim | Tipo do colaborador | EMPLOYEE (Colaborador)THIRD (Terceiro)PARTNER (Parceiro) |
integration.employee.code
|
Alfanumérico | Sim | Código do cadastro do colaborador no sistema de folha | |
integration.employee.eSocialRegistration
|
Alfanumérico | Não | Matrícula do eSocial | |
integration.employee.name
|
Alfanumérico | Sim | Nome do colaborador | |
integration.employee.cpfNumber
|
Numérico | Não | Número do CPF | |
integration.employee.nisNumber
|
Numérico | Não | Número do NIS | |
integration.employee.birthday
|
Data | Não | Data de nascimento | |
integration.employee.hireDate
|
Data | Não | Data de admissão | |
integration.employee.dismissalDate
|
Data | Não | Data de demissão | |
integration.employee.maritalStatusType
|
Enumeração | Não | Estado civil | SINGLE (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.genderType
|
Enumeração | Não | Gênero do colaborador | MALE (Masculino)FEMALE (Feminino) |
integration.employee.situationType
|
Enumeração | Sim | Situação do colaborador | PRE_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.contractType
|
Enumeração | Não | Tipo do contrato | EMPLOYEE (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.eSocialCategory
|
Grupo de parâmetros com dados da categoria eSocial do colaborador - Obrigatório | |||
integration.employee.eSocialCategory.id
|
Alfanumérico | Sim | Identificador único do registro | |
integration.employee.eSocialCategory.code
|
Enumeração | Sim | Categoria do colaborador no eSocial, conforme a Tabela 01 (Categorias de Trabalhadores) |
Clique aqui para ver a lista de valores possíveis |
integration.employee.eSocialCategory.dateWhen
|
Data | Sim | Data de início do colaborador na categoria eSocial (A partir de) | |
integration.employee.isDeficient
|
Booleano | Não | Colaborador é deficiente? | true
false
|
integration.employee.company
|
Grupo de parâmetros com dados da empresa atual do colaborador - Obrigatório | |||
integration.employee.company.id
|
Alfanumérico | Sim | Identificador único do registro | |
integration.employee.company.code
|
Numérico | Sim | Código da empresa | |
integration.employee.company.name
|
Alfanumérico | Sim | Nome da empresa | |
integration.employee.previousCompany
|
Grupo 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.id
|
Alfanumérico | Sim | Identificador único do registro | |
integration.employee.previousCompany.code
|
Numérico | Sim | Código da empresa | |
integration.employee.previousCompany.name
|
Alfanumérico | Sim | Nome da empresa | |
integration.employee.companyBranch
|
Grupo de parâmetros com dados da filial atual do colaborador - Obrigatório |
|||
integration.employee.companyBranch.id
|
Alfanumérico | Sim | Identificador único do registro | |
integration.employee.companyBranch.code
|
Numérico | Sim | Código da filial | |
integration.employee.companyBranch.companyBranchName
|
Alfanumérico | Sim | Nome da filial | |
integration.employee.companyBranch.name
|
Alfanumérico | Sim | Razão social da filial | |
integration.employee.companyBranch.subscriptionType
|
Enumeração | Sim | Tipo de inscrição da filial | CNPJ (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.subscriptionNumber
|
Alfanumérico | Sim | Número da inscrição | |
integration.employee.companyBranch.dateWhen
|
Data | Sim | Data de início do colaborador na filial (A partir de) | |
integration.employee.previousCompanyBranch
|
Grupo 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.id
|
Alfanumérico | Sim | Identificador único do registro | |
integration.employee.previousCompanyBranch.code
|
Numérico | Sim | Código da filial | |
integration.employee.previousCompanyBranch.companyBranchName
|
Alfanumérico | Sim | Nome da filial | |
integration.employee.previousCompanyBranch.name
|
Alfanumérico | Sim | Razão social da filial | |
integration.employee.previousCompanyBranch.subscriptionType
|
Enumeração | Sim | Tipo de inscrição da filial | CNPJ (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.subscriptionNumber
|
Alfanumérico | Sim | Número da inscrição | |
integration.employee.previousCompanyBranch.dateWhen
|
Data | Sim | Data de início do colaborador na filial (A partir de) | |
integration.employee.costCenter
|
Grupo de parâmetros com dados do centro de custo do colaborador - Opcional |
|||
integration.employee.costCenter.id
|
Alfanumérico | Não | Identificador único do registro | |
integration.employee.costCenter.code
|
Alfanumérico | Não | Código do centro de custo | |
integration.employee.costCenter.name
|
Alfanumérico | Não | Nome do centro de custo | |
integration.employee.costCenter.dateWhen
|
Data | Não | Data de início do colaborador no centro de custo (A partir de) | |
integration.employee.department
|
Grupo de parâmetros com dados do setor do colaborador - Opcional |
|||
integration.employee.department.id
|
Alfanumérico | Não | Identificador único do registro | |
integration.employee.department.code
|
Alfanumérico | Não | Código do setor | |
integration.employee.department.structureCode
|
Numérico | Não | Código de organograma do setor | |
integration.employee.department.name
|
Alfanumérico | Não | Nome do setor | |
integration.employee.department.dateWhen
|
Data | Não | Data de início do colaborador no setor (A partir de) | |
integration.employee.jobPosition
|
Grupo de parâmetros com dados do cargo do colaborador - Opcional |
|||
integration.employee.jobPosition.id
|
Alfanumérico | Não | Identificador único do registro | |
integration.employee.jobPosition.code
|
Alfanumérico | Não | Código do cargo | |
integration.employee.jobPosition.structureCode
|
Alfanumérico | Não | Código da estrutura de cargos | |
integration.employee.jobPosition.cboCode
|
Alfanumérico | Não | Código do CBO do cargo | |
integration.employee.jobPosition.name
|
Alfanumérico | Não | Nome do cargo | |
integration.employee.jobPosition.dateWhen
|
Data | Não | Data de início do colaborador no cargo (A partir de) | |
integration.employee.shift
|
Grupo de parâmetros com dados do turno do colaborador - Opcional |
|||
integration.employee.shift.id
|
Alfanumérico | Não | Identificador único do registro | |
integration.employee.shift.code
|
Numérico | Não | Código do turno | |
integration.employee.shift.name
|
Alfanumérico | Não | Nome do turno | |
integration.employee.shift.dateWhen
|
Data | Não | Data de início do colaborador no turno (A partir de) | |
integration.employee.workstation
|
Grupo de parâmetros com dados do posto de trabalho do colaborador - Opcional |
|||
integration.employee.workstation.id
|
Alfanumérico | Não | Identificador único do registro | |
integration.employee.workstation.code
|
Alfanumérico | Não | Código do posto de trabalho | |
integration.employee.workstation.structureCode
|
Numérico | Não | Estrutura do posto de trabalho | |
integration.employee.workstation.name
|
Alfanumérico | Não | Nome do posto de trabalho | |
integration.employee.workstation.dateWhen
|
Data | Não | Data de início do colaborador no posto de trabalho (A partir de) | |
integration.employee.reasonLeave
|
Grupo de parâmetros com dados do motivo de afastamento do colaborador - Opcional |
|||
integration.employee.reasonLeave.id
|
Alfanumérico | Não | Identificador único do registro | |
integration.employee.reasonLeave.code
|
Numérico | Não | Código do motivo do afastamento (sistema da Senior) | |
integration.employee.reasonLeave.name
|
Alfanumérico | Não | Estrutura do motivo | |
integration.employee.reasonLeave.startDate
|
Data | Não | Data de início do afastamento | |
integration.employee.reasonLeave.estimatedEndDate
|
Data | Não | Data de previsão de término do afastamento | |
integration.employee.reasonLeave.endDate
|
Data | Não | Data de término do afastamento | |
integration.employee.deficiencies
|
Lista de deficiências do colaborador - Opcional |
|||
integration.employee.deficiencies.id
|
Alfanumérico | Não | Identificador único do registro | |
integration.employee.deficiencies.code
|
Numérico | Não | Código da deficiência | |
integration.employee.deficiencies.name
|
Alfanumérico | Não | Nome da deficiência | |
integration.employee.deficiencies.isMainDeficiency
|
Booleano | Não | É a deficiência principal? | true
false
|
integration.employee.deficiencies.deficiencyType
|
Enumeração | Não | Tipo 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.dateWhen
|
Data | Não | Data de início da deficiência | |
integration.employee.deficiencies.isRehabilitated
|
Booleano | Não | Reabilitado | true
false
|
integration.employee.deficiencies.employee
|
Alfanumérico | Não | Identificador único do colaborador | |
integration.employee.ctpsNumber
|
Alfanumérico | Não | Número da carteira de trabalho | |
integration.employee.ctpsSerie
|
Alfanumérico | Não | Série da carteira de trabalho | |
integration.employee.ctpsIssuanceDate
|
Data | Não | Data da emissão da carteira de trabalho | |
integration.employee.ctpsSerieDigit
|
Alfanumérico | Não | Dígito da carteira de trabalho | |
integration.employee.ctpsState
|
Enumeração | Não | Estado (UF) da carteira de trabalho | AC, 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.rgNumber
|
Alfanumérico | Não | Carteira de identidade | |
integration.employee.rgIssuer
|
Alfanumérico | Não | Órgão emissor da carteira de identidade | |
integration.employee.rgState
|
Enumeração | Não | Estado (UF) de emissão da carteira de identidade | AC, 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.rgIssuanceDate
|
Data | Não | Data de emissão da carteira de identidade | |
integration.employee.numberContractSameHireDate
|
Numérico | Não | Número de contratos do colaborador | |
integration.employee.previousEmployeeType
|
Alfanumérico | Não | Tipo 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.previousCode
|
Numérico | Não | Có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.workEnvironment
|
Lista 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.id
|
Alfanumérico | Não | Identificador único do registro | |
integration.employee.workEnvironment.location
|
Enumeração | Sim | Local de trabalho | OWN_EMPLOYER (Estabelecimento do próprio empregador)THIRD (Estabelecimento de terceiros) |
integration.employee.workEnvironment.code
|
Alfanumérico | Sim | Código do ambiente de trabalho | |
integration.employee.workEnvironment.name
|
Alfanumérico | Sim | Nome do ambiente de trabalho | |
integration.employee.workEnvironment.subscriptionType
|
Enumeração | Sim | Tipo de inscrição | CNPJ (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.subscriptionNumber
|
Alfanumérico | Sim | Número de inscrição | |
integration.employee.workEnvironment.dateWhen
|
Data | Sim | Data do histórico de ambiente de trabalho (A partir de) | |
integration.employee.reintegrationCompanyOrigin
|
Empresa origem da reintegração do colaborador | |||
integration.employee.reintegrationCompanyOrigin.id
|
Alfanumérico | Não | Identificador (ID) interno da entidade | |
integration.employee.reintegrationCompanyOrigin.code
|
Numérico | Não | Código da empresa | |
integration.employee.reintegrationCompanyOrigin.name
|
Alfanumérico | Não | Nome da empresa | |
integration.employee.reintegrationEmployeeTypeOrigin
|
Enumeração | Não | Tipo do colaborador origem da reintegração | EMPLOYEE (Colaborador)THIRD (Terceiro)PARTNER (Parceiro) |
integration.employee.reintegrationCodeOrigin
|
Numérico | Não | Código origem da reintegração do colaborador | |
integration.companyName
|
Alfanumérico | Sim | Nome da empresa usado para localização rápida (filtro) de uma pendência de integração | |
integration.companyBranchCode
|
Numérico | Sim | Código da filial usado para localização rápida (filtro) de uma pendência de integração | |
integration.companyBranchName
|
Alfanumérico | Sim | Nome da filial usado para localização rápida (filtro) de uma pendência de integração | |
integration.employeeCode
|
Numérico | Sim | Código do colaborador usado para localização rápida (filtro) de uma pendência de integração | |
integration.eSocialRegistration
|
Alfanumérico | Não | Matrícula do colaborador no eSocial usado para localização rápida (filtro) de uma pendência de integração | |
integration.cpfNumber
|
Alfanumérico | Não | Número do CPF do colaborador usado para localização rápida (filtro) de uma pendência de integração | |
integration.employeeName
|
Alfanumérico | Sim | Nome do colaborador usado para localização rápida (filtro) de uma pendência de integração | |
integration.lotWorkstation
|
Alfanumérico | Não | Identificador (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
| Code | Description | |
|---|---|---|
200
|
Ok Valor de exemplo:
|
|
default
|
Error response Valor de exemplo:
|
Exemplo:
Execução no API Client:
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
|
|
Parâmetros de entrada
Cabeçalho (Header):
| Parâmetro | Valor |
|---|---|
Content-Type
|
application/json |
Authorization
|
Bearer Token |
Corpo (Body):
| Parâmetro | Tipo | Obrigatório | Descrição | Valores permitidos | ||
|---|---|---|---|---|---|---|
integrationId
|
Alfanumérico | Sim | ID da integração | |||
statusType
|
Enumeração | Sim | Status da integração |
|
||
errorMessage
|
Alfanumérico | Não | Mensagem de erro |
O objetivo da mensagem de erro é deixar claro para o cliente qual foi o problema e o que pode ser feito para corrigir. Assim, o cliente ganha autonomia para identificar qual ação deve tomar. Por isso, recomendamos que a mensagem enviada pelo seu sistema seja implementada com o seguinte formato:
Exemplo:
|
||
providerEmployeeIdentification
|
Alfanumérico | Não | ID único do colaborador no sistema do prestador. |
Este parâmetro permite encontrar o cadastro de um colaborador por meio de um identificador único do colaborador no sistema do prestador. O identificador único facilita a identificação do colaborador em pendências futuras enviadas pelo sistema da Senior, como, por exemplo, quando ocorre uma movimentação de empresa e filial com troca do cadastro desse colaborador no sistema. Caso o prestador queira receber o identificador único nas pendências futuras, ele precisa primeiro informar o ID este campo providerEmployeeIdentification na primitiva integrationUpdateStatus. |
Exemplo JSON:
|
{ "integrationId" : "a446b2e6-9a9e-46bf-934e-8375e319efd6", "statusType" : "ON_PROVIDER" "errorMessage" : "" "providerEmployeeIdentification" : "123456abc" } |
Resposta
| Code | Description | |
|---|---|---|
202
|
Ok Valor de exemplo:
|
|
default
|
Error response Valor de exemplo:
|
Exemplo:
Execução no API Client:
Eventos do eSocial (arquivos XML)
Passos para a integração:
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. 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:
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âmetro | Valor |
|---|---|
Content-Type
|
application/json |
Authorization
|
Bearer Token |
Corpo (Body):
| Parâmetro | Tipo | Obrigatório | Descrição | Valores permitidos |
|---|---|---|---|---|
providerXmlId
|
Alfanumérico | Sim | ID do XML no prestador SST | |
providerCompanyId
|
Alfanumérico | Sim | Código da empresa no prestador SST | |
subscriptionType
|
Alfanumérico | Sim | Tipo de inscrição da empresa | CNPJ
CPF
CAEPF
CNO
CEI
|
subscriptionNumber
|
Alfanumérico | Sim | Número de inscrição da empresa, sem máscara de formatação | |
xml
|
Alfanumérico | Sim | XML 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
| Code | Description | |||||||||||||||||
|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|
200
|
Resposta retornada pelo sistema da Senior:
Valor de exemplo:
|
|||||||||||||||||
default
|
Error response Valor de exemplo:
|
Exemplo:
Execução no API Client:
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âmetro | Valor |
|---|---|
Content-Type
|
application/json |
Authorization
|
Bearer Token |
Corpo (Body):
| Parâmetro | Tipo | Obrigatório | Descrição |
|---|---|---|---|
providerXmlId
|
Alfanumérico | Não | Identificador único do envio do XML no prestador SST |
id
|
Alfanumérico | Não | Identificador ú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
| Code | Description | |||||||||||||||||||||||||||||||||||||||||||||
|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|
200
|
Resposta retornada pelo sistema da Senior:
Valor de exemplo:
|
|||||||||||||||||||||||||||||||||||||||||||||
default
|
Error response Valor de exemplo:
|
Exemplos:
Execução no API Client:
Preenchimento dos parâmetros do cabeçalho (Header) da mensagem:
Evento validado com sucesso pelo sistema da Senior (VALIDATION_SUCCESS):
Evento validado com erro pelo sistema da Senior (VALIDATION_ERROR):
Evento em processo de envio para o Governo (SENDING_TO_GOVERNMENT):
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
|
|
Parâmetros
A pendência de integração é enviada pela plataforma da Senior com os parâmetros abaixo:
Cabeçalho (Header):
| Parâmetro | Observações |
|---|---|
Content-Type
|
Valor 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:
|
Corpo (Body):
| Code | Description | |||||||||||||||||||||||||||||||||||||||||||||
|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|
200
|
Resposta retornada pelo sistema da Senior:
Valor de exemplo:
|
|||||||||||||||||||||||||||||||||||||||||||||
default
|
Error response Valor de exemplo:
|
Resposta
| Code | Description | |
|---|---|---|
200
|
Ok Valor de exemplo:
|
|
default
|
Error response Valor de exemplo:
|
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âmetro | Valor |
|---|---|
Content-Type
|
application/json |
Authorization
|
Bearer Token |
Corpo (Body):
| Parâmetro | Tipo | Descrição | Observações | Valores permitidos |
|---|---|---|---|---|
providerXmlId
|
Alfanumérico | Identificador único do evento no prestador SST | Identificador único do evento do eSocial (XML) no prestador SST | |
providerStatusType
|
Enumeração | Situação da integração do status do evento do eSocial para o prestador SST | Situaçã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) |
providerErrorMessage
|
Alfanumérico | Mensagem de erro | Mensagem 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
| Code | Description | |
|---|---|---|
202
|
Ok Valor de exemplo:
|
|
default
|
Error response Valor de exemplo:
|
Exemplo:
Execução no API Client:
Indicação que o status do evento foi recebido com sucesso:
Indicação que houve problema no recebimento do status do evento:
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).
English
Español
