English
Español
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.
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.
English
Español
