Eventos de calendario

CRUD sobre el calendario nativo de Finova. Cada evento pertenece a un usuario (el host) dentro de tu workspace; un mismo API key puede administrar el calendario de cualquier miembro del workspace pasando user_id.

Cuando el host tiene Google Calendar conectado, los eventos creados a través de esta API se sincronizan automáticamente con su calendario primario en Google (incluyendo Meet si lo solicitas).

El objeto Calendar Event

{
  "id":                "65a4b5c6d7e8f9012345abcd",
  "user_id":           "64f1a2b3c4d5e6f701234567",
  "title":             "Demo con Acme",
  "description":       "Walkthrough del producto + Q&A",
  "location":          "Online",
  "color":             "#2563eb",
  "starts_at":         "2026-05-20T17:00:00Z",
  "ends_at":           "2026-05-20T17:30:00Z",
  "all_day":           false,
  "timezone":          "America/Mexico_City",
  "kind":              "meeting",
  "source":            "native",
  "meet_url":          "https://meet.google.com/abc-defg-hij",
  "create_meet":       true,
  "attendees":         [{ "name": "Laura M.", "email": "laura@example.com" }],
  "reminders_minutes": [15],
  "google_event_id":   "evt_8fz2k...",
  "booking_link_id":   null,
  "booking_id":        null,
  "booker_lead_id":    null,
  "created_at":        "2026-05-15T10:00:00Z",
  "updated_at":        "2026-05-15T10:00:00Z"
}

Campos

Campo	Tipo	Descripción
id	string	ObjectId.
user_id	string	Host del evento. Debe pertenecer al workspace.
title	string	Título visible. Requerido.
description	string	Descripción libre.
location	string	Lugar (URL, dirección, etc.).
color	string	Color HEX para la UI. Default #2563eb.
starts_at	string	ISO 8601 UTC. Requerido.
ends_at	string	ISO 8601 UTC. Requerido, debe ser > starts_at.
all_day	bool	Evento de día completo. Default false.
timezone	string	IANA tz. Default America/Mexico_City.
kind	enum	event, meeting, task. Default event.
source	enum	Read-only. native, booking, google.
meet_url	string	Read-only para creación nueva; lo genera Google si pides Meet.
create_meet	bool	Solo aplica si kind != "task" y el host tiene Google Calendar conectado.
attendees	array	Lista de { name, email }. Recibirán invite vía Google (si conectado).
reminders_minutes	array	Recordatorios en minutos antes del evento. Default [15].
google_event_id	string	Read-only. ID del evento en Google si está sincronizado.
booking_link_id / booking_id / booker_lead_id	string	Read-only. Vínculos cuando el evento proviene de una liga de agenda.
created_at / updated_at	string	ISO 8601 UTC.

---

Listar eventos

GET/api/v1/calendar/eventsread-calendar_events

Query params: limit, starting_after, ending_before, include_total, page (ver Paginación).

Filtros adicionales:

Param	Descripción
user_id	Limita a eventos de un host específico.
kind	event, meeting o task.
source	native, booking o google.
from	ISO 8601. Eventos que terminan después de este timestamp.
to	ISO 8601. Eventos que comienzan antes de este timestamp.

Performance

La query usa el índice compuesto { company_id: 1, created_at: -1 } para paginación por cursor, y { company_id: 1, user_id: 1, starts_at: 1 } cuando filtras por user_id + rango temporal. Para volúmenes altos prefiere starting_after sobre page.

---

Obtener un evento

GET/api/v1/calendar/events/:idread-calendar_events

---

Crear un evento

POST/api/v1/calendar/eventscreate-calendar_events

Campos aceptados en data: user_id (requerido), title (requerido), description, location, color, starts_at (requerido), ends_at (requerido), all_day, timezone, kind, attendees, reminders_minutes, create_meet, sync_to_google (control fino: por default sincroniza si el host tiene Google conectado).

cURL

curl -X POST https://developers.fi-nova.com/api/v1/calendar/events \
  -H 'Authorization: Bearer finova_sk_TU_SECRETO' \
  -H 'Content-Type: application/json' \
  -d '{
    "data": {
      "user_id":   "64f1a2b3c4d5e6f701234567",
      "title":     "Demo con Acme",
      "starts_at": "2026-05-20T17:00:00Z",
      "ends_at":   "2026-05-20T17:30:00Z",
      "kind":      "meeting",
      "create_meet": true,
      "attendees": [{ "name": "Laura M.", "email": "laura@example.com" }]
    }
  }'

JavaScript

await fetch('https://developers.fi-nova.com/api/v1/calendar/events', {
  method: 'POST',
  headers: {
    Authorization:   'Bearer finova_sk_TU_SECRETO',
    'Content-Type':  'application/json',
  },
  body: JSON.stringify({
    data: {
      user_id:   '64f1a2b3c4d5e6f701234567',
      title:     'Demo con Acme',
      starts_at: '2026-05-20T17:00:00Z',
      ends_at:   '2026-05-20T17:30:00Z',
      kind:      'meeting',
      create_meet: true,
      attendees: [{ name: 'Laura M.', email: 'laura@example.com' }],
    },
  }),
});

---

Actualizar un evento

PATCH/api/v1/calendar/events/:idupdate-calendar_events

Mismos campos que create. Si el evento ya está sincronizado con Google, los cambios se propagan automáticamente. user_id no se puede cambiar después de creado: para reasignar el host, elimina y crea de nuevo.

---

Eliminar un evento

DELETE/api/v1/calendar/events/:iddelete-calendar_events

Borra el evento de Finova y, si está sincronizado, también de Google Calendar. 204 No Content en éxito.

---

Errores específicos

error	Cuándo
invalid_user (422)	user_id ausente o no pertenece al workspace del API key.
validation_failed (422)	Falta título, ends_at ≤ starts_at, kind inválido, etc.
not_found (404)	El evento no existe o pertenece a otro workspace.