Al terminar
Vas a tener este flujo funcionando.
- Consultar un rango en una zona horaria explícita.
- Elegir un intervalo libre desde la respuesta.
- Crear el evento sin duplicarlo ante una respuesta perdida.
Implementación
01
02
03
04
Seguí el contrato en este orden.
Definí la ventana
Enviá start, end, timezone y los calendarIds que la credencial puede consultar.
Interpretá los bloques ocupados
POST /freebusy.php es una consulta y no usa Idempotency-Key. Calculá candidatos fuera de los intervalos ocupados.
Revalidá cerca de la creación
No caches disponibilidad durante períodos largos. Volvé a consultar antes de confirmar una decisión sensible.
Creá el evento
Usá POST /events.php con una clave idempotente derivada de la reserva o solicitud externa.
Endpoints
Superficie utilizada.
POST
/api/v1/freebusy.php
Consultar ocupación en un rango
POST
/api/v1/events.php
Ocupar el horario elegido
GET
/api/v1/events.php?calendarId={id}
Confirmar el estado vigente
export PIETROCAL_API_TOKEN="pc_live_TU_TOKEN"
export PIETROCAL_CALENDAR_ID="18"
curl -sS -X POST \
"https://pietrocal.com/api/v1/freebusy.php" \
-H "Accept: application/json" \
-H "Content-Type: application/json" \
-H "Authorization: Bearer $PIETROCAL_API_TOKEN" \
--data-binary "{
\"calendarIds\": [$PIETROCAL_CALENDAR_ID],
\"start\": \"2026-08-05T09:00:00-03:00\",
\"end\": \"2026-08-05T18:00:00-03:00\",
\"timezone\": \"America/Argentina/Buenos_Aires\"
}"
curl -i -sS -X POST \
"https://pietrocal.com/api/v1/events.php" \
-H "Accept: application/json" \
-H "Content-Type: application/json" \
-H "Authorization: Bearer $PIETROCAL_API_TOKEN" \
-H "Idempotency-Key: turno-externo-20260805-1500" \
--data-binary "{
\"calendarId\": $PIETROCAL_CALENDAR_ID,
\"title\": \"Turno confirmado\",
\"start\": \"2026-08-05T15:00:00-03:00\",
\"end\": \"2026-08-05T15:30:00-03:00\",
\"allDay\": false
}"
Antes de publicar
Lista de verificación.
- Trabajá siempre con una zona horaria IANA explícita.
- Tratà la disponibilidad como una fotografía, no como un bloqueo.
- Usá una clave idempotente estable al convertir la decisión en evento.
- Ante 429, respetá Retry-After antes de volver a consultar.
Errores esperables
Tratamiento mínimo.
403 api_scope_requiredLa consulta necesita availability:read y la creación events:write.
422La ventana, la zona horaria o el calendario no son válidos.
409La creación ya no es compatible con el estado actual del recurso.
429Reducí la frecuencia de sondeo y respetá el reinicio indicado.