Desenvolver a API - Integrador SST (v1) [deprecado]
Você está vendo a documentação de uma versão deprecada da API do Integrador SST. Clique aqui para ver a documentação da versão atual.
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).
Conceitos e demais informações (caso necessário) seguem nessa página.
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.
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:
|
|
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 | ON_PROVIDER (Recebido com sucesso pelo prestador)INTEGRATION_ERROR (Erro no recebimento da pendência de integração) |
errorMessage
|
Alfanumérico | Não | Mensagem de erro |
Exemplo JSON:
|
{ "integrationId" : "a446b2e6-9a9e-46bf-934e-8375e319efd6", "statusType" : "ON_PROVIDER" "errorMessage" : "" } |
Resposta
| Code | Description | |
|---|---|---|
202
|
Ok Valor de exemplo:
|
|
default
|
Error response Valor de exemplo:
|
Exemplo:
Execução no API Client:
Importante
Também existe a possibilidade de receber as pendências de integração em tempo real, para isso siga os passos abaixo: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 de entrada
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 | |
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 | 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 é uma pessoa com deficiência? | true
false
|
integration.employee.company
|
Grupo de parâmetros com dados da empresa 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 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
CPF
CAEPF
CNO
CEI
|
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
CPF
CAEPF
CNO
CEI
|
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.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", "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: esocialEventXml
|
|
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 |
|---|---|---|---|---|
esocialEventXmlInput.providerXmlId
|
Alfanumérico | Não | ID do XML no prestador SST | |
esocialEventXmlInput.providerCompanyId
|
Alfanumérico | Não | Código da empresa no prestador SST | |
esocialEventXmlInput.subscriptionType
|
Alfanumérico | Não |
Tipo de inscrição da empresa |
CNPJ
CPF
CAEPF
CNO
CEI
|
esocialEventXmlInput.subscriptionNumber
|
Alfanumérico | Não | Número de inscrição da empresa, sem máscara de formatação | |
esocialEventXmlInput.xml
|
Alfanumérico | Sim | XML do evento do eSocial, sem quebras de linhas |
Exemplo JSON:
|
{ "providerXmlId" : "123456789", "providerCompanyId" : "102030", "subscriptionType" : "CNPJ", "subscriptionNumber" : "12345678", "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.
Web service disponibilizado na plataforma da Senior: providerXml
|
|
A inclusão do parâmetro providerXml na URL permite filtrar as pendências pelo número identificador do XML no prestador.
Exemplo:https://platform-homologx.senior.com.br:8243/t/senior.com.br/bridge/1.0/rest/hcm/esocial/entities/providerXml?filter=providerXmlId eq '123456789'
Parâmetros de entrada
Cabeçalho (Header):
| Parâmetro | Valor |
|---|---|
Authorization
|
Bearer Token |
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:
Preenchimento dos parâmetros do cabeçalho (Header) da mensagem:
Evento validado com sucesso pelo sistema da Senior:
Evento validado com erro pelo sistema da Senior:
Aguardando envio do evento do sistema da Senior para o Governo:
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: xmlUpdateStatus
|
|
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 | ||||
|---|---|---|---|---|---|---|---|
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. Valores possíveis:
|
||||
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:
Importante
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 de entrada
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 |
|---|---|---|---|---|
result.id
|
Alfanumérico | Não | Identificador único do registro | |
result.xml
|
XML | Sim | XML string | |
result.xmlStatus
|
Enumeração | Sim | Status do XML | IN_ANALYSIS (em validação no sistema Senior)VALIDATION_SUCCESS (validado pela Senior e ok para enviar ao Governo)VALIDATION_ERROR (validado pela Senior e apresentou erros no XML)GOVERNMENT_RETURN (retorno do Governo após receber o evento - recibo (sucesso) ou críticas (erro)) |
result.providerStatusType
|
Enumeração | Sim | Situação do consumo do status do XML pelo prestador | ON_PROVIDER (Recebido pelo prestador SST)SENT_TO_PROVIDER (Enviado ao prestador SST)PROVIDER_ERROR (Erro no provedor) |
result.layoutSituation
|
Grupo de parâmetros com dados da situação do layout do eSocial - Opcional |
|||
result.layoutSituation.id
|
Alfanumérico | Não | Identificador único do registro | |
result.layoutSituation.layoutId
|
Alfanumérico | Sim | Identificador do layout | |
result.layoutSituation.eventId
|
Alfanumérico | Sim | Identificador do evento | |
result.layoutSituation.eventDate
|
Data | Sim | Data e hora do evento | |
result.layoutSituation.layoutType
|
Enumeração | Sim | Tipo do layout | SXXXX (onde "XXXX" equivale ao número do layout. Exemplo: S2240 caso se refira ao leiaute S-2240) |
result.layoutSituation.layoutSourceType
|
Enumeração | Sim | Origem do layout | TYPED (Digitado)IMPORTED (Importado)SENIOR_G6 (Sistema Senior G6)SENIOR_4W (Sistema Senior 4W)THIRD_PARTY_INTEGRATION (Sistema externo) |
result.layoutSituation.operationType
|
Enumeração | Não | Tipo da operação | INSERT (Inclusão de layout)UPDATE (Atualização de layout)DELETE (Remoção do layout) |
result.layoutSituation.statusType
|
Enumeração | Sim | Status do layout | WAITING_MANUAL_SUBMISSION (Aguardando envio manual)WAITING_AUTOMATIC_SUBMISSION (Aguardando envio automático)WAITING_GOVERNMENT_RETURN (Aguardando retorno do Governo)RECEIPT_RETURNED (Recibo retornado com sucesso)RECEIPT_MANUAL (Recibo informado manualmente)EDOC_ERROR (Erro no mensageiro do evento)SENDING_TO_GOVERNMENT (Enviando evento para o Governo)MESSAGE_RETURNED (Mensagem retornada do Governo)EVENT_DELETED (Erro tratado (evento excluído))EVENT_CANCELED (Evento cancelado)INTEGRATING (Integrando/processando a pendência)CANCEL_REGENERATED (Pendência regerada)EDOC_SUBMISSION_ERROR (Erro ao enviar o evento do eSocial para o mensageiro)EDOC_RETURN_FETCHING_ERROR (Erro ao buscar o retorno do evento do eSocial do mensageiro) |
result.layoutSituation.layoutSituationMessage
|
Alfanumérico | Não | Mensagem de erro no processamento | |
result.layoutSituation.layoutSituationStackTrace
|
Alfanumérico | Não | StackTrace do erro no processamento | |
result.layoutSituation.layoutMessage
|
Alfanumérico | Não | Mensagem do layout (erro ou retorno do governo) | |
result.layoutSituation.receiptNumber
|
Alfanumérico | Não | Número do recibo | |
result.layoutSituation.registrationNumber
|
Alfanumérico | Não | Número de matrícula | |
result.layoutSituation.employerDocumentNumber
|
Alfanumérico | Sim | CPF/CNPJ do empregador | |
result.layoutSituation.employeeDocumentNumber
|
Alfanumérico | Não | CPF do trabalhador | |
result.layoutSituation.subscriptionType
|
Enumeração | Sim | Código correspondente ao tipo de inscrição | CNPJ (1 - CNPJ)CPF (2 - CPF)CAEPF (3 - CAEPF (Cadastro de Atividade Econômica de Pessoa Física))CNO (4 - CNO (Cadastro Nacional de Obra)) |
result.layoutSituation.environmentIdType
|
Enumeração | Sim | Tipo de ambiente | EMPLOYER (1 - Estabelecimento do próprio empregador)THIRD (2 - Estabelecimento de terceiros)SERVICE (3 - Prestação de serviços em instalações de terceiros) |
result.layoutSituation.priority
|
Numérico | Sim | Prioridade de envio | |
result.stackTrace
|
Alfanumérico | Não | Stacktrace | |
result.message
|
Alfanumérico | Não | Mensagem | |
result.idEvento
|
Alfanumérico | Não | Identificador único do evento | |
result.layoutType
|
Enumeração | Não | Tipo de layout | SXXXX (onde "XXXX" equivale ao número do layout. Exemplo: S2240 caso se refira ao leiaute S-2240) |
result.receiptDate
|
Data | Sim | Data de recebimento | |
result.providerCompanyId
|
Alfanumérico | Não | Identificador único da empresa no prestador SST | |
result.subscriptionType
|
Enumeração | Não | Tipo de inscrição | CNPJ (1 - CNPJ)CPF (2 - CPF)CAEPF (3 - CAEPF (Cadastro de Atividade Econômica de Pessoa Física))CNO (4 - CNO (Cadastro Nacional de Obra)) |
result.subscriptionNumber
|
Alfanumérico | Não | Número de inscrição | |
result.providerXmlId
|
Alfanumérico | Não | Identificador único do XML do prestador | |
result.providerErrorMessage
|
Alfanumérico | Não | Relatório de erro ocorrido no provedor | |
Exemplo JSON:
|
{ "result": { "id": "a7b1df6c-2d8d-4770-9191-1fa6558a306e", "xml": "XML do leiaute do eSocial", "xmlStatus": "VALIDATION_SUCCESS", "providerStatusType": "ON_PROVIDER", "layoutSituation": { "id": "306c4c5e-8376-4ba4-bf25-6a78a0b77733", "layoutId": "01a7355c-e661-4198-8653-511c3d723243", "eventId": "ID1248926420001002019061707564900000", "eventDate": "2019-01-01T00:00:00Z", "layoutType": "S1060", "layoutSourceType": "TYPED", "operationType": "INSERT", "statusType": "WAITING_GOVERNMENT_RETURN", "layoutMessage": null, "receiptNumber": null, "registrationNumber": null, "employerDocumentNumber": "39659157000169", "employeeDocumentNumber": "68334152345", "subscriptionType": "CNPJ", "environmentIdType": "PRODUCTION", "priority": 1 }, "stackTrace": null, "message": null, "idEvento": "ID1248926420001002019061707564900000", "layoutType": "S1060", "receiptDate": "2019-01-01T00:00:00Z", "providerCompanyId": "123456", "subscriptionType": "CNPJ", "subscriptionNumber": "39659157000169", "providerXmlId": "999", "providerErrorMessage": null } } |
Resposta
| Code | Description | |
|---|---|---|
200
|
Ok Valor de exemplo:
|
|
default
|
Error response Valor de exemplo:
|
Exemplo:
Execução no API Client:
Projeto Template
O uso do projeto template facilita a implementação, pois ele traz todas as rotinas necessárias para a comunicação entre os sistemas. Basta fazer o download do projeto no GitHub e alterá-lo de acordo com as suas necessidades, com base nesta documentação. O desenvolvimento da sua própria solução é uma alternativa para os casos onde não é possível usar o template.
Disponibilizamos o projeto sst-consumer-example disponível no GitHub que facilita a implementação da API em Java, porém apresentamos também esta alternativa para situações onde o desenvolvedor deseja criar uma solução utilizando outras linguagens de programação.
Ambiente de homologação
Após a implementação da API, é possível realizar o acesso ao ambiente de homologação e testes.
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.
English
Español
