[Intum](https://intum.pl/pomoc.md) / [Kalendarz](https://intum.pl/pomoc/kalendarz.md)

# [Wydarzenia](https://intum.pl/pomoc/kalendarz/kalendarz.md) | [API](#api)

Moduł kalendarza w Intum służy do planowania spotkań, terminów i powtarzających się wydarzeń. Każde wydarzenie należy do jakiegoś kalendarza, a kalendarzy w obrębie konta może być dowolnie wiele.

## Wiele kalendarzy

Kalendarze możesz organizować jak chcesz - najczęściej firmy robią tak:

- jeden kalendarz dla całej firmy (urlopy, święta, ważne terminy)
- osobne kalendarze dla działów (Sprzedaż, Serwis, Marketing)
- prywatne kalendarze konkretnych osób (`Kalendarz Jana`, `Kalendarz Barbary`)
- kalendarze tematyczne (Spotkania z klientami, Szkolenia, Webinary)

Każdy kalendarz ma swoją nazwę, opis i kolor. Kolor wydarzenia w widoku siatki bierze się z kalendarza (jeśli wydarzenie nie ma własnego koloru). Przy pierwszym wejściu w moduł system tworzy domyślny kalendarz konta - nazywa się tak samo jak konto i działa jako worek na wydarzenia, które nie pasują nigdzie indziej.

## Widoki

W kalendarzu masz trzy główne widoki:

1. **Miesiąc** - cała siatka miesięczna z wydarzeniami w komórkach dni
2. **Tydzień** - siedem kolumn dni z godzinami od góry do dołu
3. **Pojedynczy kalendarz** - to samo co wyżej, ale tylko dla jednego wybranego kalendarza

Wydarzenia całodniowe pokazują się w pasku nad siatką godzin, reszta lokuje się w slotach godzinowych. Po kliknięciu wydarzenia otwiera się popover z nazwą, opisem, godziną, kalendarzem, klientem (jeśli przypięty) i przyciskami `Pokaż` / `Edytuj`.

## Tworzenie wydarzenia

Nowe wydarzenie dodajesz przyciskiem `+` w module Kalendarz albo bezpośrednio z karty klienta (patrz niżej). Pola formularza:

- **Nazwa** - wymagane
- **Opis** - dowolny tekst
- **Początek** i **Koniec** - daty z godziną. Końca nie musi być (wydarzenie punktowe)
- **Całodniowe** - przełącznik, ukrywa godziny
- **Kolor** - jeśli pusty, brany jest kolor kalendarza
- **Kalendarz** - do którego ma trafić
- **Klient** - opcjonalne powiązanie z klientem CRM
- **Cykliczność** - opisana niżej

## Cykliczne wydarzenia

Każde wydarzenie może się powtarzać. Cykliczność nie tworzy 365 osobnych rekordów w bazie - to jeden rekord, który jest dynamicznie rozwijany na siatce kalendarza. Dzięki temu nie zaśmieca bazy i można jednym kliknięciem zmienić wszystkie wystąpienia.

Dostępne typy:

- **Codziennie** - co dzień, co drugi dzień, co N dni
- **Co tydzień** - z możliwością wybrania konkretnych dni tygodnia (np. tylko pon-śr-pt)
- **Co miesiąc** - tego samego dnia miesiąca
- **Co rok** - tej samej daty co roku (urodziny, rocznice)

Dla każdego typu możesz ustawić **interwał** - co ile jednostek powtórzyć. Na przykład "co 2 tygodnie w środy" to typ tygodniowy z interwałem 2 i wybraną środą.

Dodatkowo:

- **Data zakończenia** - od kiedy wydarzenie przestaje się powtarzać. Pusta = powtarza się bez końca
- **Liczba wystąpień** - alternatywa dla daty zakończenia, kończy serię po N wystąpieniach

W widoku wydarzenie cykliczne ma podpis pod nazwą (`Co tydzień`, `Co rok` itd.).

## Wydarzenia Klienta

Aby dodać wydarzenie powiązane z klientem, wejdź w **podgląd klienta**, kliknij przycisk \*\*`+ Dodaj`\*\* i wybierz **`Dodaj wydarzenie`**. Otworzy się formularz nowego wydarzenia z już wpisanym klientem - wystarczy nadać nazwę, ustawić termin i zapisać. Po dodaniu wydarzenie pojawia się na karcie klienta w zakładce **Wydarzenia**.

Na karcie klienta CRM zakładka **Wydarzenia** pokazuje wszystkie wydarzenia, które mają tego klienta przypiętego.

Dodane w ten sposób wydarzenie pojawi się w trzech miejscach:

1. Na karcie klienta (zakładka Wydarzenia)
2. W kalendarzu, do którego trafiło (domyślnie kalendarz konta)
3. W zbiorczym widoku Kalendarz (siatka miesiąca/tygodnia)

Dzięki temu masz jedną sprawę w trzech kontekstach - patrząc na klienta widzisz, kiedy się z nim spotykasz; patrząc na kalendarz widzisz, że ten slot to spotkanie z konkretną firmą.

## Powiązania z innymi obiektami

Wydarzenie może być przypięte nie tylko do klienta, ale też do dowolnego obiektu w systemie. Wykorzystujemy to np. dla zamówień w Commerce - termin dostawy generuje wydarzenie z kolorem statusu zamówienia. Po kliknięciu w popoverze widać nazwę powiązanego obiektu.

## Wyszukiwarka i filtry

W liście wydarzeń można filtrować:

- po **kalendarzu**
- po **kliencie**
- po **zakresie dat** (od - do)
- tryb **najbliższe wydarzenia** - lista nadchodzących pozycji w dół, łącznie z rozwiniętymi wystąpieniami cyklicznych

## Najczęstsze pytania

**Jak ustawić wydarzenie urodzinowe?** Typ `Co rok`, bez daty końca. Najłatwiej dodać z karty klienta - wtedy automatycznie zostanie do niego przypięte.

**Co się stanie, gdy usunę kalendarz?** Wydarzenia z tego kalendarza nie znikają - zostaną odpięte i będą widoczne w widoku ogólnym bez przypisania.

**Czy wydarzenie cykliczne można zmienić tylko dla jednego dnia?** Aktualnie nie - edycja wydarzenia cyklicznego dotyczy wszystkich wystąpień. Jeśli chcesz wyjątek, dodaj osobne jednorazowe wydarzenie i ewentualnie skróć serię.

---

## API

### Ogólne API

# Intum API

Dokumentacja API platformy [Intum](https://intum.pl) - system operacyjny firmy.

## Host

Host jest zawsze taki sam jak adres konta: `xxxx.intum.com` lub `xxx.intum.pl` (w zależności od ustawień konta)

## Autoryzacja

Wszystkie requesty API wymagają `api_token`:
- header: `Authorization: Bearer TOKEN`

Token możesz wygenerować w **Ustawienia Konta** → **Tokeny API**

## Endpointy API kalendarza

Autoryzacja: `Authorization: Bearer TOKEN`. Token wymaga uprawnienia `calendar`.

### Kalendarze

| Metoda | Ścieżka | Opis |
|--------|---------|------|
| GET | `/calendar/calendars.json` | Lista kalendarzy konta |
| GET | `/calendar/calendars/:id.json` | Pojedynczy kalendarz |
| POST | `/calendar/calendars.json` | Utworzenie kalendarza |
| PATCH | `/calendar/calendars/:id.json` | Aktualizacja |
| DELETE | `/calendar/calendars/:id.json` | Usunięcie (wydarzenia są odpinane, nie usuwane) |

Pola kalendarza:

| Pole | Typ | Opis |
|------|-----|------|
| `name` | string | Nazwa (wymagane) |
| `description` | text | Opis |
| `color` | string | Kolor w formacie hex `#3b82f6` |

### Wydarzenia

| Metoda | Ścieżka | Opis |
|--------|---------|------|
| GET | `/calendar/events.json` | Lista wydarzeń |
| GET | `/calendar/events/:id.json` | Pojedyncze wydarzenie |
| POST | `/calendar/events.json` | Utworzenie |
| PATCH | `/calendar/events/:id.json` | Aktualizacja |
| DELETE | `/calendar/events/:id.json` | Usunięcie |

Parametry GET listy:

- `calendar_id` - filtr po kalendarzu
- `client_id` - filtr po kliencie CRM
- `eventable_type` - filtr po typie powiązanego obiektu
- `from`, `to` - zakres dat (`YYYY-MM-DD`)
- `upcoming=1` - tryb najbliższych wydarzeń, rozwija cykliczne w wirtualne wystąpienia
- `limit` - liczba wyników w `upcoming` (domyślnie 10, max 30)

Pola wydarzenia:

| Pole | Typ | Opis |
|------|-----|------|
| `name` | string | Nazwa (wymagane) |
| `description` | text | Opis |
| `start_time` | datetime | Początek (wymagane) |
| `end_time` | datetime | Koniec (opcjonalne, dla wydarzeń punktowych) |
| `all_day` | boolean | Całodniowe |
| `color` | string | Kolor hex; pusty = kolor kalendarza |
| `calendar_id` | integer | ID kalendarza |
| `client_id` | integer | ID klienta z CRM (opcjonalne) |
| `recurrence_type` | string | `daily`, `weekly`, `monthly`, `yearly` lub null |
| `recurrence_interval` | integer | Co ile jednostek powtórzyć (domyślnie 1) |
| `recurrence_end_date` | date | Do kiedy się powtarza (puste = bez końca) |
| `recurrence_count` | integer | Maksymalna liczba wystąpień |
| `recurrence_days` | array | Dni tygodnia dla `weekly`, np. `["mon","wed","fri"]` |

### Tworzenie wydarzenia

```
POST /calendar/events.json
Authorization: Bearer TOKEN
Content-Type: application/json
```

Proste, jednorazowe:

```json
{
  "event": {
    "name": "Spotkanie z klientem ACME",
    "start_time": "2026-05-12T10:00:00",
    "end_time": "2026-05-12T11:00:00",
    "calendar_id": 3,
    "client_id": 471
  }
}
```

Cotygodniowe (poniedziałki i środy, do końca roku):

```json
{
  "event": {
    "name": "Standup",
    "start_time": "2026-05-04T09:00:00",
    "end_time": "2026-05-04T09:15:00",
    "calendar_id": 3,
    "recurrence_type": "weekly",
    "recurrence_interval": 1,
    "recurrence_days": ["mon", "wed"],
    "recurrence_end_date": "2026-12-31"
  }
}
```

Urodziny klienta (rocznie, bez końca):

```json
{
  "event": {
    "name": "Urodziny - Jan Kowalski",
    "start_time": "2026-06-15T00:00:00",
    "all_day": true,
    "client_id": 471,
    "recurrence_type": "yearly"
  }
}
```

### Odpowiedź (201 Created)

```json
{
  "id": 1234,
  "name": "Spotkanie z klientem ACME",
  "start_time": "2026-05-12T10:00:00.000+02:00",
  "end_time": "2026-05-12T11:00:00.000+02:00",
  "calendar_id": 3,
  "client_id": 471,
  "recurrence_type": null,
  "effective_color": "#3b82f6",
  "token": "event_token_xxx"
}
```

### Pobranie wydarzeń klienta

```
GET /calendar/events.json?client_id=471
```

Zwraca wszystkie wydarzenia, do których przypięty jest klient o ID 471. Tych samych danych używa zakładka `Wydarzenia` na karcie klienta CRM.

### Najbliższe wydarzenia (upcoming)

```
GET /calendar/events.json?upcoming=1&limit=20
```

Zwraca posortowaną listę najbliższych wydarzeń w okresie 90 dni naprzód. Wydarzenia cykliczne są rozwijane na poszczególne wystąpienia (każde z własnym `start_time`, ale tym samym `id` rekordu). Idealne do widgetu "Co masz dziś" lub "Najbliższe spotkania".