HomeBuildProduct integration guides
Guide
Work Schedules API Guide for ADP eXpert Brazil
Published on
Feb 08, 2023 12:38PM
Last modified
Mar 15, 2023 10:10AM
ADP Copyright Information
ADP, the ADP logo, and Always Designing for People are trademarks of ADP, Inc.
Windows is a registered trademark of the Microsoft Corporation.
All other trademarks are the property of their respective owners.
Copyright © 2023 ADP, Inc. ADP Proprietary and Confidential - All Rights Reserved. These materials may not be reproduced in any format without the express written permission of ADP, Inc.
These materials may not be reproduced in any format without the express written permission of ADP, Inc. ADP provides this publication “as is” without warranty of any kind, either expressed or implied, including, but not limited to, the implied warranties of merchantability or fitness for a particular purpose. ADP is not responsible for any technical inaccurancies or typographical errors which may be contained in this publication. Changes are periodically made to the information herein, and such changes will be incorporated in new editions of this publication. ADP may make improvements and/or changes in the product and/or the programes described in this publication.
Published on
Feb 08, 2023 12:38PM
Last modified
Mar 15, 2023 10:10AM
Table of Contents
Chapter 1
About this API

Summary

The Work Schedules API guides allows to request the Worker Work Schedule planned for the next days, concepts known as "Escala" and "Turma" in the eXpert Brazil SOR.

Also, to calculate the planned schedule for each day for the Worker, the following situations are going to be considered:

  • Time Offs
  • Leaves of Absence
  • Planned day offs
  • Work Schedule changes for specific days
  • Holidays and holidays extensions
  • Standard planned worker work schedule
  • On notice periods

With these information, the system will then calculate if the day is a work day or day off, as well as the planned working hours (from 8:00 to 17:00 for example).

 

What´s new in this guide

In this section, we will announce any new revisions to the Work Schedules Application Programming Interface (API) and this guide.

 

March, 2023

  •  First revision of this document

 

Process Overview

The following table shows how your data connector application would be used by a client.

  Actor Task Description
1 HR Practitioner Trigger the API-based data exchange between your application and ADP eXpert 
1 Your Application Retrieve work schedules information details based on your needs

 

Required Setup Steps

There are no required setup steps.

 

Postman Collection

Postman allows you to import a collection of APIs, created by others, so you can try them out. For more information on Postman, see Making Your First API Call Using Postman.

 

Before You Begin

 

ADP provides a comprehensive set of pay statements APIs to stay in synch with an ADP application and do the following:

  • Retrieve an employee work schedules for a period of days.
  • Retrieve an employee work shift for a day.

The amount of data retrieved by your application may vary based on the target ADP system and the ADP system configurations.

 

Chapter 2
Use Case: Retrieving Work Schedules Information

Before You Begin

 

This API contains the data of the work schedules registered in the eXpert system. In each call, you can ask for the work schedules of a employee.

 

API Usage

 

Method URI Description GitHub Example
GET /time/v2/workers/{aoid}/work-schedules To retrieve the standard work schedule for an employee for a period of days. TBD

 

Scope of Application

 

The canonical URI corresponding to the API needs to be added in the Consumer Application Registry (CAR) for the subscription following which a user can access this API and make successful API calls.

 

The following canonical needs to be added to your application scope to enable this use case:

/time/timeLaborManagement/scheduleManagement/workScheduleManagement/workSchedules.read

 

Supported OData Query Options

This use case supports Query String Options as defined by Open Data Protocol (OData).

 

Query String Option Description Example
Call by ID Filter by the type of worker's work schedule  //time/v2/workers/{aoid}/work-schedules/{schedule-id}
$filter Filter by period of days searched $filter=/workSchedules/schedulePeriod/startDate EQ 2023-01-01 AND /workSchedules/schedulePeriod/endDate EQ 2023-01-04

 

In this API, you only can access the work schedule for a limited period of days per call, so we advise that you use the filter command to inform the period of days requested. If not, the API will return the work schedule for the next 10 days.

 

Data Dictionary

 

See Appendix A: Data Dictionary on page for data retrieval.

All listed fields are supported for this use case.

 

Responses

 

You may encounter exceptions outside your common success scenarios. You must account for these exceptions during your initial development.

Chapter 3
Use Case: Retrieving Work Shifts Information

Before You Begin

 

This API contains the data of the work shifts registered in the eXpert system. In each call, you can ask for the work shift of a employee for a day.

 

API Usage

 

Method URI Description GitHub Example
GET /time/v2/workers/{aoid}/work-shifts To retrieve the standard work shift for a worker given an specific day. TBD

 

Scope of Application

 

The canonical URI corresponding to the API needs to be added in the Consumer Application Registry (CAR) for the subscription following which a user can access this API and make successful API calls.

 

The following canonical needs to be added to your application scope to enable this use case:

/time/timeLaborManagement/scheduleManagement/workScheduleManagement/workshift.read

 

Supported OData Query Options

This use case supports Query String Options as defined by Open Data Protocol (OData).

 

Query String Option Description Example
Call by ID Filter by the type of worker's work shift //time/v2/workers/{aoid}/work-shifts/{schedule-id}
$filter Filter by period the day being searched. $filter=startDate EQ 2023-03-02

 

In this API, you only can access the work shift for a day per call, so we advise that you use the filter command to inform the day requested. If not, the API will return the work shift for the current day.

 

Data Dictionary

 

See Appendix A: Data Dictionary on page for data retrieval.

All listed fields are supported for this use case.

 

Responses

 

You may encounter exceptions outside your common success scenarios. You must account for these exceptions during your initial development.

Chapter 4
Appendixes

Appendix A: Data Dictionary

 

The data dictionary provides the schema resource to application user interface field mapping.

 

Work Schedules > itemID

Canonical Field Label SOR Rule SOR Rule (in local language)

/workSchedules

/workSchedules/itemID

 The unique identifier of the related schedule within a collection

Work Schedule type code, according to the rule:

"Standard" for time register

"On notice" for over notice records

Código do tipo de Work Schedule, conforme regra abaixo:

"Standard" para registros de horário

"On notice" para registros de sobre aviso

 

Work Schedules > scheduleID

Canonical Field Label SOR Rule SOR Rule (in local language)
/workSchedules/scheduleID A unique identification of the schedule

For standard schedule:

<Employee's Current Class Code according to history>-<Collaborator's Current Class Code according to history>_<workerID>

 

Example: 1-1_001-1234

 

For notice periods:

Abbreviation of the notice period_<workerID>

Para horário padrão:

<Código da Escala atual do colaborador conforme histórico>-<Código da Turma atual do colaborador conforme histórico>_<workerID>

 

Exemplo: 1-1_001-1234

 

Para horários de sobre aviso:

Sigla do período de sobre aviso_<workerID>

 

Work Schedules > scheduleName

Canonical Field Label SOR Rule SOR Rule (in local language)
/workSchedules/scheduleName A descriptive name of the schedule

For standard schedule:

Schedule name in the worker registry.

 

For notice periods:

Description of the notice period

Para horário padrão:

Nome da turma do histórico

 

Para horários de sobre aviso:

Descrição do período de sobre aviso

 

Work Schedules > associateOID

Canonical Field Label SOR Rule SOR Rule (in local language)
/workSchedules/associateOID A unique identifier of a worker the schedule is related to

Worker's AOID.

 AOID do colaborador.

 

Work Schedules > schedulePeriod

Canonical Field Label SOR Rule SOR Rule (in local language)

/workSchedules/schedulePeriod

/workSchedules/schedulePeriod/startDate

 Work schedule period start date Work schedule period start date Data de início do período de Work Schedule
/workSchedules/schedulePeriod/endDate Work schedule period end date Work schedule period end date Data de fim do período de Work Schedule

 

Work Schedules > scheduleDays

Canonical Field Label SOR Rule SOR Rule (in local language)
/workSchedules/scheduleDays A collection of days within the schedule

Open a record in the array for each day of the period, from the start date to the end date

 Será demonstrado um registro na lista para cada dia que compõe o período sendo demonstrado.

/workSchedules/scheduleDays/dayOfWeekCode

/workSchedules/scheduleDays/dayOfWeekCode/name

 A day of week

Day of the week

 Nome do dia da semana
/workSchedules/scheduleDays/scheduleDayDate A date identifying the schedule day

Date

 Dia do registro

 

Work Schedules > workShifts

Canonical Field Label SOR Rule SOR Rule (in local language)
/workSchedules/scheduleDays/workShifts A collection of shifts 

Worker's work shifts for the day.

 Nesta lista serão demonstrados os turnos de trabalho do colaborador no dia.
/workSchedules/scheduleDays/workShifts/workShiftID The unique identifier for a Work Shift

Shift code as registered in the eXpert

 Código do horário conforme cadastrado no eXpert
/workSchedules/scheduleDays/workShifts/shiftDescription The description of the Work Shift

Description of the work shift, if registered.

 Descrição do horário, se cadastrada.

/workSchedules/scheduleDays/workShifts/shiftTypeCode

/workSchedules/scheduleDays/workShifts/shiftTypeCode/name

 The short description of the related code used as a coded name

Description of the shift type:

For time 997: "Leave"

For schedules 998 and 999: "Day off"

For other schedules: "Work day"

Descrição do tipo de horário:

Para horário 997: "Leave"

Para horários 998 e 999: "Day off"

Para demais horários: "Work day"

/workSchedules/scheduleDays/workShifts/shiftDateTimePeriod

/workSchedules/scheduleDays/workShifts/shiftDateTimePeriod/startDateTime

 Defines the startDatetime and endDateTime for the work shift.

Shift start date/time.

 Data/hora de início do horário
/workSchedules/scheduleDays/workShifts/shiftDateTimePeriod/endDateTime Time end of date/time

Shift end date/time

Data/hora de fim do horário

 

/workSchedules/scheduleDays/workShifts/totalTime

 

/workSchedules/scheduleDays/workShifts/totalTime/timeValue

 The total amount of time from the start of a work shift to the end of the work shift expressed as hh:mm

Total hours of the schedule

 

Empty for time off, DSR, leave

Total de Horas do horário

Não demonstrar para horários de folga, DSR, afastamento
/workSchedules/scheduleDays/workShifts/shiftSegments The collection of shift segments that occur in the work shift.

Open an object for every pair of clock entries.

 

Example:

08:00 12:00 13:00 17:00

 

We would have:

An object for 08:00 12:00

An object for 12:00 13:00

An object for 13:00 17:00

Abrir um objeto para cada par de batidas de ponto

 

Exemplo:

08:00 12:00 13:00 17:00

Teríamos:

Um objeto para 08:00 12:00

Um objeto para 12:00 13:00

Um objeto para 13:00 17:00
/workSchedules/scheduleDays/workShifts/shiftSegments/segmentTypeCode The type of shift segment (e.g. work, break, etc.)

"Work" for periods of work

"Break" for meal/break periods

 

 

"Work" para períodos de trabalho

"Break" para períodos de refeição/pausa

 

/workSchedules/scheduleDays/workShifts/shiftSegments/segmentDateTimePeriod

/workSchedules/scheduleDays/workShifts/shiftSegments/segmentDateTimePeriod/startDateTime

 The string representation of the date-time value

Pair entry time

 

Example:

08:00 12:00 13:00 17:00

We would have:

08:00

12:00

13:00

 

Do not demonstrate for time off, DSR, leave

Horário da entrada do par

 

Exemplo:

08:00 12:00 13:00 17:00

Teríamos:

08:00

12:00

13:00

 

Não demonstrar para horários de folga, DSR, afastamento
/workSchedules/scheduleDays/workShifts/shiftSegments/segmentDateTimePeriod/endDateTime The string representation of the date-time value

Pair end time

Example:

08:00 12:00 13:00 17:00

 

We would have:

12:00 pm

13:00

17:00

 

Do not demonstrate for time off, DSR, leave

Horário da saída do par

 

Exemplo:

08:00 12:00 13:00 17:00

Teríamos:

12:00

13:00

17:00

 

Não demonstrar para horários de folga, DSR, afastamento

 

Appendix B: Data Dictionary

Work Shifts

Canonical Field Label SOR Rule SOR Rule (in local language)
/workSchedules/scheduleDays/workShifts A collection of shifts 

Work shifts

 Turnos de trabalho
/workSchedules/scheduleDays/workShifts/workShiftID The unique identifier for a Work Shift

Time code as registered in the eXpert

 Código do horário conforme cadastrado no eXpert

/workSchedules/scheduleDays/workShifts/shiftDescription

 The description of the Work Shift

Work Shift type.

 Tipo de horário

/workSchedules/scheduleDays/workShifts/shiftTypeCode

 

/workSchedules/scheduleDays/workShifts/shiftTypeCode/name

 The short description of the related code used as a coded name

Description of the time type:

 

For time 997: "Leave"

For schedules 998 and 999: "Day off"

For other schedules: "Work day"

Demonstrar a descrição do tipo de horário:

 

Para horário 997: "Leave"

Para horários 998 e 999: "Day off"

Para demais horários: "Work day"

/workSchedules/scheduleDays/workShifts/shiftDateTimePeriod

/workSchedules/scheduleDays/workShifts/shiftDateTimePeriod/startDateTime

 Defines the startDatetime and endDateTime for the work shift.

Time start of date/time

 Data/hora de início do horário
/workSchedules/scheduleDays/workShifts/shiftDateTimePeriod/endDateTime Time end of date/time

Time end of date/time

Data/hora de fim do horário

 

/workSchedules/scheduleDays/workShifts/totalTime

 

/workSchedules/scheduleDays/workShifts/totalTime/timeValue

 The total amount of time from the start of a work shift to the end of the work shift expressed as hh:mm

Total hours of the schedule

Do not demonstrate for time off, DSR, leave

Total de Horas do horário

Não demonstrar para horários de folga, DSR, afastamento
/workSchedules/scheduleDays/workShifts/shiftSegments The collection of shift segments that occur in the work shift.

Open an object for every pair of clock entries

 

Example:

08:00 12:00 13:00 17:00

 

We would have:

An object for 08:00 12:00

An object for 12:00 13:00

An object for 13:00 17:00

Abrir um objeto para cada par de batidas de ponto 

 

Exemplo:

08:00 12:00 13:00 17:00

 

Teríamos:

Um objeto para 08:00 12:00

Um objeto para 12:00 13:00

Um objeto para 13:00 17:00
/workSchedules/scheduleDays/workShifts/shiftSegments/segmentTypeCode The type of shift segment (e.g. work, break, etc.)

"Work" for periods of work

"Break" for meal/break periods

 

Example:

08:00 12:00 13:00 17:00

 

We would have:

Work to 08:00 12:00

Break for 12:00 13:00

Work for 13:00 17:00

 

"Work" para períodos de trabalho

"Break" para períodos de refeição/pausa

 

Exemplo:

08:00 12:00 13:00 17:00

 

Teríamos:

Work para 08:00 12:00

Break para 12:00 13:00

Work para 13:00 17:00

/workSchedules/scheduleDays/workShifts/shiftSegments/segmentDateTimePeriod

/workSchedules/scheduleDays/workShifts/shiftSegments/segmentDateTimePeriod/startDateTime

 The string representation of the date-time value

Pair entry time

 

Example:

08:00 12:00 13:00 17:00

We would have:

8 o'clock

12:00 pm

13:00

Do not demonstrate for time off, DSR, leave

Horário da entrada do par

 

Exemplo:

08:00 12:00 13:00 17:00

Teríamos:

08:00

12:00

13:00

 

Não demonstrar para horários de folga, DSR, afastamento
/workSchedules/scheduleDays/workShifts/shiftSegments/segmentDateTimePeriod/endDateTime The string representation of the date-time value

Pair end time

 

Example:

08:00 12:00 13:00 17:00

 

We would have:

12:00 pm

13:00

17:00

 

Horário da saída do par

 

Exemplo:

08:00 12:00 13:00 17:00

 

Teríamos:

12:00

13:00

17:00

Work Schedules API Guide for ADP eXpert Brazil

Last updated: Mar 15, 2023
SummaryThe Work Schedules Application Programming Interface (API) for eXpert Brazil allows to make employee time data available to customers and partners.
Download Guide.Download PDF
Chapter 1
About this API
Chapter 2
Use Case: Retrieving Work Schedules Information
Chapter 3
Use Case: Retrieving Work Shifts Information
Chapter 4
Appendixes
ADP Marketplace
About Marketplace
Apps
Partners
Developers
About ADP
API Reference
Learn
Key concepts
How-to articles
FAQs
Build
Integration by solution
API explorer
Developer libraries
Guides
Support
Status
Help center
ADP and the ADP logo are registered trademarks of ADP, Inc. All other marks are the property of their respective owners.
Copyright © 2023 ADP, Inc.
Terms|Privacy