Buscar hueco libre
https://api.afer.pro/api/v1/schedules/free-slots
GET https://api.afer.pro/api/v1/schedules/free-slots
Los ratos en que todas las personas pedidas están libres a la vez, de la duración pedida.
Dentro de su jornada planificada, sin festivos ni ausencias y sin pisar lo que ya tienen con hora. Devuelve los primeros huecos por orden, con el rato libre entero y una propuesta que empieza al principio del rato (en múltiplos de 15 minutos). De hoy, solo lo que queda por delante.
Quien no tiene ningún turno planificado en el período cuenta de lunes a viernes de 9 a 14 y de 15 a 18, y se dice en avisos; con horario_por_defecto: false, sin turno no hay hueco.
No reserva nada: para eso, agendar.
Envía tus claves API en las cabeceras X-API-KEY y X-API-SECRET. La cuenta sobre la que se opera se resuelve automáticamente a partir de la clave. Cómo obtener tus claves →
Este endpoint requiere autenticación (API key u OAuth).
Parámetros del cuerpo
El cuerpo de la petición es un objeto JSON con Content-Type: application/json.
empleadoIdsarrayopcional | Las personas (id cifrado, correo o nombre); en GET, separadas por comas. Vacío = quien llama. Hasta 10. |
duracion_minutosintegerobligatorio | Cuánto tiene que durar, de 5 a 720. |
fecha_iniciostringopcional | Desde. Por defecto hoy. |
fecha_finstringopcional | Hasta. Por defecto 14 días; como mucho 62. |
desde_horastringopcional | Solo a partir de esta hora (HH:MM). |
hasta_horastringopcional | Solo hasta esta hora (HH:MM). |
limiteintegeropcional | Cuántos huecos. Por defecto 8, máximo 30. |
horario_por_defectobooleanopcional | Usar 9–14 y 15–18 con quien no tiene turnos. Por defecto sí. |
Ejemplo de petición
curl -X GET 'https://api.afer.pro/api/v1/schedules/free-slots?empleadoIds=aBc%E2%80%A6%2CdEf%E2%80%A6&duracion_minutos=90&fecha_inicio=2026-11-09&fecha_fin=2026-11-13' \
-H 'X-API-KEY: afer_tk_TU_TOKEN' \
-H 'X-API-SECRET: afer_sk_TU_SECRET'
<?php
$ch = curl_init('https://api.afer.pro/api/v1/schedules/free-slots?empleadoIds=aBc%E2%80%A6%2CdEf%E2%80%A6&duracion_minutos=90&fecha_inicio=2026-11-09&fecha_fin=2026-11-13');
curl_setopt($ch, CURLOPT_RETURNTRANSFER, true);
curl_setopt($ch, CURLOPT_HTTPHEADER, [
'X-API-KEY: afer_tk_TU_TOKEN',
'X-API-SECRET: afer_sk_TU_SECRET',
]);
$respuesta = json_decode(curl_exec($ch), true);
curl_close($ch);
const respuesta = await fetch('https://api.afer.pro/api/v1/schedules/free-slots?empleadoIds=aBc%E2%80%A6%2CdEf%E2%80%A6&duracion_minutos=90&fecha_inicio=2026-11-09&fecha_fin=2026-11-13', {
method: 'GET',
headers: {
'X-API-KEY': 'afer_tk_TU_TOKEN',
'X-API-SECRET': 'afer_sk_TU_SECRET'
}
});
const resultado = await respuesta.json();
Respuesta
{
"errorCode": 200,
"errorMsg": "",
"data": {
"personas": [
{
"empleadoId": "aBc…",
"nombre": "Pere Mas"
},
{
"empleadoId": "dEf…",
"nombre": "Toni Vich"
}
],
"periodo": {
"desde": "2026-11-09",
"hasta": "2026-11-13"
},
"duracion_minutos": 90,
"num_huecos": 1,
"huecos": [
{
"fecha": "2026-11-09",
"dia": "lunes",
"libre_desde": "15:00",
"libre_hasta": "17:00",
"propuesta": {
"fecha": "2026-11-09",
"hora_inicio": "15:00",
"hora_fin": "16:30"
},
"minutos_libres": 120
}
],
"avisos": [],
"mensaje": "Para reservar uno, agendar con su fecha y hora."
}
}
Errores
| Caso | Resultado |
|---|---|
| Sin credenciales | errorCode 401. |
Sin duracion_minutos o fuera de 5–720 |
errorCode 400. |
| Período ya pasado o de más de 62 días | errorCode 400. |
Por MCP es buscar_hueco.