Base URL https://api.afer.pro Referencia aferapp.com Reservar demo

Buscar hueco libre

GET https://api.afer.pro/api/v1/schedules/free-slots
Alias en castellano (v0, sigue operativo): 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.

Autenticación

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.

empleadoIdsarray
opcional
Las personas (id cifrado, correo o nombre); en GET, separadas por comas. Vacío = quien llama. Hasta 10.
duracion_minutosinteger
obligatorio
Cuánto tiene que durar, de 5 a 720.
fecha_iniciostring
opcional
Desde. Por defecto hoy.
fecha_finstring
opcional
Hasta. Por defecto 14 días; como mucho 62.
desde_horastring
opcional
Solo a partir de esta hora (HH:MM).
hasta_horastring
opcional
Solo hasta esta hora (HH:MM).
limiteinteger
opcional
Cuántos huecos. Por defecto 8, máximo 30.
horario_por_defectoboolean
opcional
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

200 · application/json
{
    "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

CasoResultado
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.
Notas

Por MCP es buscar_hueco.