[Intum](https://intum.fr/aide.md) / [Formularze](https://intum.fr/aide/formularze.md)

# [Formularze](https://intum.fr/aide/formularze/formularze.md) | [API](#api)

## Do czego służą formularze

Formularze pozwalają zbierać dane od klientów i użytkowników zewnętrznych — bez konieczności logowania się do systemu. Formularz można osadzić na stronie internetowej jako widget lub udostępnić przez bezpośredni link.

## Zastosowania

- **Formularze kontaktowe** — zbieranie zapytań od klientów
- **Ankiety i badania** — NPS, oceny satysfakcji, ankiety wielopytaniowe
- **Rejestracja zgłoszeń** — przyjmowanie zgłoszeń serwisowych lub reklamacji
- **Zbieranie danych klientów** — automatyczne tworzenie kart klientów w CRM
- **Formularze wewnętrzne** — zbieranie danych od pracowników

## Typy formularzy

- **Prosty** — standardowy formularz z polami tekstowymi, listami wyboru i checkboxami
- **Zaawansowany** — formularz z dodatkowymi opcjami konfiguracji
- **NPS** — formularz Net Promoter Score
- **Kontaktowy** — gotowy szablon formularza kontaktowego

## Typy pól

- **Tekst (string)** — krótkie pole tekstowe
- **Textarea (text)** — wieloliniowe pole tekstowe
- **Lista wyboru (select)** — rozwijana lista opcji
- **Radio** — jednokrotny wybór z listy opcji
- **Checkbox** — wielokrotny wybór
- **Załącznik (attachment)** — upload pliku
- **Tytuł (title)** — nagłówek sekcji (nie zbiera danych)
- **Placeholder** — tekst opisowy między polami

## Mapowanie na obiekty

Wyniki formularza można automatycznie mapować na obiekty w systemie:

- **Klient CRM** — dane z formularza tworzą lub aktualizują kartę klienta
- **Zadanie** — zgłoszenie tworzy zadanie w module Organizacja
- **Email** — wynik wysyłany jako wiadomość email

Każde pole formularza może być przypisane do konkretnego pola docelowego (np. pole "Email" → email klienta).

## Powiadomienia

- **Powiadomienie dla operatora** — email na wybraną skrzynkę po każdym nowym zgłoszeniu
- **Potwierdzenie dla klienta** — automatyczny email do osoby wypełniającej formularz (wymaga pola email i skonfigurowanej skrzynki)
- Treść potwierdzenia obsługuje szablony Liquid z danymi z formularza

## Osadzanie na stronie

Formularz można osadzić na stronie przez:

- **Widget JavaScript** — skrypt generowany automatycznie, formularz ładuje się w kontenerze na stronie
- **Bezpośredni link** — publiczny URL z tokenem formularza

## Zabezpieczenia

- **Anti-spam** — honeypot i kontrola czasu wypełniania
- **Walidacja pól** — wymagane pola, walidacja email, cyfr, znaków alfanumerycznych
- **Okres aktywności** — formularz aktywny tylko w określonym przedziale dat

## Powiązane

- [Widget Formularza na Stronę](formularze-widget) — jak osadzić formularz na stronie
- [Zgłoszenia](zgloszenia) — przeglądanie i zarządzanie wynikami formularzy

---

## 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**

## API Endpoints

| Metoda | Ścieżka | Opis |
|--------|---------|------|
| GET | `/form/forms.json` | Lista formularzy |
| GET | `/form/forms/:id.json` | Pojedynczy formularz |
| POST | `/form/forms.json` | Utworzenie formularza |
| PATCH | `/form/forms/:id.json` | Aktualizacja formularza |
| DELETE | `/form/forms/:id.json` | Usunięcie formularza |

## Pola formularza

| Pole | Typ | Wymagane | Opis |
|------|-----|----------|------|
| `name` | string | tak | Nazwa formularza |
| `description` | text | nie | Opis formularza |
| `lang` | string | nie | Język: `pl`, `en`, `fr`, `cs`, `sk`, `de`, `es`, `uk` |
| `kind` | string | nie | Typ: `simple` (domyślnie), `advanced`, `nps`, `contact_basic`, `contact_advanced` |
| `date_from` | datetime | nie | Początek aktywności formularza |
| `date_to` | datetime | nie | Koniec aktywności formularza |
| `mapping` | string | nie | Mapowanie wyników: `client`, `task`, `email` |
| `mapping_options` | object | nie | Opcje mapowania (np. `{"auto_mapping": 1}`) |
| `team_id` | integer | nie | ID zespołu |
| `department_id` | integer | nie | ID działu |
| `notification_mailbox_id` | integer | nie | ID skrzynki do powiadomień |
| `confirmation_mailbox_id` | integer | nie | ID skrzynki do potwierdzeń klienta |
| `confirmation_subject` | string | nie | Temat emaila potwierdzenia |
| `confirmation_body` | string | nie | Treść emaila potwierdzenia (Liquid) |
| `client_email_field_id` | integer | nie | ID pola z emailem klienta (do potwierdzenia) |
| `fields` | object | nie | Ustawienia UI formularza |

### Pola w `fields`

| Klucz | Opis |
|-------|------|
| `submit_text` | Tekst przycisku wysłania |
| `form_class` | Klasa CSS formularza |
| `form_style` | Style CSS formularza |
| `form_redirect` | URL przekierowania po wysłaniu |
| `form_response` | HTML/Liquid zwrotka po wysłaniu |
| `form_anonymous` | Czy anonimowe (bez IP/agent) |
| `custom_js` | Własny JavaScript |
| `button_class` | Klasa CSS przycisku |

## Pola Form::FormField

| Pole | Typ | Wymagane | Opis |
|------|-----|----------|------|
| `name` | string | tak* | Nazwa pola (* nie dla placeholder) |
| `kind` | string | tak | Typ: `string`, `text`, `select`, `radio`, `checkbox`, `attachment`, `title`, `placeholder` |
| `required` | boolean | nie | Czy pole wymagane |
| `priority` | integer | nie | Kolejność wyświetlania |
| `description` | text | nie | Opis/placeholder pola |
| `regex` | string | nie | Walidacja: `email`, `digits`, `alphanum` |
| `map_to` | string | nie | Pole docelowe przy mapowaniu (np. `email`, `phone`, `name`) |
| `fields` | object | nie | Ustawienia pola |

### Pola w FormField `fields`

| Klucz | Opis |
|-------|------|
| `input_placeholder` | Placeholder tekst |
| `options` | Opcje dla select/radio/checkbox (rozdzielane `\r\n`) |
| `rows` | Liczba wierszy textarea |
| `class` | Klasa CSS pola |
| `code` | Nazwa zmiennej do Liquid |

## Format requestu

### POST — Utworzenie formularza z polami

```json
{
  "api_token": "TOKEN",
  "form": {
    "name": "Formularz kontaktowy",
    "description": "Formularz na stronę główną",
    "lang": "pl",
    "kind": "simple",
    "form_fields_attributes": [
      {
        "name": "Imię i nazwisko",
        "kind": "string",
        "required": true,
        "priority": 1,
        "map_to": "name"
      },
      {
        "name": "Email",
        "kind": "string",
        "required": true,
        "priority": 2,
        "regex": "email",
        "map_to": "email"
      },
      {
        "name": "Wiadomość",
        "kind": "text",
        "required": true,
        "priority": 3
      }
    ]
  }
}
```

### PATCH — Aktualizacja formularza

```json
{
  "api_token": "TOKEN",
  "form": {
    "name": "Zmieniona nazwa",
    "mapping": "client",
    "mapping_options": { "auto_mapping": 1 }
  }
}
```

## Endpointy publiczne (bez autoryzacji)

| Metoda | Ścieżka | Opis |
|--------|---------|------|
| GET | `/form/forms/:token/get_form` | Pobranie formularza publicznego (token) |
| POST | `/form/results/save` | Zapisanie wyniku formularza |

## Format odpowiedzi

### GET — Lista formularzy

```json
[
  {
    "id": 123,
    "name": "Formularz kontaktowy",
    "kind": "simple",
    "lang": "pl",
    "results_count": 45,
    "new_results_count": 3,
    "last_result_at": "2026-03-05T10:00:00+01:00",
    "date_from": null,
    "date_to": null,
    "token": "abc123token"
  }
]
```