Guía API: automatizar calendarios y eventos

Al terminar

Vas a tener este flujo funcionando.

Elegir un calendario autorizado por su ID real.
Crear un evento con fecha, zona horaria y título.
Repetir una solicitud ambigua sin crear un duplicado.

Implementación

Seguí el contrato en este orden.

Creá una credencial acotada

Para una automatización propia usá un token personal. Para conectar cuentas de terceros, usá OAuth 2.1 con PKCE.

Listá los calendarios visibles

GET /calendars.php devuelve solamente calendarios accesibles para el propietario de la credencial y conserva sus permisos reales.

Persistí tu referencia externa

Guardá el calendarId elegido y una clave idempotente estable derivada de la operación de tu sistema.

Creá el evento

POST /events.php requiere calendarId, title, start y end. Enviá Idempotency-Key para que un replay seguro reproduzca la respuesta.

Endpoints

Superficie utilizada.

GET /api/v1/calendars.php Listar calendarios autorizados

GET /api/v1/events.php?calendarId={id} Leer eventos del calendario

POST /api/v1/events.php Crear el evento idempotente

export PIETROCAL_API_TOKEN="pc_live_TU_TOKEN"
export PIETROCAL_CALENDAR_ID="18"
export EXTERNAL_OPERATION_ID="crm-reunion-20260804-184"

curl -sS "https://pietrocal.com/api/v1/calendars.php" \
  -H "Accept: application/json" \
  -H "Authorization: Bearer $PIETROCAL_API_TOKEN"

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: $EXTERNAL_OPERATION_ID" \
  --data-binary "{
    \"calendarId\": $PIETROCAL_CALENDAR_ID,
    \"title\": \"Reunión desde CRM\",
    \"start\": \"2026-08-04T15:00:00-03:00\",
    \"end\": \"2026-08-04T16:00:00-03:00\",
    \"allDay\": false,
    \"description\": \"Referencia externa: $EXTERNAL_OPERATION_ID\"
  }"

Antes de publicar

Lista de verificación.

Confirmá HTTP 201 en la primera creación.
Conservá X-Request-Id y los headers de cuota.
Ante un corte ambiguo, repetí exactamente la misma clave y el mismo cuerpo.
No reintentes con una clave nueva porque eso representa otra creación.

Errores esperables

Tratamiento mínimo.

403 api_scope_required

La credencial no tiene el scope de lectura o escritura requerido.

409 idempotency_key_conflict

La misma clave fue reutilizada con un cuerpo diferente.

425 idempotency_request_in_progress

Otra ejecución con la misma clave todavía está en curso.

429

Respetá Retry-After y no hagas reintentos inmediatos en bucle.

Automatizá una agenda sin duplicar eventos.