Documentación de la API de TimeWellScheduled

1. Introducción

La API de TimeWellScheduled permite a los desarrolladores integrar de forma segura funciones de programación de horarios, seguimiento de tiempo, nóminas y recursos humanos en sus aplicaciones. Todas las solicitudes se realizan a través de HTTPS y devuelven datos estructurados en formato JSON o XML.

2. Primeros pasos

Antes de comenzar, necesitará una clave API (API Key) y un ID de empresa (Company ID).
Siga la guía de configuración de la clave API para generar su clave API.

URL de la API:

Si sus datos residen en Canadá, la URL de su API es
https://api.ca.timewellscheduled.com

Si sus datos residen en EE. UU., la URL de su API es
https://api.us.timewellscheduled.com

3. Autenticación y seguridad

Application ID [appid] – proporcionado por nosotros en la guía de configuración de la clave API
Company ID [c] – el identificador único de su empresa. Puede ser encontrado aquí
Module [module] – el módulo que se está llamando
Encriptación: Todas las contraseñas se almacenan usando bCrypt

Deberá realizar un hash de las credenciales de los empleados con el «salt» específico de la empresa proporcionado durante la autenticación. Para más información sobre bCrypt, lea esto.

4. Formato de solicitud

Todas las solicitudes utilizan el método GET con los parámetros pasados en la cadena de consulta (query string).

Ejemplo:

GET /?appid={AppID}&c={CompanyID}&module=verify

GET /?appid={AppID}&c={CompanyID}&module=verify

Parámetros requeridos:

appid – Su Application ID

c – Company ID

module – Módulo de la API a llamar

appid – Su Application ID
c – Company ID
module – Módulo de la API a llamar

appid – Su Application ID
c – Company ID
module – Módulo de la API a llamar

5. Formato de respuesta

Las respuestas devuelven resultados estructurados en JSON o XML (algunas llamadas devuelven JSON, otras XML).

Ejemplo de respuesta JSON:

{

«success»: 1,

«ontime»: 1,

«message»: «Your action has been recorded successfully»

}

{
«success»: 1,
«ontime»: 1,
«message»: «Your action has been recorded successfully»
}

{
"success": 1,
"ontime": 1,
"message": "Your action has been recorded successfully"
}

6. Módulos

verify

Recupera la información de la empresa y la lista de empleados.

URL del endpoint:

<API URL>/response.asp

Ejemplo de solicitud:

GET /?appid={AppID}&c={CompanyID}&module=verify

GET /?appid={AppID}&c={CompanyID}&module=verify

Ejemplo de respuesta:

<?xml version=”1.0”?>

<name>Bob Robertson</name>

</employee>

<name>Jane Johnson</name>

</employee>

<name>Bill Smith</name>

</employee>

</employees>

<branding logo=«https://url_to_logo/MainLogo.png»>Your Company Here</branding>

<bcryptSalt>yourKey</bcryptSalt>

</message>

</response>

<?xml version=”1.0”?>
<response>
<success>1</success>
<ontime>1</ontime>
<message>
<employees>
<employee>
<name>Bob Robertson</name>
<id>12345</id>
</employee>
<employee>
<name>Jane Johnson</name>
<id>abc123</id>
</employee>
<employee>
<name>Bill Smith</name>
<id>995jk</id>
</employee>
</employees>
<branding logo=»https://url_to_logo/MainLogo.png»>Your Company Here</branding>
<bcryptSalt>yourKey</bcryptSalt>
</message>
</response>

<?xml version=”1.0”?>
 <response>
 <success>1</success>
 <ontime>1</ontime>
 <message>
 	<employees>
 		<employee>
 		<name>Bob Robertson</name>
 		<id>12345</id>
 		</employee>
 		<employee>
 		<name>Jane Johnson</name>
 		<id>abc123</id>
 		</employee>
 		<employee>
 		<name>Bill Smith</name>
 		<id>995jk</id>
 		</employee>
 	</employees>
 	<branding logo="https://url_to_logo/MainLogo.png">Your Company Here</branding>
 	<bcryptSalt>yourKey</bcryptSalt>
 </message>
 </response>

begin

Registra el inicio del turno de un empleado.

URL del endpoint:

<API URL>/response.asp

Parámetros adicionales:

U – código de fichaje

P – contraseña del empleado (en bCrypt)

Year – el año en que se realiza la acción

Month – el mes en que se realiza la acción

Day – el día en que se realiza la acción

Hour – la hora en que se realiza la acción

Minute – el minuto en que se realiza la acción

Second – el segundo en que se realiza la acción

U – código de fichaje
P – contraseña del empleado (en bCrypt)
Year – el año en que se realiza la acción
Month – el mes en que se realiza la acción
Day – el día en que se realiza la acción
Hour – la hora en que se realiza la acción
Minute – el minuto en que se realiza la acción
Second – el segundo en que se realiza la acción

U – código de fichaje
P – contraseña del empleado (en bCrypt)
Year – el año en que se realiza la acción
Month – el mes en que se realiza la acción
Day – el día en que se realiza la acción
Hour – la hora en que se realiza la acción
Minute – el minuto en que se realiza la acción
Second - el segundo en que se realiza la acción

Ejemplo de solicitud:

GET /?appid={AppID}&c={CompanyID}&module=begin&u={punchCode}&p={bCryptPassword}&Year=2025&Month=9&Day=22&Hour=16&Minute=0&Second=34

GET /?appid={AppID}&c={CompanyID}&module=begin&u={punchCode}&p={bCryptPassword}&Year=2025&Month=9&Day=22&Hour=16&Minute=0&Second=34

Ejemplo de respuesta:

<?xml version=”1.0”?>

<message>Your action has been recorded successfully. You have 12 unread message(s) in your Inbox.</message>

</response>

<?xml version=”1.0”?>
<response>
<success>1</success>
<ontime>1</ontime>
<message>Your action has been recorded successfully. You have 12 unread message(s) in your Inbox.</message>
</response>

<?xml version=”1.0”?>
 <response>
 	<success>1</success>
 	<ontime>1</ontime>
 	<message>Your action has been recorded successfully. You have 12 unread message(s) in your Inbox.</message>
 </response>

end

Registra el fin del turno de un empleado.

URL del endpoint:

<API URL>/response.asp

Parámetros adicionales:

U – código de fichaje

P – contraseña del empleado (en bCrypt)

Year – el año en que se realiza la acción

Month – el mes en que se realiza la acción

Day – el día en que se realiza la acción

Hour – la hora en que se realiza la acción

Minute – el minuto en que se realiza la acción

Second – el segundo en que se realiza la acción

U – código de fichaje
P – contraseña del empleado (en bCrypt)
Year – el año en que se realiza la acción
Month – el mes en que se realiza la acción
Day – el día en que se realiza la acción
Hour – la hora en que se realiza la acción
Minute – el minuto en que se realiza la acción
Second - el segundo en que se realiza la acción

Ejemplo de solicitud:

GET /?appid={AppID}&c={CompanyID}&module=end&u={punchCode}&p={bCryptPassword}&Year=2025&Month=9&Day=22&Hour=19&Minute=05&Second=25

GET /?appid={AppID}&c={CompanyID}&module=end&u={punchCode}&p={bCryptPassword}&Year=2025&Month=9&Day=22&Hour=19&Minute=05&Second=25

Ejemplo de respuesta:

<?xml version=”1.0”?>

<message>It is too early for you to EXIT</message>

<message>Select a reason.</message>

<reason ID=«2233»>Accident de route</reason>

<reason ID=«153»>Car problems</reason>

<reason ID=«157»>Computer issues</reason>

<reason ID=«1482»>Default reason code</reason>

<reason ID=«159»>Finished early</reason>

<reason ID=«154»>Not feeling well</reason>

<reason ID=«156»>Other (Please explain)</reason>

<reason ID=«1983»>Personal emergency</reason>

<reason ID=«2231»>Rendez-vous chez le medecin</reason>

<reason ID=«158»>Traffic</reason>

</reasons>

</watchdog>

</response>

<?xml version=”1.0”?>
<response>
<success>0</success>
<ontime>0</ontime>
<message>It is too early for you to EXIT</message>
<watchdog>
<message>Select a reason.</message>
<reasons>
<reason ID=»2233″>Accident de route</reason>
<reason ID=»153″>Car problems</reason>
<reason ID=»157″>Computer issues</reason>
<reason ID=»1482″>Default reason code</reason>
<reason ID=»159″>Finished early</reason>
<reason ID=»154″>Not feeling well</reason>
<reason ID=»156″>Other (Please explain)</reason>
<reason ID=»1983″>Personal emergency</reason>
<reason ID=»2231″>Rendez-vous chez le medecin</reason>
<reason ID=»158″>Traffic</reason>
</reasons>
</watchdog>
</response>

<?xml version=”1.0”?>
 <response>
 	<success>0</success>
 	<ontime>0</ontime>
 	<message>It is too early for you to EXIT</message>
 	<watchdog>
 		<message>Select a reason.</message>
 		<reasons>
 			<reason ID="2233">Accident de route</reason>
 			<reason ID="153">Car problems</reason>
 			<reason ID="157">Computer issues</reason>
 			<reason ID="1482">Default reason code</reason>
 			<reason ID="159">Finished early</reason>
 			<reason ID="154">Not feeling well</reason>
 			<reason ID="156">Other (Please explain)</reason>
 			<reason ID="1983">Personal emergency</reason>
 			<reason ID="2231">Rendez-vous chez le medecin</reason>
 			<reason ID="158">Traffic</reason>
 		</reasons>
 	</watchdog>
 </response>

Dado que la solicitud no tuvo éxito y se activó un evento de supervisión (watchdog), debemos enviar la misma solicitud de nuevo con el parámetro adicional REASON ID incluido.

Ejemplo de solicitud:

GET /?appid={AppID}&c={CompanyID}&module=end&u={punchCode}&p={bCryptPassword}&Year=2025&Month=9&Day=22&Hour=19&Minute=05&Second=25&reason={reason ID}

GET /?appid={AppID}&c={CompanyID}&module=end&u={punchCode}&p={bCryptPassword}&Year=2025&Month=9&Day=22&Hour=19&Minute=05&Second=25&reason={reason ID}

Ejemplo de respuesta:

<?xml version=”1.0”?>

<message>Your action has been recorded successfully.</message>

</response>

<?xml version=”1.0”?>
<response>
<success>1</success>
<ontime>1</ontime>
<message>Your action has been recorded successfully.</message>
</response>

<?xml version=”1.0”?>
 <response>
 	<success>1</success>
 	<ontime>1</ontime>
 	<message>Your action has been recorded successfully.</message>
 </response>

break

Registra el inicio o fin de un descanso (break).

URL del endpoint:

<API URL>/response.asp

Parámetros adicionales:

U – código de fichaje

P – contraseña del empleado (en bCrypt)

Year – el año en que se realiza la acción

Month – el mes en que se realiza la acción

Day – el día en que se realiza la acción

Hour – la hora en que se realiza la acción

Minute – el minuto en que se realiza la acción

Second – el segundo en que se realiza la acción

U – código de fichaje
P – contraseña del empleado (en bCrypt)
Year – el año en que se realiza la acción
Month – el mes en que se realiza la acción
Day – el día en que se realiza la acción
Hour – la hora en que se realiza la acción
Minute – el minuto en que se realiza la acción
Second - el segundo en que se realiza la acción

Ejemplo de solicitud:

GET /?appid={AppID}&c={CompanyID}&module=break&u={punchCode}&p={bCryptPassword}&Year=2025&Month=9&Day=22&Hour=18&Minute=15&Second=09

GET /?appid={AppID}&c={CompanyID}&module=break&u={punchCode}&p={bCryptPassword}&Year=2025&Month=9&Day=22&Hour=18&Minute=15&Second=09

Ejemplo de respuesta:

<?xml version=”1.0”?>

<message>Your action has been recorded successfully.</message>

</response>

<?xml version=”1.0”?>
<response>
<success>1</success>
<ontime>1</ontime>
<message>Your action has been recorded successfully.</message>
</response>

<?xml version=”1.0”?>
 <response>
 	<success>1</success>
 	<ontime>1</ontime>
 	<message>Your action has been recorded successfully.</message>
 </response>

meal

Registra el inicio o fin de un período de comida.

URL del endpoint:

<API URL>/response.asp

Parámetros adicionales:

U – código de fichaje

P – contraseña del empleado (en bCrypt)

Year – el año en que se realiza la acción

Month – el mes en que se realiza la acción

Day – el día en que se realiza la acción

Hour – la hora en que se realiza la acción

Minute – el minuto en que se realiza la acción

Second – el segundo en que se realiza la acción

U – código de fichaje
P – contraseña del empleado (en bCrypt)
Year – el año en que se realiza la acción
Month – el mes en que se realiza la acción
Day – el día en que se realiza la acción
Hour – la hora en que se realiza la acción
Minute – el minuto en que se realiza la acción
Second - el segundo en que se realiza la acción

Ejemplo de solicitud:

GET /?appid={AppID}&c={CompanyID}&module=meal&u={punchCode}&p={bCryptPassword}&Year=2025&Month=9&Day=22&Hour=17&Minute=08&Second=25

GET /?appid={AppID}&c={CompanyID}&module=meal&u={punchCode}&p={bCryptPassword}&Year=2025&Month=9&Day=22&Hour=17&Minute=08&Second=25

Ejemplo de respuesta:

<?xml version=”1.0”?>

<message>This action cannot be done. Your schedule does not allow any MEALS</message>

</response>

<?xml version=”1.0”?>
<response>
<success>0</success>
<ontime>0</ontime>
<message>This action cannot be done. Your schedule does not allow any MEALS</message>
</response>

<?xml version=”1.0”?>
 <response>
 	<success>0</success>
 	<ontime>0</ontime>
 	<message>This action cannot be done. Your schedule does not allow any MEALS</message>
 </response>

schedule_list

Recupera los horarios de un empleado dentro de un rango de fechas determinado.

URL del endpoint:

<API URL>/response_json.asp

Parámetros adicionales:

StartDate – la fecha de inicio del rango

EndDate – la fecha de fin del rango

StartDate – la fecha de inicio del rango
EndDate – la fecha de fin del rango

StartDate – la fecha de inicio del rango
EndDate – la fecha de fin del rango

Ejemplo de solicitud:

POST /?appid={AppID}&c={CompanyID}&module=schedule_list&u={punchCode}&StartDate=2025–09–01&EndDate= 2025–09–02

POST /?appid={AppID}&c={CompanyID}&module=schedule_list&u={punchCode}&StartDate=2025-09-01&EndDate= 2025-09-02

POST /?appid={AppID}&c={CompanyID}&module=schedule_list&u={punchCode}&StartDate=2025-09-01&EndDate= 2025-09-02

Ejemplo de respuesta:

{

«success»: 1,

«schedules»: [

{«date»: «2025-09-01», «time»: «9:00-17:00», «dept»: «Office»},

{«date»: «2025-09-02», «time»: «9:00-17:00», «dept»: «Office»}

]

}

{
«success»: 1,
«schedules»: [
{«date»: «2025-09-01», «time»: «9:00-17:00», «dept»: «Office»},
{«date»: «2025-09-02», «time»: «9:00-17:00», «dept»: «Office»}
]
}

{
"success": 1,
"schedules": [
{"date": "2025-09-01", "time": "9:00-17:00", "dept": "Office"},
{"date": "2025-09-02", "time": "9:00-17:00", "dept": "Office"}
]
}

employee_list

Recupera todos los empleados activos.

URL del endpoint:

<API URL>/response_json.asp

Ejemplo de solicitud:

POST /?appid={AppID}&c={CompanyID}&module=employee_list

POST /?appid={AppID}&c={CompanyID}&module=employee_list

Ejemplo de respuesta:

{

«success»: 1,

«employees»: [

{«id»: «001», «name»: «Alice Johnson»},{«id»: «002», «name»: «Mark Smith»}

]

}

{
«success»: 1,
«employees»: [
{«id»: «001», «name»: «Alice Johnson»},{«id»: «002», «name»: «Mark Smith»}
]
}

{
"success": 1,
"employees": [
{"id": "001", "name": "Alice Johnson"},{"id": "002", "name": "Mark Smith"}
]
}

absence_list

Recupera las ausencias de los empleados dentro de un rango de fechas determinado.

URL del endpoint:

<API URL>/response_json.asp

Parámetros adicionales:

StartDate – la fecha de inicio del rango

EndDate – la fecha de fin del rango

StartDate – la fecha de inicio del rango
EndDate – la fecha de fin del rango

StartDate – la fecha de inicio del rango
EndDate – la fecha de fin del rango

Ejemplo de solicitud:

POST /?appid={AppID}&c={CompanyID}&module=absence_list&StartDate=2025–09–01&EndDate=2025–09–30

POST /?appid={AppID}&c={CompanyID}&module=absence_list&StartDate=2025-09-01&EndDate=2025-09-30

POST /?appid={AppID}&c={CompanyID}&module=absence_list&StartDate=2025-09-01&EndDate=2025-09-30

Ejemplo de respuesta:

{

«success»: 1,

«absences»: [

{«employee»: «John Doe», «from»: «2025-09-10», «to»: «2025-09-12», «type»: «Vacation»}

]

}

{
«success»: 1,
«absences»: [
{«employee»: «John Doe», «from»: «2025-09-10», «to»: «2025-09-12», «type»: «Vacation»}
]
}

{
"success": 1,
"absences": [
{"employee": "John Doe", "from": "2025-09-10", "to": "2025-09-12", "type": "Vacation"}
]
}

payroll_list

Recupera los detalles de nómina (payroll) para un rango de fechas.

URL del endpoint:

<API URL>/response_json.asp

Parámetros adicionales:

StartDate – la fecha de inicio del rango

EndDate – la fecha de fin del rango

StartDate – la fecha de inicio del rango
EndDate – la fecha de fin del rango

StartDate – la fecha de inicio del rango
EndDate – la fecha de fin del rango

Ejemplo de solicitud:

POST /?appid={AppID}&c={CompanyID}&module=payroll_list&StartDate=2025–09–01&EndDate=2025–09–15

POST /?appid={AppID}&c={CompanyID}&module=payroll_list&StartDate=2025-09-01&EndDate=2025-09-15

POST /?appid={AppID}&c={CompanyID}&module=payroll_list&StartDate=2025-09-01&EndDate=2025-09-15

Ejemplo de respuesta:

{

«success»: 1,

«payroll»: [

{«employee»: «Anne Robinson», «totalRT»: 40, «totalOT»: 5},

{«employee»: «Sam Smith», «totalRT»: 38, «totalOT»: 0}

]

}

{
«success»: 1,
«payroll»: [
{«employee»: «Anne Robinson», «totalRT»: 40, «totalOT»: 5},
{«employee»: «Sam Smith», «totalRT»: 38, «totalOT»: 0}
]
}

{
"success": 1,
"payroll": [
{"employee": "Anne Robinson", "totalRT": 40, "totalOT": 5},
{"employee": "Sam Smith", "totalRT": 38, "totalOT": 0}
]
}

who_is_working

Recupera la lista de todos los empleados programados para trabajar hoy.

URL del endpoint:

<API URL>/response_json.asp

Parámetros adicionales:

Date – la fecha para la cual visualizar los horarios

Date – la fecha para la cual visualizar los horarios

Ejemplo de solicitud:

POST /?appid={AppID}&c={CompanyID}&module= who_is_working&Date=2025–09–25

POST /?appid={AppID}&c={CompanyID}&module= who_is_working&Date=2025-09-25

POST /?appid={AppID}&c={CompanyID}&module= who_is_working&Date=2025-09-25

Ejemplo de respuesta:

{

«schedules»: [

{

«employeeName»: «Chester Field»,

«departmentName»: «Widget Assembly»,

«departmentCode»: «WA»,

«shiftStartDate»: «October 28, 2025»,

«shiftStartTime»: «7:00a»,

«shiftEndDate»: «October 28, 2025»,

«shiftEndTime»: «4:30p»,

«status»: «On Duty»

}

«displayDate»: «October 28, 2025»,

}

{
«schedules»: [
{
«employeeName»: «Chester Field»,
«departmentName»: «Widget Assembly»,
«departmentCode»: «WA»,
«shiftStartDate»: «October 28, 2025»,
«shiftStartTime»: «7:00a»,
«shiftEndDate»: «October 28, 2025»,
«shiftEndTime»: «4:30p»,
«status»: «On Duty»
}
],
«displayDate»: «October 28, 2025»,
}
}

{
    "schedules": [
        {
            "employeeName": "Chester Field",
            "departmentName": "Widget Assembly",
            "departmentCode": "WA",
            "shiftStartDate": "October 28, 2025",
            "shiftStartTime": "7:00a",
            "shiftEndDate": "October 28, 2025",
            "shiftEndTime": "4:30p",
            "status": "On Duty"
        }
    ],
    "displayDate": "October 28, 2025",
}
}

7. Parámetros opcionales

file – Adjunta una foto con las acciones de fichaje

lat/lng – Pasa las coordenadas de geolocalización

ip – Restringe las acciones a IPs registradas

reason – Proporciona los motivos ‘watchdog’ cuando sea requerido

file – Adjunta una foto con las acciones de fichaje
lat/lng – Pasa las coordenadas de geolocalización
ip – Restringe las acciones a IPs registradas
reason – Proporciona los motivos ‘watchdog’ cuando sea requerido

file – Adjunta una foto con las acciones de fichaje
lat/lng – Pasa las coordenadas de geolocalización
ip – Restringe las acciones a IPs registradas
reason – Proporciona los motivos 'watchdog' cuando sea requerido

8. Inicio de sesión único (SSO)

TimeWellScheduled es compatible con SSO, lo que permite a los usuarios iniciar sesión directamente a través de una URL segura. Parámetros requeridos:

appid, c, userEmail, timestamp, hash. Póngase en contacto con soporte para confirmar la URL de su centro de datos.

9. Manejo de errores

Las respuestas de la API incluyen un indicador de éxito (success flag) y mensajes descriptivos. – success = 1 → Solicitud exitosa –

success = 0 → Error (consulte el mensaje o la respuesta del watchdog para obtener más detalles)

10. Soporte

Si encuentra problemas: Correo electrónico: support@timewellscheduled.com Teléfono: 1-877-689-7977

Documentación de la API de TimeWellScheduled

PRIMEROS PASOS

1. Introducción

2. Primeros pasos

3. Autenticación y seguridad

4. Formato de solicitud

5. Formato de respuesta

6. Módulos

verify

begin

end

break

meal

schedule_list

employee_list

absence_list

payroll_list

who_is_working

7. Parámetros opcionales

8. Inicio de sesión único (SSO)

9. Manejo de errores

10. Soporte