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).
Clique aqui para saber mais sobre os conceitos da API, 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 - Buscar as pendências de integração da plataforma da Senior
Buscar, 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:
Nota O campo |
|
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:
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:
Opcional: receber as pendências de integração em tempo real
Também existe a possibilidade de 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.
Caso a confirmação do status da integração não seja enviada (Passo 3), 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 | 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)EMPLOYEE_ESOCIAL_REGISTRATION (Alteração da matrícula eSocial)INITIAL_LOAD (Carga inicial) |
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.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" }, "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:
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 - Buscar o status dos eventos (XML) da plataforma da Senior
Buscar 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):
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:
Opcional: receber os status dos eventos (XML) em tempo real
Também é possível 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:
|
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.
Any questions?
If you still have any doubts about the development of this API, contact Senior at integradorsst.devs@senior.com.br.
This is a communication channel geared towards developers, exclusively answering questions of a technical nature and regarding the OSH Integrator architecture. Before contacting, please read all guidelines and examples available in this documentation.
Other subjects, such as commercial or business subjects, must be sent to the proper Senior channels.
Esta é a documentação da versão mais atual desta API. Clique aqui se quiser consultar a documentação da versão anterior (deprecada).
English
Español
