[Intum](https://intum.fr/aide.md) / [CRM](https://intum.fr/aide/crm.md)

# [Klienci](https://intum.fr/aide/crm/klienci.md) | [API](#api)

## Klienci CRM

Klient to centralny obiekt w CRM - reprezentuje firmę albo osobę, z którą współpracujesz. Wokół niego krążą kontakty, interesy, zadania, faktury i cała historia kontaktu.

## Rodzaje klientów

- **Nabywca (buyer)** - kupuje od was usługi lub produkty
- **Dostawca (supplier)** - to wy kupujecie od niego

## Dane klienta

### Podstawowe

- Nazwa firmy lub imię i nazwisko
- E-mail, telefon, telefon komórkowy
- NIP, REGON, PESEL
- Strona internetowa, domena

### Adres

- Ulica, kod pocztowy, miasto, województwo, kraj
- Opcjonalny adres dostawy (jeśli inny niż główny)

### Dane finansowe

- Bank i numer konta
- Kwota rozliczeń, okres płatności
- Rabat

## Co można dodać z poziomu klienta (+ Dodaj)

Na karcie klienta jest przycisk **+ Dodaj** - rozwija menu z elementami, które od razu zostaną powiązane z tym klientem (wstępnie wypełnione `client_id`, dane teleadresowe itp.).

W menu znajdziesz:

- **Kontakt** - osoba powiązana z klientem (pracownik, decydent)
- **Interes** - szansa sprzedażowa
- **E-mail** - nowa wiadomość, `to:` podpowiada się z e-maila klienta
- **Zadanie** - powiązane z klientem
- **Zgłoszenie helpdesk** - ticket od tego klienta
- **Notatka** - krótki wpis w historii
- **Dokument** - plik na dysku przypisany do klienta
- **Połączenie VoIP** - rejestracja rozmowy
- **Czas pracy** - workinfo do rozliczeń
- **Lista zadań (tasklist)** - grupa zadań
- **Projekt** - z klientem jako właścicielem
- **Faktura** - dokument sprzedażowy
- **Zamówienie** - dokument zamówienia
- **Oferta/Zlecenie** - quotation; na liście sprzedaży oznaczona badge'em "Oferta"
- **Wydarzenie** - w kalendarzu, z klientem powiązanym

Część pozycji pojawia się tylko, gdy aktywny jest odpowiedni moduł (np. faktury, zamówienia i oferty wymagają modułu Sprzedaż; wydarzenia - Kalendarza).

Obok **+ Dodaj** widoczny bywa też przycisk **Generuj dokument z szablonu** - pojawia się, gdy w systemie są szablony dla klientów. Jeśli ich jeszcze nie ma, w menu **+ Dodaj** dochodzi pozycja **Dodaj szablon dokumentu**.

## Kontakty

Każdy klient może mieć wiele [kontaktów](kontakty) - osób z nim powiązanych. Jeden kontakt jest oznaczony jako główny i to jego dane podpowiadają się np. przy mailach.

## Statusy

Klient ma przypisany [status](statusy-crm) - typowo "Nowy", "Aktywny", "VIP", "Nieaktywny". Statusy zmienisz pojedynczo z karty klienta albo masowo z listy.

## Tagi

Klientów można oznaczać tagami. Pomagają w segmentacji i szybkim filtrowaniu listy.

## Boxy na karcie klienta

Karta klienta pokazuje boxy z powiązanymi obiektami:

- [Kontakty](kontakty), [Interesy](interesy), [Notatki](notatki)
- Zadania, e-maile, połączenia, zgłoszenia helpdesk, czaty, dokumenty
- **Sprzedaż** - zamówienia i oferty z tym klientem; przy quotation pojawia się badge "Oferta"
- Faktury, projekty, wydarzenia

Boxy są dynamiczne - sekcja, w której nie ma żadnych powiązanych rekordów, jest ukrywana.

## Łączenie klientów

Ten sam klient mógł trafić do bazy kilka razy (różny zapis NIP, literówki). Zamiast usuwać duplikaty - scal je. System przeniesie wszystkie powiązania (kontakty, faktury, maile, zadania) do jednego rekordu.

## Archiwizacja

Klienta można zarchiwizować zamiast usuwać. Nie pojawia się na domyślnych listach, ale dane i historia są zachowane. Można go w każdej chwili przywrócić.

## Zewnętrzne ID (external_id)

Pole na identyfikator z zewnętrznego systemu (inne CRM, ERP, sklep). Przydaje się przy:

- synchronizacji z innym systemem
- wyszukiwaniu po kluczu zewnętrznym
- upsercie przez API (`POST /crm/clients/upsert.json`)

## Wyszukiwanie GUS

Wpisz NIP - system sięgnie do rejestru GUS (BIR) i podpowie nazwę firmy, adres oraz REGON. Oszczędza ręcznego wpisywania danych firmowych.

---

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

| Metoda | Ścieżka | Opis |
|--------|---------|------|
| GET | `/crm/clients.json` | Lista klientów |
| GET | `/crm/clients/:id.json` | Pojedynczy klient |
| POST | `/crm/clients.json` | Utworzenie klienta |
| PATCH | `/crm/clients/:id.json` | Aktualizacja klienta |
| DELETE | `/crm/clients/:id.json` | Usunięcie klienta |
| POST | `/crm/clients/upsert.json` | Utwórz lub zaktualizuj (po external_id) |
| GET | `/crm/clients/autocomplete.json` | Wyszukiwanie (autocomplete) |
| POST | `/crm/clients/:id/change_bulk_option` | Zmiana statusu |
| POST | `/crm/clients/merge_clients` | Scalenie klientów |
| GET | `/crm/clients/e/:external_id.json` | Pobranie po external_id |

**Autoryzacja:** `Authorization: Bearer TOKEN` (uprawnienie: **crm**)

## Pola client

| Pole | Typ | Wymagane | Opis |
|------|-----|----------|------|
| `name` | string | tak | Nazwa klienta |
| `first_name` | string | nie | Imię |
| `last_name` | string | nie | Nazwisko |
| `kind` | string | nie | `buyer` lub `supplier` |
| `company` | boolean | nie | Czy firma |
| `email` | string | nie | E-mail |
| `phone` | string | nie | Telefon |
| `mobile_phone` | string | nie | Telefon komórkowy |
| `tax_no` | string | nie | NIP (unikalny per konto) |
| `register_number` | string | nie | REGON |
| `street` | string | nie | Ulica |
| `post_code` | string | nie | Kod pocztowy |
| `city` | string | nie | Miasto |
| `country` | string | nie | Kod kraju |
| `www` | string | nie | Strona internetowa |
| `domain` | string | nie | Domena firmy |
| `description` | text | nie | Opis |
| `note` | text | nie | Notatka |
| `status_id` | integer | nie | ID statusu |
| `responsible_id` | integer | nie | ID odpowiedzialnego |
| `department_id` | integer | nie | ID działu |
| `project_id` | integer | nie | ID projektu |
| `category_id` | integer | nie | ID kategorii |
| `external_id` | string | nie | Zewnętrzne ID (unikalne per konto) |
| `score` | decimal | nie | Scoring klienta |
| `origin` | string | nie | Źródło pozyskania |
| `archive` | boolean | nie | Archiwizacja |
| `tags` | array | nie | Tagi `["vip", "premium"]` |
| `fields` | object | nie | Własne pola (JSONB) |

## Filtrowanie (GET /crm/clients.json)

| Parametr | Opis |
|----------|------|
| `q` | Wyszukiwanie pełnotekstowe |
| `status_id` | Filtruj po statusie |
| `responsible_id` | Filtruj po odpowiedzialnym |
| `department_id` | Filtruj po dziale |
| `project_id` | Filtruj po projekcie |
| `tag_ids` | Filtruj po tagach |
| `archive` | `true` = zarchiwizowani |

## Upsert (utwórz lub zaktualizuj)

```json
{
  "api_token": "TOKEN",
  "client": {
    "external_id": "CRM-123",
    "name": "Firma ABC",
    "email": "kontakt@firma.pl"
  }
}
```

Jeśli klient z `external_id: "CRM-123"` istnieje — zostanie zaktualizowany. Jeśli nie — utworzony.

## Przykład utworzenia

```json
{
  "api_token": "TOKEN",
  "client": {
    "name": "Firma ABC",
    "kind": "buyer",
    "email": "kontakt@firma.pl",
    "phone": "+48123456789",
    "tax_no": "PL1234567890",
    "city": "Warszawa",
    "status_id": 1
  }
}
```