Desarrollar la API - Integrador SST ( v1 ) [obsoleto]
Estás viendo la documentación de una versión obsoleta del Integrador SST . Haga clic aquí para ver la documentación de la versión actual .
Esta documentación está destinada a desarrolladores de proveedores de SST que deseen crear una API para integrar y comunicarse entre el sistema del proveedor y el Integrador SST de Senior, y que también deseen acceder al entorno de aprobación y pruebas.
Usted necesitará desarrollar en el sistema del prestador los web services (REST) responsables por la comunicación con el sistema de Senior. Su API será responsable por integrar las pendencias de envío de las informaciones de empleados y de los eventos de SST del eSocial.
Para probar los servicios desarrollados usted puede usar cualquier API Client de su preferencia (esta documentación utiliza el Postman para fines de ejemplo).
Los conceptos y otra información (si es necesario) se encuentran en esta página .
Datos de los empleados
Pasos para la integración:
Paso 1 - Autenticación
El primer paso es implementar la autenticación con la plataforma de homologación de la Senior. Eso es hecho por el servicio loginWithKey, responsable por realizar el login en la plataforma con llave y secreto informados por el usuario.
Para obtener la llave y el secreto que serán usados en su implementación entre en contacto con la Senior pelo e-mail: integradorsst.devs@senior.com.br. Se trata de un canal de comunicación dirigido a promotores, respondiendo exclusivamente a cuestiones de carácter técnico y arquitectónico. Integrador SST .
Web service disponibilizado en la plataforma de la Senior: loginWithKey
|
|
Estructura de credenciales:
{ "accessKey": "XXX","secret": "XXX","tenantName": "XXX"}Ejemplo:
Ejecución en cliente API:
Paso 2 - Buscar las pendencias de integración de la plataforma de la Senior
Buscar, en el sistema de la Senior, las pendencias que aún no fueron integradas.
Web service disponibilizado en la plataforma de la Senior: retrieveSentIntegrationsQuery
|
|
Parámetros de entrada
Encabezamiento:
| Parámetro | Valor |
|---|---|
Content-Type
|
application/json |
Authorization
|
Bearer Token |
Cuerpo:
| Parámetro | Tipo | Obligatorio | Descripción | Valores permitidos |
|---|---|---|---|---|
pagination
|
Grupo de parámetros con la definición de la paginación de los registros - Opcional | |||
pagination.current
|
Numérico | Sí | Página actual de registros | |
pagination.size
|
Numérico | Sí | Cantidad de registros por página | |
pagination.orderBy
|
Grupo de parámetros con la definición de la ordenación - Opcional | |||
pagination.orderBy.field
|
Alfanumérico | Sí | Nombre del campo por el cual los registros serán ordenados | |
pagination.orderBy.direction
|
Enumeración | No | Orientación de la ordenación | ASC (Ascendente)DESC (Descendente) |
Ejemplo JSON:
|
{ "pagination": { "current": 0, "size": 10, "orderBy": [{ "field": "receiptDate", "direction": "ASC" }] } } |
Respuesta
| Code | Description | |
|---|---|---|
200
|
DE ACUERDO Valor de ejemplo:
|
|
default
|
Respuesta de error Valor de ejemplo:
|
Observación
Si la integración con el proveedor no está activa en la configuración del proveedor Integrador SST , la respuesta del servicio web no devolverá ninguna integración pendiente.
Ejemplo:
Ejecución en cliente API:
Paso 3 - Enviar la respuesta para la plataforma de la Senior
Enviar la respuesta para la plataforma de la Senior indicando si la integración ocurrió con éxito o con errores.
Web service disponibilizado en la plataforma de la Senior: integrationUpdateStatus
|
|
Parámetros de entrada
Encabezamiento:
| Parámetro | Valor |
|---|---|
Content-Type
|
application/json |
Authorization
|
Bearer Token |
Cuerpo:
| Parámetro | Tipo | Obligatorio | Descripción | Valores permitidos |
|---|---|---|---|---|
integrationId
|
Alfanumérico | Sí | ID de la integración | |
statusType
|
Enumeración | Sí | Estado de la integración | ON_PROVIDER (Recibido exitosamente por el proveedor)INTEGRATION_ERROR (Error al recibir la integración pendiente) |
errorMessage
|
Alfanumérico | No | Mensaje de error |
Ejemplo JSON:
|
{ "integrationId" : "a446b2e6-9a9e-46bf-934e-8375e319efd6", "statusType" : "ON_PROVIDER" "errorMessage" : "" } |
Respuesta
| Code | Description | |
|---|---|---|
202
|
DE ACUERDO Valor de ejemplo:
|
|
default
|
Respuesta de error Valor de ejemplo:
|
Ejemplo:
Ejecución en cliente API:
Importante
También existe la posibilidad de recibir los asuntos pendientes de integración en tiempo real, para ello sigue los pasos a continuación:Implemente este servicio para recibir las pendencias de integración de datos de los empleados a medida en que ocurran admisiones, movimientos o desvinculaciones en el sistema de la Senior.
En el caso que la confirmación del estado de la integración no sea enviada (Paso 3), el sistema de la Senior realizará más tres intentos de envío de la pendencia de integración al prestador, con intervalo de 10 minutos entre cada intento.
Web service disponibilizado en el prestador SST: pendency
|
|
Parámetros de entrada
La pendencia de integración es enviada por la plataforma de la Senior con los parámetros abajo:
Encabezamiento:
| Parámetro | Tipo | Descripción | Observaciones |
|---|---|---|---|
Content-Type
|
Alfanumérico | Especifica el tipo de contenido enviado. | Valor por defecto: application/json |
x-senior-key
|
Alfanumérico |
Llave de acceso de la empresa que envió la pendencia de integración. |
Llave de acceso de la empresa, referente a la pendencia de integración en la plataforma de la Senior. Esa llave identifica a cual empresa pertenece la pendencia. Ejemplo:
|
Cuerpo:
| Parámetro | Tipo | Obligatorio | Descripción | Valores permitidos |
|---|---|---|---|---|
integration.id
|
Alfanumérico | Sí | Identificador único de la pendencia de integración en la API | |
integration.externalId
|
Alfanumérico | Sí | Identificador de la pendencia de integración entre los sistemas | |
integration.externalHistoricId
|
Alfanumérico | No | Identificador anterior de la pendencia de integración entre los sistemas | |
integration.operationType
|
Enumeración | Sí | Tipo de operación | INSERT UPDATE DELETE |
integration.statusType
|
Enumeración | Sí | Estado de la pendencia de integración | SENT_TO_PROVIDER (Pendiente enviado al proveedor de SST)ON_PROVIDER (Pendiente recibido exitosamente por el proveedor de SST) |
integration.integrationType
|
Enumeración | Sí | Motivo de la integración | NEW_EMPLOYEE (Nuevo empleado)EMPLOYEE_CHANGE (Cambio de empleado)DISMISSAL HISTORICAL_COST_CENTER (Despido de empleados) HISTORICAL_DEPARTMENT (Historial del centro de costos) HISTORICAL_ESOCIAL_CATEGORY (Historial del departamento) HISTORICAL_JOB_POSITION (historial de categorías eSocial) HISTORICAL_WORKSTATION (Historial de trabajos) HISTORICAL_COMPANY_BRANCH (Historial de la estación de trabajo) (Historial de sucursales)HISTORICAL_WORKSHIFTHISTORICAL_COMPANY (historial de la empresa)HISTORICAL_LEAVE EMPLOYEE_ESOCIAL_REGISTRATION (Historial de escala) INITIAL_LOAD (Salir del historial) (Cambio de registro eSocial) (carga inicial) |
integration.receiptDate
|
Fecha | Sí | Fecha de creación de la pendencia de integración | |
integration.previewSendDate
|
Fecha | Sí | Fecha prevista para envío de la pendencia de integración | |
integration.scheduledDate
|
Fecha | Sí | Fecha de programación para envío de la pendencia de integración | |
integration.sendDate
|
Fecha | Sí | Fecha de envío de la pendencia de integración | |
integration.providerCompanyIdentification
|
Alfanumérico | Sí | Identificación de la empresa en el prestador SST | |
integration.providerPreviousCompanyIdentification
|
Alfanumérico | No | Identificación de la empresa anterior en el proveedor de SST (enviado si el empleado tiene algún traslado entre empresas en su historial) | |
integration.dateWhen
|
Ordenes de Producción/Servicio | Sí | Fecha de referencia de las informaciones del empleado | |
integration.integrationSequence
|
Numérico | No | Número secuencial de la integración | |
integration.cancelationReason
|
Alfanumérico | No | Motivo de la cancelación de la pendencia de integración | |
integration.integrationMessage
|
Alfanumérico | No | Observaciones de la integración | |
integration.stackTrace
|
Alfanumérico | No | Detalles de eventuales errores | |
integration.employee
|
Grupo de parámetros con datos del empleado - Obligatorio | |||
integration.employee.id
|
Alfanumérico | Sí | Identificador del empleado para el sistema de nómina de pago | |
integration.employee.externalId
|
Alfanumérico | Sí | Identificador del empleado para integraciones entre los sistemas | |
integration.employee.employeeType
|
Enumeración | Sí | Tipo del empleado | EMPLOYEE (Empleado)THIRD PARTNER (Tercero) |
integration.employee.code
|
Alfanumérico | Sí | Código del registro del empleado en el sistema de nómina | |
integration.employee.eSocialRegistration
|
Alfanumérico | No | Matrícula del eSocial | |
integration.employee.name
|
Alfanumérico | Sí | Nombre del empleado | |
integration.employee.cpfNumber
|
Numérico | No | Número del CPF* | |
integration.employee.nisNumber
|
Numérico | No | Número del NIS* | |
integration.employee.birthday
|
Fecha | No | Fecha de nacimiento | |
integration.employee.hireDate
|
Fecha | No | Fecha de admisión | |
integration.employee.dismissalDate
|
Fecha | No | Fecha de despido | |
integration.employee.maritalStatusType
|
Enumeración | No | Estado civil | SINGLE (Único)MARRIED DIVORCED (Casado) WIDOWERSEPARATED (Unión estable)STABLE_UNION OTHER (Otro tipo de estado civil) CONCUBINAGE |
integration.employee.genderType
|
Enumeración | No | Genero del empleado | MALE (Masculino)FEMALE (Mujer) |
integration.employee.situationType
|
Enumeración | Sí | Situación del empleado | WORKING VACATION FIRED (Despedido) AWAY (Licencia)LICENSE |
integration.employee.contractType
|
Enumeración | No | Tipo del contrato | EMPLOYEE (Empleado)MANAGER FARMWORKER (Director) RETIRED (Trabajador rural) TRAINEE (Retirado) APPRENTICE (Pasante) FIXEDDUEDATE (Aprendiz) RETIREDMANAGER DIRECTOR (Consejero jubilado)PUBLICAGENT TEACHER (Agente público) COOPERATIVEWORKER (Cooperador)DOMESTICWORKER TEACHERFIXEDDUEDATE (Trabajadora doméstica) (Profesor con plazo fijo) |
integration.employee.eSocialCategory
|
Grupo de parámetros con datos de la categoría eSocial* del empleado - Obligatorio | |||
integration.employee.eSocialCategory.id
|
Alfanumérico | Sí | Identificador único del registro | |
integration.employee.eSocialCategory.code
|
Enumeración | Sí | Categoría del empleado en el eSocial, conforme la Tabla 01 (Categorías de Trabajadores) |
Haga clic aquí para ver el listado de valores posibles |
integration.employee.eSocialCategory.dateWhen
|
Fecha | Sí | Fecha de inicio del empleado en la categoría eSocial* (A partir de) | |
integration.employee.isDeficient
|
Booleano | No | ¿Es el empleado una persona con discapacidad? | true false |
integration.employee.company
|
Grupo de parámetros con datos da empresa del empleado - Obligatorio | |||
integration.employee.company.id
|
Alfanumérico | Sí | Identificador único del registro | |
integration.employee.company.code
|
Numérico | Sí | Código de la empresa | |
integration.employee.company.name
|
Alfanumérico | Sí | Nombre de la empresa | |
integration.employee.previousCompany
|
Grupo de parámetros con datos de la empresa anterior del empleado (enviado si el empleado tiene algún traslado entre empresas en su historial) - Opcional | |||
integration.employee.previousCompany.id
|
Alfanumérico | Sí | Identificador único del registro | |
integration.employee.previousCompany.code
|
Numérico | Sí | Código de la empresa | |
integration.employee.previousCompany.name
|
Alfanumérico | Sí | Nombre de la empresa | |
integration.employee.companyBranch
|
Grupo de parámetros con datos de sucursal de empleado - Obligatorio |
|||
integration.employee.companyBranch.id
|
Alfanumérico | Sí | Identificador único del registro | |
integration.employee.companyBranch.code
|
Numérico | Sí | Código de la sucursal | |
integration.employee.companyBranch.companyBranchName
|
Alfanumérico | Sí | Nombre de la sucursal | |
integration.employee.companyBranch.name
|
Alfanumérico | Sim | Razón social de la sucursal | |
integration.employee.companyBranch.subscriptionType
|
Enumeración | Sí | Tipo de inscripción de la sucursal | CNPJ CPF CAEPF CNO CEI |
integration.employee.companyBranch.subscriptionNumber
|
Alfanumérico | Sí | Número de la inscripción | |
integration.employee.companyBranch.dateWhen
|
Fecha | Sí | Fecha de inicio del empleado en la sucursal (A partir de) | |
integration.employee.previousCompanyBranch
|
Grupo de parámetros con datos de la sucursal anterior del empleado (enviado si el empleado tiene alguna transferencia entre sucursales en su historial) - Opcional | |||
integration.employee.previousCompanyBranch.id
|
Alfanumérico | Sí | Identificador único del registro | |
integration.employee.previousCompanyBranch.code
|
Numérico | Sí | Código de la sucursal | |
integration.employee.previousCompanyBranch.companyBranchName
|
Alfanumérico | Sí | Nombre de la sucursal | |
integration.employee.previousCompanyBranch.name
|
Alfanumérico | Sim | Razón social de la sucursal | |
integration.employee.previousCompanyBranch.subscriptionType
|
Enumeración | Sí | Tipo de inscripción de la sucursal | CNPJ CPF CAEPF CNO CEI |
integration.employee.previousCompanyBranch.subscriptionNumber
|
Alfanumérico | Sí | Número de la inscripción | |
integration.employee.previousCompanyBranch.dateWhen
|
Fecha | Sí | Fecha de inicio del empleado en la sucursal (A partir de) | |
integration.employee.costCenter
|
Grupo de parámetros con datos del centro de costes de los empleados: opcional |
|||
integration.employee.costCenter.id
|
Alfanumérico | No | Identificador único del registro | |
integration.employee.costCenter.code
|
Alfanumérico | No | Código del centro de costo | |
integration.employee.costCenter.name
|
Alfanumérico | No | Nombre del centro de costo | |
integration.employee.costCenter.dateWhen
|
Fecha | No | Fecha de inicio del empleado en el centro de costo (A partir de) | |
integration.employee.department
|
Grupo de parámetros con datos del sector del empleado - Opcional |
|||
integration.employee.department.id
|
Alfanumérico | No | Identificador único del registro | |
integration.employee.department.code
|
Alfanumérico | No | Código del sector | |
integration.employee.department.structureCode
|
Numérico | No | Código de organigrama del sector | |
integration.employee.department.name
|
Alfanumérico | No | Nombre del sector | |
integration.employee.department.dateWhen
|
Fecha | No | Fecha de inicio del empleado en el sector (A partir de) | |
integration.employee.jobPosition
|
Grupo de parámetros con datos de posición de empleado - Opcional |
|||
integration.employee.jobPosition.id
|
Alfanumérico | No | Identificador único del registro | |
integration.employee.jobPosition.code
|
Alfanumérico | No | Código del cargo | |
integration.employee.jobPosition.structureCode
|
Alfanumérico | No | Código de la estructura de funciones | |
integration.employee.jobPosition.cboCode
|
Alfanumérico | No | Código del CBO del cargo | |
integration.employee.jobPosition.name
|
Alfanumérico | No | Nombre del cargo | |
integration.employee.jobPosition.dateWhen
|
Fecha | No | Fecha de inicio del empleado en el cargo (A partir de) | |
integration.employee.shift
|
Grupo de parámetros con datos de turnos de empleados: opcional |
|||
integration.employee.shift.id
|
Alfanumérico | No | Identificador único del registro | |
integration.employee.shift.code
|
Numérico | No | Código del turno | |
integration.employee.shift.name
|
Alfanumérico | No | Nombre del turno | |
integration.employee.shift.dateWhen
|
Fecha | No | Fecha de inicio del empleado en el turno (A partir de) | |
integration.employee.workstation
|
Grupo de parámetros con datos del puesto de trabajo del empleado - Opcional |
|||
integration.employee.workstation.id
|
Alfanumérico | No | Identificador único del registro | |
integration.employee.workstation.code
|
Alfanumérico | No | Código de posición de trabajo | |
integration.employee.workstation.structureCode
|
Numérico | No | Estructura de posición de trabajo | |
integration.employee.workstation.name
|
Alfanumérico | No | Nombre de posición de trabajo | |
integration.employee.workstation.dateWhen
|
Fecha | No | Fecha de inicio del empleado en el puesto de trabajo (A partir de) | |
integration.employee.reasonLeave
|
Grupo de parámetros con datos del motivo de la ausencia del empleado - Opcional |
|||
integration.employee.reasonLeave.id
|
Alfanumérico | No | Identificador único del registro | |
integration.employee.reasonLeave.code
|
Numérico | No | Código del motivo de alejamiento (sistema de la Senior) | |
integration.employee.reasonLeave.name
|
Alfanumérico | No | Estructura del motivo | |
integration.employee.reasonLeave.startDate
|
Fecha | No | Fecha del inicio del alejamiento | |
integration.employee.reasonLeave.estimatedEndDate
|
Fecha | No | Fecha de previsión de término del alejamiento | |
integration.employee.reasonLeave.endDate
|
Fecha | No | Fecha del termino del ausentismo | |
integration.employee.deficiencies
|
Lista de deficiencias de los empleados - Opcional |
|||
integration.employee.deficiencies.id
|
Alfanumérico | No | Identificador único del registro | |
integration.employee.deficiencies.code
|
Numérico | No | Código de la deficiencia | |
integration.employee.deficiencies.name
|
Alfanumérico | No | Nombre de la deficiencia | |
integration.employee.deficiencies.isMainDeficiency
|
Booleano | No | ¿Es la deficiencia principal? | true false |
integration.employee.deficiencies.deficiencyType
|
Enumeración | No | Tipo de la deficiencia en el eSocial | PHYSICAL (Física)AUDITORY VISUAL (VISUALES)MENTAL INTELLECTUAL (mental) OTHER (Intelectual) (Otro tipo de discapacidad) |
integration.employee.deficiencies.dateWhen
|
Fecha | No | Fecha de inicio de la deficiencia | |
integration.employee.deficiencies.isRehabilitated
|
Booleano | No | Rehabilitado | true false |
integration.employee.deficiencies.employee
|
Alfanumérico | No | Identificador único del empleado | |
integration.employee.ctpsNumber
|
Alfanumérico | No | Número de la libreta laboral | |
integration.employee.ctpsSerie
|
Alfanumérico | No | Serie de la libreta laboral | |
integration.employee.ctpsIssuanceDate
|
Fecha | No | Fecha de la emisión de la libreta laboral | |
integration.employee.ctpsSerieDigit
|
Alfanumérico | No | Dígito de la libreta laboral | |
integration.employee.ctpsState
|
Enumeración | No | Estado (UF) de la libreta laboral | 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 | No | Cédula de Identidad | |
integration.employee.rgIssuer
|
Alfanumérico | No | Órgano emisor de la cédula de identidad | |
integration.employee.rgState
|
Enumeración | No | Estado (UF) de emisión de la cédula de identidad | 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
|
Fecha | No | Fecha de emisión de la cédula de identidad | |
integration.employee.numberContractSameHireDate
|
Numérico | No | Número de contratos de empleados | |
integration.companyName
|
Alfanumérico | Sí | Nombre de la empresa usado para localización rápida (filtro) de una pendencia de integración | |
integration.companyBranchCode
|
Numérico | Sí | Código de la sucursal usado para localización rápida (filtro) de una pendencia de integración | |
integration.companyBranchName
|
Alfanumérico | Sí | Nombre de la sucursal usado para localización rápida (filtro) de una pendencia de integración | |
integration.employeeCode
|
Numérico | Sí | Código del empleado usado para localización rápida (filtro) de una pendencia de integración | |
integration.eSocialRegistration
|
Alfanumérico | No | Matrícula del empleado en el eSocial usado para localización rápida (filtro) de una pendencia de integración | |
integration.cpfNumber
|
Alfanumérico | No | Número del CPF* del empleado usado para localización rápida (filtro) de una pendencia de integración | |
integration.employeeName
|
Alfanumérico | Sí | Nombre del empleado usado para localización rápida (filtro) de una pendencia de integración | |
integration.lotWorkstation
|
Alfanumérico | No | Identificador (lote) de alteraciones de historiales ocasionadas por cambio de puesto de trabajo | |
Ejemplo 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": "Demostrar Ind.& Com. Textil 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": "Administración", "dateWhen": "2019-01-01", "_discriminator": "department" }, "jobPosition": { "id": "e6afbaf2-1482-4883-86bf-c10e4f8857bb", "code": "29", "structureCode": "1", "cboCode": "241005", "name": "Abogado", "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": "Abogado", "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": "Demostrar Ind.& Com. Textil 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 } } |
Respuesta
| Code | Description | |
|---|---|---|
200
|
DE ACUERDO Valor de ejemplo:
|
|
default
|
Respuesta de error Valor de ejemplo:
|
Ejemplo:
Ejecución en cliente API:
Eventos del eSocial (archivos XML)
Pasos para la integración:
Paso 1 - Autenticación
El primer paso es implementar la autenticación con la plataforma de homologación de la Senior. Eso es hecho por el servicio loginWithKey, responsable por realizar el login en la plataforma con llave y secreto informados por el usuario.
Para obtener la llave y el secreto que serán usados en su implementación entre en contacto con la Senior pelo e-mail: integradorsst.devs@senior.com.br. Se trata de un canal de comunicación dirigido a promotores, respondiendo exclusivamente a cuestiones de carácter técnico y arquitectónico. Integrador SST .
Web service disponibilizado en la plataforma de la Senior: loginWithKey
URL:
|
|
Estructura de credenciales:
{ "accessKey": "XXX","secret": "XXX","tenantName": "XXX"}Ejemplo:
Ejecución en cliente API:
Paso 2 - Enviar los eventos del eSocial (XML) para la plataforma de la Senior
Enviar los eventos del eSocial (XML) para la Senior. Los archivos XML deben ser enviados individualmente (uno a un) del prestador para Senior.
Cada XML enviado es validado, conforme estructura y atributos de su layout, antes de ser enviado al Gobierno. Caso o XML esteja inválido, él no será considerado para envío al eSocial.
Web service disponibilizado en la plataforma de la Senior: esocialEventXml
|
|
Parámetros de entrada
Encabezamiento:
| Parámetro | Valor |
|---|---|
Content-Type
|
application/json |
Authorization
|
Bearer Token |
Cuerpo:
| Parámetro | Tipo | Obligatorio | Descripción | Valores permitidos |
|---|---|---|---|---|
esocialEventXmlInput.providerXmlId
|
Alfanumérico | No | ID do XML en el prestador SST | |
esocialEventXmlInput.providerCompanyId
|
Alfanumérico | No | Código de la empresa en el prestador SST | |
esocialEventXmlInput.subscriptionType
|
Alfanumérico | No |
Tipo de inscripción de la empresa |
CNPJ CPF CAEPF CNO CEI |
esocialEventXmlInput.subscriptionNumber
|
Alfanumérico | No | Número de inscripción de la empresa, sin máscara de formatación | |
esocialEventXmlInput.xml
|
Alfanumérico | Sí | XML del evento del eSocial, sin quiebras de líneas |
Ejemplo 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\"> <ideEvent> <indRetif>1</indRetif> <tpAmb>2</tpAmb> <procEmi>1</procEmi> <verProc>6.2.0</verProc> </ideEvent> <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> <exam> <dtExm>2020-07-01</dtExm> <procRealized>0001</procRealized> <ordExame>1</ordExame> </exame> <médico> <nmMed>prueba</nmMed> <nrCRM>1231213</nrCRM> <ufCRM>AC</ufCRM> </doctor> </aso> </exMedOcup> </evtMonit></eSocial>" } |
Respuesta
| Code | Description | |||||||||||||||||||||||||||||||||||||
|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|
200
|
Respuesta devuelta por el sistema Senior:
Valor de ejemplo:
|
|||||||||||||||||||||||||||||||||||||
default
|
Respuesta de error Valor de ejemplo:
|
Ejemplo:
Ejecución en cliente API:
Paso 3 - Buscar el estado de los eventos (XML) de la plataforma de la Senior
Buscar los estados de los eventos (XML) que fueron enviados al sistema de la Senior.
Web service disponibilizado en la plataforma de la Senior: providerXml
|
|
La inclusión del parámetro providerXml en la URL permite filtrar las pendencias por el número identificador del XML en el prestador.
Ejemplo: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
Encabezamiento:
| Parámetro | Valor |
|---|---|
Authorization
|
Bearer Token |
Respuesta
| Code | Description | |||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||
|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|
200
|
Respuesta devuelta por el sistema Senior:
Valor de ejemplo:
|
|||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||
default
|
Respuesta de error Valor de ejemplo:
|
Ejemplo:
Ejecución en cliente API:
Llenado de los parámetros del encabezado (Header) del mensaje:
Evento validado con éxito por el sistema de la Senior:
Evento validado con error por el sistema de la Senior:
Aguardando envío del evento del sistema de la Senior para el Gobierno:
Paso 4 - Enviar respuesta para la plataforma de la Senior indicando el recibimiento del estado
Enviar la respuesta para la plataforma de la Senior indicando si los estados de los eventos del eSocial (XML) fueron recibidos con éxito o con errores en el sistema del prestador.
Web service disponibilizado en la plataforma de la Senior: xmlUpdateStatus
|
|
Parámetros de entrada
Encabezamiento:
| Parámetro | Valor |
|---|---|
Content-Type
|
application/json |
Authorization
|
Bearer Token |
Cuerpo:
| Parámetro | Tipo | Descripción | Observaciones | ||||
|---|---|---|---|---|---|---|---|
providerXmlId
|
Alfanumérico | Identificador único del evento en el prestador SST | Identificador único del evento del eSocial (XML) en el prestador SST | ||||
providerStatusType
|
Enumeración | Situación de la integración del estado del evento del eSocial para el prestador SST |
Situación del estado del evento del eSocial en relación al prestador SST. Valores posibles:
|
||||
providerErrorMessage
|
Alfanumérico | Mensaje de error | Mensaje de error enviado para la plataforma de la Senior con el motivo del problema en el recibimiento de la situación del evento por el prestador SST. |
Ejemplo JSON:
Indicación que el estado del evento fue recibido con éxito:
|
{ "providerXmlId": "123456789", "providerStatusType" : "ON_PROVIDER", "providerErrorMessage" : "" } |
Indicación que hubo problema en el recibimiento del estado del evento:
|
{ "providerXmlId": "123456789", "providerStatusType" : "PROVIDER_ERROR", "providerErrorMessage" : "No fue posible integrar el estado del evento del eSocial por indisponibilidad del servicio del sistema del prestador SST." } |
Respuesta
| Code | Description | |
|---|---|---|
202
|
DE ACUERDO Valor de ejemplo:
|
|
default
|
Respuesta de error Valor de ejemplo:
|
Ejemplo:
Ejecución en cliente API:
Indicación que el estado del evento fue recibido con éxito:
Indicación que hubo problema en el recibimiento del estado del evento:
Importante
También es posible recibir el estado del evento (XML) en tiempo real. Para hacer esto, debe seguir estos pasos:Implemente este servicio para recibir las actualizaciones del estado de los eventos del eSocial (XML) a medida en que ellas ocurren en el sistema de la Senior. Por ejemplo, cuando el Gobierno retorna para la Senior el recibo o las críticas del evento del eSocial.
Web service disponibilizado en el prestador SST: statusIntegration
|
|
Parámetros de entrada
La pendencia de integración es enviada por la plataforma de la Senior con los parámetros abajo:
Encabezamiento:
| Parámetro | Tipo | Descripción | Observaciones |
|---|---|---|---|
Content-Type
|
Alfanumérico | Especifica el tipo de contenido enviado | Valor por defecto: application/json |
x-senior-key
|
Alfanumérico | Llave de acceso de la empresa que envió la pendencia de integración |
Llave de acceso de la empresa referente a la pendencia de integración en la plataforma de la Senior. Esa llave identifica a cual empresa pertenece la pendencia. Ejemplo:
|
Cuerpo:
| Parámetro | Tipo | Obligatorio | Descripción | Valores permitidos |
|---|---|---|---|---|
result.id
|
Alfanumérico | No | Identificador único del registro | |
result.xml
|
XML | Sí | XML string | |
result.xmlStatus
|
Enumeración | Sí | Estado del XML | IN_ANALYSIS (en validación en el sistema Senior)VALIDATION_SUCCESS (validado por Senior y ok para enviar al Gobierno)VALIDATION_ERROR (validado por Senior y presentó errores en XML)GOVERNMENT_RETURN (retorno del Gobierno después recibir el evento - recibo (éxito) o críticas (error)) |
result.providerStatusType
|
Enumeración | Sí | Situación del consumo del estado del XML por el prestador | ON_PROVIDER (Recibido por el proveedor de SST)SENT_TO_PROVIDER PROVIDER_ERROR (Enviado al proveedor de SST) (Error del proveedor) |
result.layoutSituation
|
Grupo de parámetros con datos sobre la situación del diseño eSocial - Opcional |
|||
result.layoutSituation.id
|
Alfanumérico | No | Identificador único del registro | |
result.layoutSituation.layoutId
|
Alfanumérico | Sí | Identificador del layout | |
result.layoutSituation.eventId
|
Alfanumérico | Sí | Identificador del evento | |
result.layoutSituation.eventDate
|
Fecha | Sí | Fecha y hora del evento | |
result.layoutSituation.layoutType
|
Enumeración | Sí | Tipo del layout | SXXXX (donde "XXXX" equivale al número del layout. Ejemplo: S2240 caso se refiera al layout S-2240) |
result.layoutSituation.layoutSourceType
|
Enumeración | Sí | Origen del layout | TYPED IMPORTED SENIOR_G6 (Sistema G6 superior) SENIOR_4W (Sistema superior de 4W) THIRD_PARTY_INTEGRATION (Sistema externo) |
result.layoutSituation.operationType
|
Enumeración | No | Tipo de operación | INSERT (Inclusión de diseño)UPDATE DELETE (actualización de diseño) (eliminación de diseño) |
result.layoutSituation.statusType
|
Enumeración | Sí | Estado del layout | WAITING_MANUAL_SUBMISSION (Esperando envío manual)WAITING_AUTOMATIC_SUBMISSION (Aguardando envío automático)WAITING_GOVERNMENT_RETURN (Esperando respuesta del Gobierno)RECEIPT_RETURNED (Recibo retornado con éxito)RECEIPT_MANUAL (Recibo informado manualmente)EDOC_ERROR (Error en el mensajero de eventos)SENDING_TO_GOVERNMENT (Envío de evento al Gobierno)MESSAGE_RETURNED (Mensaje devuelto por el Gobierno)EVENT_DELETED (Error tratado (evento excluido))EVENT_CANCELED (Evento cancelado)INTEGRATING (Integrando/tramitando el asunto pendiente)CANCEL_REGENERATED (pendiente de regeneración)EDOC_SUBMISSION_ERROR (Error al enviar el evento eSocial al messenger)EDOC_RETURN_FETCHING_ERROR (Error al buscar el regreso del evento eSocial del messenger) |
result.layoutSituation.layoutSituationMessage
|
Alfanumérico | No | Mensaje de error en el procesamiento | |
result.layoutSituation.layoutSituationStackTrace
|
Alfanumérico | No | StackTrace del error en el procesamiento | |
result.layoutSituation.layoutMessage
|
Alfanumérico | No | Mensaje del layout (error o retorno del gobierno) | |
result.layoutSituation.receiptNumber
|
Alfanumérico | No | Número del recibo | |
result.layoutSituation.registrationNumber
|
Alfanumérico | No | Número de matrícula | |
result.layoutSituation.employerDocumentNumber
|
Alfanumérico | Sí | CPF*/CNPJ* del empleador | |
result.layoutSituation.employeeDocumentNumber
|
Alfanumérico | No | CPF* del Trabajador | |
result.layoutSituation.subscriptionType
|
Enumeración | Sí | Código correspondiente al tipo de inscrip. | CNPJ (1 - CNPJ)CPF CAEPF (2 - FCP) CNO (3 - CAEPF (Registro de Actividad Económica de las Personas Físicas)) (4 - CNO (Registro Nacional de Obras)) |
result.layoutSituation.environmentIdType
|
Enumeración | Sí | Tipo de ambiente | EMPLOYER (1 - Establecimiento del propio empleador)THIRD SERVICE (2 - Establecimiento de terceros) (3 - Prestación de servicios en instalaciones de terceros) |
result.layoutSituation.priority
|
Numérico | Sí | Prioridad de envío | |
result.stackTrace
|
Alfanumérico | No | Stacktrace | |
result.message
|
Alfanumérico | No | Mensaje | |
result.idEvento
|
Alfanumérico | No | Identificador único del evento | |
result.layoutType
|
Enumeración | No | Tipo de layout | SXXXX (donde "XXXX" equivale al número del layout. Ejemplo: S2240 caso se refiera al layout S-2240) |
result.receiptDate
|
Ordenes de Producción/Servicio | Sí | Fecha de recibimiento | |
result.providerCompanyId
|
Alfanumérico | No | Identificador único de la empresa en el prestador SST | |
result.subscriptionType
|
Enumeración | No | Tipo de Inscripción | CNPJ (1 - CNPJ)CPF CAEPF (2 - FCP) CNO (3 - CAEPF (Registro de Actividad Económica de las Personas Físicas)) (4 - CNO (Registro Nacional de Obras)) |
result.subscriptionNumber
|
Alfanumérico | No | Número de Inscripción | |
result.providerXmlId
|
Alfanumérico | No | Identificador único del XML del prestador | |
result.providerErrorMessage
|
Alfanumérico | No | Informe de error ocurrido en el proveedor | |
Ejemplo JSON:
|
{ "result": { "id": "a7b1df6c-2d8d-4770-9191-1fa6558a306e", "xml": "XML del layout del 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 } } |
Respuesta
| Code | Description | |
|---|---|---|
200
|
DE ACUERDO Valor de ejemplo:
|
|
default
|
Respuesta de error Valor de ejemplo:
|
Ejemplo:
Ejecución en cliente API:
Proyecto de plantilla
El uso del proyecto template facilita la implementación, pues él trae todas las rutinas necesarias para la comunicación entre los sistemas. Simplemente descargue el proyecto desde GitHub. y cámbielo según sus necesidades, basándose en esta documentación. El desarrollo de su propia solución es una alternativa para los casos donde no es posible usar la plantilla.
Ponemos a disposición el proyecto (Undefined variable: integrador-sst.projeto template) disponible en GitHub lo cual facilita la implementación de la API en Java, pero también presentamos esta alternativa para situaciones donde el desarrollador quiera crear una solución utilizando otros lenguajes de programación.
Entorno de aprobación
Después de implementar la API, es posible acceder al entorno de aprobación y prueba.
¿Dudas?
En el caso que aún tenga algún cuestionamiento sobre el desarrollo de esta API entre en contacto con la Senior a través del e-mail: integradorsst.devs@senior.com.br.
Se trata de un canal de comunicación dirigido a promotores, respondiendo exclusivamente a cuestiones de carácter técnico y arquitectónico. Integrador SST . Antes de entrar en contacto es importante haber hecho la lectura de todas las orientaciones y ejemplos disponibles en esta documentación.
Otros asuntos, comerciales o de negocio, deben ser encaminados para los canales apropiados de la Senior.
English
Español
