Calendar Events

Overview

The Calendar API provides endpoints for retrieving available time slots and creating calendar events for booked virtual classes. Events are automatically integrated with Google Calendar and include Google Meet conference links.

Get Calendar Events

Retrieve upcoming calendar events to display available time slots for class booking.

Endpoint

GET /api/calendar

Response

events

array

Array of calendar events with start time, end time, and status

Show Event Object

start

object

Start time information

Show properties

dateTime

string

ISO 8601 datetime string

end

object

End time information

Show properties

dateTime

string

ISO 8601 datetime string

status

string

Event status: confirmed, tentative, or cancelled

Example Request

curl https://your-domain.com/api/calendar

Example Response

[
  {
    "start": {
      "dateTime": "2024-03-15T17:00:00-03:00"
    },
    "end": {
      "dateTime": "2024-03-15T18:30:00-03:00"
    },
    "status": "confirmed"
  },
  {
    "start": {
      "dateTime": "2024-03-16T19:00:00-03:00"
    },
    "end": {
      "dateTime": "2024-03-16T20:30:00-03:00"
    },
    "status": "confirmed"
  }
]

Error Responses

Show 500 - Server Error

{
  "error": "Failed to fetch calendar events"
}

Create Calendar Event

Create a Google Calendar event with Google Meet link after successful payment. This endpoint is typically called by the webhook handler after payment confirmation.

Endpoint

POST /api/calendar

Authentication

Requires admin-level OAuth2 refresh token stored in the database.

Request Body

preferenceId

string

required

Mercado Pago preference ID linking the payment to the virtual class

Response

success

boolean

Whether the calendar event was created successfully

message

string

Success message: “Event created successfully”

Example Request

curl -X POST https://your-domain.com/api/calendar \
  -H "Content-Type: application/json" \
  -d '{
    "preferenceId": "123456789-abc123"
  }'

Example Response

{
  "success": true,
  "message": "Event created successfully"
}

Error Responses

Show 400 - Missing Parameter

{
  "error": "Missing preferenceId"
}

Show 404 - Virtual Class Not Found

{
  "error": "Virtual class not found"
}

Show 500 - Server Error

{
  "error": "Failed to create calendar event"
}

Implementation Details

Event Creation Flow

Retrieve Virtual Class

Find the virtual class record using the provided preferenceId

OAuth Authentication

Use admin refresh token to authenticate with Google Calendar API

Create Google Calendar Event

Create event with Google Meet conference link enabled

Update Database

Store googleEventId and htmlLink in the VirtualClass record

Google Calendar Configuration

The calendar event includes:

Summary: Class type and learning focus
Description: Detailed class information
Conference: Google Meet link automatically generated
Timezone: America/Argentina/Buenos_Aires
Attendees: Student email address
Reminders: Email notification 60 minutes before start

Environment Variables

CALENDAR_ID

string

required

Google Calendar ID where events are created

AUTH_GOOGLE_ID

string

required

Google OAuth2 client ID

AUTH_GOOGLE_SECRET

string

required

Google OAuth2 client secret

GOOGLE_REDIRECT_URI

string

required

OAuth2 redirect URI configured in Google Cloud Console

ADMIN_EMAIL

string

required

Admin email address with calendar access

Virtual Classes

Learn about the class booking system

Payment System

Understand the payment flow that triggers calendar events

Calendar Integration

Detailed guide on Google Calendar setup

Calendar Setup

Admin configuration for Google Calendar

Authentication

Classes

Payments

User Data

Calendar

Overview

Get Calendar Events

Endpoint

Response

Example Request

Example Response

Error Responses

Create Calendar Event

Endpoint

Authentication

Request Body

Response

Example Request

Example Response

Error Responses

Implementation Details

Event Creation Flow

Google Calendar Configuration

Environment Variables

Virtual Classes

Payment System

Calendar Integration

Calendar Setup

Build docs developers (and LLMs) love

Authentication

Classes

Payments

User Data

Calendar

​Overview

​Get Calendar Events

​Endpoint

​Response

​Example Request

​Example Response

​Error Responses

​Create Calendar Event

​Endpoint

​Authentication

​Request Body

​Response

​Example Request

​Example Response

​Error Responses

​Implementation Details

​Event Creation Flow

​Google Calendar Configuration

​Environment Variables

​Related Resources

Virtual Classes

Payment System

Calendar Integration

Calendar Setup

Build docs developers (and LLMs) love

Overview

Get Calendar Events

Endpoint

Response

Example Request

Example Response

Error Responses

Create Calendar Event

Endpoint

Authentication

Request Body

Response

Example Request

Example Response

Error Responses

Implementation Details

Event Creation Flow

Google Calendar Configuration

Environment Variables

Related Resources