Desarrollar la API - Integrador SST ( v2 )
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).
Visite la documentación de conceptos de API para obtener información adicional o continúe en esta página para obtener documentación de referencia de terminales.
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: obtenga problemas de integración de plataforma senior
Cada problema de integración tiene una razón de generarse. El motivo de la cuestión pendiente determina el tipo de integración .
El tipo de integración se identifica por el parámetro integrationType , presente en la respuesta o envío de algunas solicitudes.
Para saber qué tipos de integración existen y qué acción se espera del sistema del proveedor de SST para cada tipo, acceda a la documentación de tipos de integración (integrationType) .
Hay dos formas de obtener problemas de integración de plataforma Senior. Puede elegir una de las opciones que se describen a continuación:
2.1) Buscar asuntos pendientes periódicamente (opción 1)
La primera opción es que el sistema del proveedor busque cada cierto tiempo, en el sistema Senior, temas pendientes que aún no han sido integrados.
Es necesario implementar la búsqueda de registros de la plataforma senior X con undescanso mínimo de 3 minutos entre cada llamada de servicio web.
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 (Ascendiente)DESC (Descendiente) |
Ejemplo JSON:
|
{ "pagination": { "current": 0, "size": 10, "orderBy": [{ "field": "receiptDate", "direction": "ASC" }] } } |
Respuesta
| Code | Description | |
|---|---|---|
200
|
DE ACUERDO Valor de ejemplo:
Notas
|
|
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:
2.2) Recibir problemas de integración en tiempo real (opción 2)
La segunda opción es recibir los problemas de integración en tiempo real . Para esto necesitas seguir estos pasos:
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.
Al recibir la integración de datos, el sistema del proveedor debe enviar confirmación del estado de la integración ( Paso 3 ). Si no se envía esta confirmación, el sistema Senior realizará tres intentos más para enviar la integración pendiente al proveedor, con un intervalo de 10 minutos entre cada intento.
Web service disponibilizado en el prestador SST: pendency
|
|
Parámetros
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 (Pendencia enviada al prestador SST)ON_PROVIDER (Pendencia recibida con éxito por el prestador SST) |
integration.integrationType
|
Enumeración | Sí |
Motivo de la integración Para obtener más información sobre los tipos de integración en este campo, consulte la documentación: |
NEW_EMPLOYEE (Nuevo empleado)EMPLOYEE_CHANGE (Alteración del empleado)DISMISSAL (Despido del empleado)HISTORICAL_COST_CENTER (Historial de centro de costo)HISTORICAL_DEPARTMENT (Historial de departamento)HISTORICAL_ESOCIAL_CATEGORY (Historial de categoría eSocial*)HISTORICAL_JOB_POSITION (Historial de cargo)HISTORICAL_WORKSTATION (Historial de puesto de trabajo)HISTORICAL_COMPANY_BRANCH (Historial de sucursal)HISTORICAL_COMPANY (historial de la empresa)HISTORICAL_WORKSHIFT (Cambio de registro eSocial)HISTORICAL_LEAVE (Historial de eliminación)HISTORICAL_SALARY_PREMIUM (Historial de información adicional)HISTORICAL_WORKENVIRONMENT (Historia del ambiente laboral)EMPLOYEE_ESOCIAL_REGISTRATION (Cambio de registro eSocial)INITIAL_LOAD (Cargo inicial)REINTEGRATION (Reintegración de empleados) |
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 | |
itengration.providerEmployeeIdentification
|
Alfanumérico | No | Identificación del empleado en el proveedor de 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
|
Fecha | 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 (Tercero)PARTNER (Aparcero) |
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 (Soltero)MARRIED (Casado)DIVORCED (Divorciado)WIDOWER (Viudo)SEPARATED (Separado)STABLE_UNION (Unión estable)OTHER (Otro tipo de estado civil)CONCUBINAGE (Concubinato) |
integration.employee.genderType
|
Enumeración | No | Genero del empleado | MALE (Masculino)FEMALE (Femenino) |
integration.employee.situationType
|
Enumeración | Sí | Situación del empleado | PRE_ADMISSION (Registro previo a la admisión)PRE_ADMISSION_CANCELED (Preadmisión cancelada)WORKING (Laboral)VACATION (Vacaciones)FIRED (Despedido)AWAY (Alejado)LICENSE (Licencia) |
integration.employee.contractType
|
Enumeración | No | Tipo del contrato |
MANAGER(Empleado)EMPLOYEE (Director)FARMWORKER (Trabajador rural)RETIRED (Jubilado)TRAINEE (Pasante)APPRENTICE (Aprendiz)FIXEDDUEDATE (Plazo determinado)RETIREDMANAGER (Director jubilado)PUBLICAGENT (Agente público)TEACHER (Profesor)COOPERATIVEWORKER (Cooperado)DOMESTICWORKER (Trabajador doméstico)TEACHERFIXEDDUEDATE (Profesor con plazo determinado) |
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 | ¿El empleado es deficiente? | true
false
|
integration.employee.company
|
Grupo de parámetros con datos de la empresa actual 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 la sucursal actual del 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 | Sí | Razón social de la sucursal | |
integration.employee.companyBranch.subscriptionType
|
Enumeración | Sí | Tipo de inscripción de la sucursal | CNPJ (Registro Nacional de Personas Jurídicas)CPF (Registro de Personas Físicas)CAEPF (Registro de Actividad Económica de las Personas Físicas)CNO (Registro Nacional de Obras)CEI (Registro específico INSS) |
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 | Sí | Razón social de la sucursal | |
integration.employee.previousCompanyBranch.subscriptionType
|
Enumeración | Sí | Tipo de inscripción de la sucursal | CNPJ (Registro Nacional de Personas Jurídicas)CPF (Registro de Personas Físicas)CAEPF (Registro de Actividad Económica de las Personas Físicas)CNO (Registro Nacional de Obras)CEI (Registro específico INSS) |
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 (Auditiva)VISUAL (Visual)MENTAL (Mental)INTELLECTUAL (Intelectual)OTHER (Otro tipo de deficiencia) |
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.employee.previousEmployeeType
|
Alfanumérico | No | Tipo de alta previa del empleado en el sistema de nómina (enviado si el empleado tiene algún traslado entre empresas en su historial) | |
integration.employee.previousCode
|
Numérico | No | Código del registro previo del empleado en el sistema de nómina (se envía si el empleado tiene algún traslado entre empresas en su historial) | |
integration.employee.workEnvironment
|
Lista de entornos laborales de los empleados - Opcional Si el empleado no tiene un historial de entornos laborales, se utilizará la información de la empresa actual de ese empleado. |
|||
integration.employee.workEnvironment.id
|
Alfanumérico | No | Identificador único del registro | |
integration.employee.workEnvironment.location
|
Enumeración | Sí | Lugar de trabajo | OWN_EMPLOYER (establecimiento propio del empleador)THIRD (Establecimiento de terceros) |
integration.employee.workEnvironment.code
|
Alfanumérico | Sí | código de ambiente de trabajo | |
integration.employee.workEnvironment.name
|
Alfanumérico | Sí | Nombre del escritorio | |
integration.employee.workEnvironment.subscriptionType
|
Enumeración | Sí | Tipo de registro | CNPJ (Registro Nacional de Personas Jurídicas)CPF (Registro de Personas Físicas)CAEPF (Registro de Actividad Económica de las Personas Físicas)CNO (Registro Nacional de Obras)CEI (Registro específico INSS) |
integration.employee.workEnvironment.subscriptionNumber
|
Alfanumérico | Sí | Número de registro | |
integration.employee.workEnvironment.dateWhen
|
Fecha | Sí | Fecha del historial de escritorio (desde) | |
integration.employee.reintegrationCompanyOrigin
|
Empresa de origen de la reincorporación del empleado | |||
integration.employee.reintegrationCompanyOrigin.id
|
Alfanumérico | No | Identificador interno de la entidad (ID) | |
integration.employee.reintegrationCompanyOrigin.code
|
Numérico | No | Código de la empresa | |
integration.employee.reintegrationCompanyOrigin.name
|
Alfanumérico | No | Nombre de la empresa | |
integration.employee.reintegrationEmployeeTypeOrigin
|
Enumeración | No | Tipo de empleado origen de la reincorporación | EMPLOYEE (Empleado)THIRD (Tercero)PARTNER (Aparcero) |
integration.employee.reintegrationCodeOrigin
|
Numérico | No | Código fuente para la reincorporación 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": "empleado" "workstation": { "id": "2ccd614a-4ca5-4f44-ace1-70e98f8bc19d", "code": "ADM004", "structureCode": 2, "name": "Abogado", "dateWhen": "2019-01-01", "_discriminator": "workstation" } }, "statusType": "ON_PROVIDER", "integrationType": "NEW_EMPLOYEE", "receiptDate": "2019-09-23T19:50:31.194278Z", "sendDate": "2019-09-23T19:52:01.833552Z", "scheduledDate": "2019-09-23", "dateWhen": "2019-09-23", "integrationMessage": "", "companyCode": 1, "companyName": "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", "proveedorEmployeeIdentification": "123456", "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:
Paso 3 - Enviar la respuesta a la plataforma 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 |
|
||
errorMessage
|
Alfanumérico | No | Mensaje de error |
El propósito del mensaje de error es dejar claro al cliente cuál fue el problema y qué se puede hacer para solucionarlo. De esta forma, el cliente gana autonomía para identificar qué acción debe realizar. Por lo tanto, recomendamos que el mensaje enviado por su sistema se implemente en el siguiente formato:
Ejemplo:
|
||
providerEmployeeIdentification
|
Alfanumérico | No | La identificación única del empleado en el sistema del proveedor . |
Este parámetro le permite encontrar el registro de un empleado utilizando un identificador de empleado único en el sistema del proveedor . El identificador único facilita la identificación del empleado en futuras emisiones enviadas por el sistema Senior, como, por ejemplo, cuando una empresa o sucursal se muda y se cambia el registro del empleado en el sistema. Si el proveedor desea recibir el identificador único en ediciones futuras, primero debe ingresar el ID en este campo proveedorEmployeeIdentification en la primitiva IntegrationUpdateStatus . |
Ejemplo JSON:
|
{ "integrationId" : "a446b2e6-9a9e-46bf-934e-8375e319efd6", "statusType" : "ON_PROVIDER" "errorMessage" : "" "proveedorEmployeeIdentification": "123456abc" } |
Respuesta
| Code | Description | |
|---|---|---|
202
|
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 eventos eSocial (XML) a la plataforma 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.
Servicio web disponible en la plataforma Senior: sendEsocialXml
|
|
Parámetros de entrada
Encabezamiento:
| Parámetro | Valor |
|---|---|
Content-Type
|
application/json |
Authorization
|
Bearer Token |
Cuerpo:
| Parámetro | Tipo | Obligatorio | Descripción | Valores permitidos |
|---|---|---|---|---|
providerXmlId
|
Alfanumérico | Sí | ID do XML en el prestador SST | |
providerCompanyId
|
Alfanumérico | Sí | Código de la empresa en el prestador SST | |
subscriptionType
|
Alfanumérico | Sí | Tipo de inscripción de la empresa | CNPJ
CPF
CAEPF
CNO
CEI
|
subscriptionNumber
|
Alfanumérico | Sí | Número de inscripción de la empresa, sin máscara de formatación | |
xml
|
Alfanumérico | Sí | XML del evento del eSocial, sin quiebras de líneas |
Ejemplo JSON:
|
{ "proveedorXmlId": "11", "proveedorCompanyId": "1", "subscriptionType" : "CNPJ", "número de suscripción": "12345678010158", "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: obtener estados de eventos (XML) de la plataforma Senior
Hay dos formas de obtener estados de eventos desde la plataforma Senior. Puede elegir una de las opciones que se describen a continuación:
3.1) Buscar estado de evento periódicamente (opción 1)
La primera opción es buscar, cada cierto tiempo, el estado de los eventos (XML) que fueron enviados al sistema Senior.
Es necesario implementar la búsqueda de registros de la plataforma senior X con undescanso mínimo de 3 minutos entre cada llamada de servicio web.
Servicio web disponible en la plataforma Senior: statusEsocialXml
|
|
Parámetros de entrada
Encabezamiento:
| Parámetro | Valor |
|---|---|
Content-Type
|
application/json |
Authorization
|
Bearer Token |
Cuerpo:
| Parámetro | Tipo | Obligatorio | Descripción |
|---|---|---|---|
providerXmlId
|
Alfanumérico | No | Identificador único para enviar el XML al proveedor de SST |
id
|
Alfanumérico | No | Identificador único del registro en la plataforma Senior |
Observación
Los parámetros de entrada son opcionales. Sin embargo, siempre es necesario informar al menos uno de los dos parámetros. Si se proporcionan ambos parámetros, solo se considerará la id .
Ejemplo JSON:
|
{ "providerXmlId" : "123456789", "identificación": "91e89d6d-9bad-4f63-91c8-f0b6940f4d31" } |
Respuesta
| Code | Description | |||||||||||||||||||||||||||||||||||||||||||||
|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|
200
|
Respuesta devuelta por el sistema Senior:
Valor de ejemplo:
|
|||||||||||||||||||||||||||||||||||||||||||||
default
|
Respuesta de error Valor de ejemplo:
|
Ejemplos:
Ejecución en cliente API:
Llenado de los parámetros del encabezado (Header) del mensaje:
Evento validado exitosamente por el sistema Senior ( VALIDATION_SUCCESS ):
Evento validado con error por el sistema Senior ( VALIDATION_ERROR ):
Evento en proceso de envío al Gobierno ( SENDING_TO_GOVERNMENT ):
3.2) Recibir estados de eventos en tiempo real (opción 2)
La segunda opción es recibir estados de eventos (XML) en tiempo real . Para esto necesitas 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
La pendencia de integración es enviada por la plataforma de la Senior con los parámetros abajo:
Encabezamiento:
| Parámetro | Observaciones |
|---|---|
Content-Type
|
Valor predeterminado: application/json |
x-senior-key
|
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:
| Code | Description | |||||||||||||||||||||||||||||||||||||||||||||
|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|
200
|
Respuesta devuelta por el sistema Senior:
Valor de ejemplo:
|
|||||||||||||||||||||||||||||||||||||||||||||
default
|
Respuesta de error Valor de ejemplo:
|
Respuesta
| Code | Description | |
|---|---|---|
200
|
DE ACUERDO Valor de ejemplo:
|
|
default
|
Respuesta de error Valor de ejemplo:
|
Paso 4 - Enviar una respuesta a la plataforma Senior indicando la recepción 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.
Servicio web disponible en la plataforma Senior: statusEsocialXmlReceived
|
|
Parámetros de entrada
Encabezamiento:
| Parámetro | Valor |
|---|---|
Content-Type
|
application/json |
Authorization
|
Bearer Token |
Cuerpo:
| Parámetro | Tipo | Descripción | Observaciones | Valores permitidos |
|---|---|---|---|---|
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. | ON_PROVIDER (El estado del evento fue recibido por el proveedor de SST)PROVIDER_ERROR (Hubo problemas al recibir el estado del evento del proveedor de SST) |
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:
Proyecto de plantilla
Si no desea implementar su API como se describe en esta documentación, también ponemos a disposición el proyecto (Undefined variable: integrador-sst.projeto template) . Este proyecto es una plantilla que facilita la implementación de la API. Integrador SST en Java.
el proyecto (Undefined variable: integrador-sst.projeto template) está disponible en GitHub , simplemente descárgalo y cámbialo según tus necesidades, siguiendo la documentación disponible dentro de la propia plantilla.
Entorno de aprobación
Después de implementar la API, puede solicitar acceso al entorno de aprobación y prueba .
Si este es su primer contacto con el equipo de Integrador SST de Senior, realiza tu solicitud llenando el formulario disponible en la documentación de pasos de integración .
¿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.
Esta es la documentación para la versión más actual de esta API. Haga clic aquí si desea consultar la documentación de la versión anterior (descontinuada).
English
Español
