[Intum](https://intum.pl/pomoc.md) / [CRM](https://intum.pl/pomoc/crm.md) # [Automatyczna synchronizacja danych klientów pomiędzy własną aplikacją a Intum CRM](https://intum.pl/pomoc/crm/automatyczna-synchronizacja-danych-klientow.md) | [API](#api) Jeśli dane o klientach żyją w Twoim systemie (ERP, sklepie, własnej aplikacji), nie musisz ich przepisywać do Intum ręcznie ani wgrywać plików. Aplikacja "CRM - import i synchronizacja klientów" daje stały kanał: Twój system wysyła dane, a Intum na bieżąco tworzy i aktualizuje klientów w CRM. Dzięki temu np. dział marketingu może wysyłać kampanie do grup klientów wybranych po aktualnych danych - planie, saldzie, statusie - bez czekania na ręczne importy. ## Krok 1. Zainstaluj aplikację Wejdź w Ustawienia konta - Aplikacje i dodatki, znajdź "CRM - import i synchronizacja klientów" i kliknij Zainstaluj. Po instalacji panel aplikacji znajdziesz pod adresem /a/crm-data-ingest (link pojawi się też w ustawieniach CRM). Tak wygląda panel aplikacji: ![Panel aplikacji CRM - import i synchronizacja klientów](08dcaf2b6416-crm_ingest_panel.png) ## Krok 2. Załóż pola własne Zastanów się, jakie informacje o kliencie chcesz widzieć w CRM poza standardowymi (nazwa, NIP, adres, email). Może to być np. plan abonamentowy, saldo, data ostatniej płatności, status współpracy. Każdą taką informację załóż jako pole własne klienta w module Automatyzacja - Pola własne (panel aplikacji ma bezpośredni link). To ważne: przy imporcie zapisywane są tylko wartości pól, które wcześniej zdefiniujesz. Nieznane pola są pomijane, a ich liczba widoczna w statystykach - łatwo więc wyłapiesz literówkę w nazwie pola. ## Krok 3. Utwórz token dla swojego systemu W panelu aplikacji kliknij "Utwórz token tylko do importu". Powstanie klucz dostępu ograniczony wyłącznie do wysyłania danych - Twój system nie będzie mógł nim zrobić niczego innego w Intum, więc można go bezpiecznie przekazać np. zewnętrznej firmie utrzymującej Twój ERP. Token jest pokazywany tylko raz - skopiuj go od razu. ## Krok 4. Skopiuj gotowy przykład i podłącz swój system Panel aplikacji generuje gotowy do użycia przykład zapytania (curl) na podstawie Twoich pól własnych - z adresem, tokenem i przykładowymi wartościami. Przekaż go osobie technicznej odpowiedzialnej za Twój system. W przykładzie jest jedno miejsce do świadomej decyzji: nazwa źródła (source_code), np. "moj_erp" albo "sklep". Ta nazwa wiąże identyfikatory klientów z Twojego systemu z klientami w CRM, więc raz wybranej nie zmieniaj. Dane można wysyłać pojedynczo (przy każdej zmianie klienta) albo paczkami do 5000 rekordów - przy pierwszym zasileniu całej bazy używaj paczek. ## Przykład: co wysyła Twój system Poniżej przykładowe zapytanie dla konta "twojafirma" z dwoma polami własnymi: "plan" i "saldo" (najpierw załóż je w polach własnych klienta). Adres i token znajdziesz w panelu aplikacji. ``` POST https://twojafirma.intum.com/automation/import_batches.json Authorization: Bearer TWOJ_TOKEN Content-Type: application/json ``` ```json { "kind": "crm_clients", "source_code": "moj_erp", "batch_id": "2026-08-21-0001", "clients": [ { "external_id": "123", "name": "Firma Przykładowa Sp. z o.o.", "email": "kontakt@firma.pl", "tax_no": "5551112233", "fields": { "plan": "premium", "saldo": 199.99 } }, { "external_id": "124", "name": "Jan Kowalski", "email": "jan@kowalski.pl", "fields": { "plan": "podstawowy", "saldo": 0 } } ] } ``` Pole "batch_id" to identyfikator paczki nadawany przez Twój system (np. numer kolejny albo data z licznikiem). Chroni przed podwójnym przetworzeniem: gdy po błędzie połączenia wyślesz tę samą paczkę ponownie, Intum rozpozna ją po batch_id i pominie duplikat - przy błędach zawsze bezpiecznie jest ponowić wysyłkę. W odpowiedzi dostaniesz potwierdzenie przyjęcia (202) - dane pojawią się w CRM po chwili, gdy bufor zostanie przetworzony. ## Co się dzieje po wysłaniu Dane trafiają najpierw do bufora (dostajesz natychmiastowe potwierdzenie), a Intum przetwarza je w tle: - klient, którego jeszcze nie ma w CRM, zostanie utworzony automatycznie - jeśli klient już istnieje, ale nie był jeszcze powiązany z Twoim systemem, Intum spróbuje go dopasować - domyślnie po NIP-ie lub numerze rejestrowym (w ustawieniach można włączyć też dopasowanie po emailu i telefonie albo je wyłączyć) - ponowne wysłanie tej samej paczki jest bezpieczne - duplikat zostanie rozpoznany i pominięty W panelu aplikacji ustawisz też, czy import ma nadpisywać wypełnione pola, czy tylko uzupełniać puste. ## Monitorowanie Panel pokazuje listę źródeł z datą ostatniej wrzutki i liczbą paczek czekających w buforze, ostatnie paczki oraz statystyki przetwarzania: ilu klientów utworzono, zaktualizowano, powiązano, ile było błędów i jakie nieznane pola się pojawiły. ## Co dalej: kampanie do grup klientów Gdy dane płyną, pola własne klientów są dostępne w zaawansowanym filtrze CRM i w listach odbiorców Marketing Automation typu "filtr". Możesz np. utworzyć listę "klienci z planem premium i saldem powyżej zera" - lista odświeża się automatycznie przed każdą wysyłką kampanii. --- ## 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** ## CRM Data Ingest - API Bufor importów danych klientów. Autoryzacja: `Authorization: Bearer TOKEN` z uprawnieniem `automation_import` (token można ograniczyć wyłącznie do tego uprawnienia). Throttle: 2000 requestów/min per konto - operacje masowe wysyłaj batchami. ### Wysyłka ``` POST /automation/import_batches.json ``` ```json { "kind": "crm_clients", "source_code": "moj_system", "batch_id": "unikalny-id-batcha", "clients": [ { "external_id": "123", "name": "Firma Przykładowa", "email": "kontakt@firma.pl", "tax_no": "5551112233", "fields": { "plan": "premium", "saldo": 199.99 } } ] } ``` | Pole | Wymagane | Opis | |------|----------|------| | `kind` | nie | obecnie tylko `crm_clients` (default) | | `source_code` | tak | stała nazwa źródła `[a-z][a-z0-9_]*` - przestrzeń identyfikatorów `external_id`; nie zmieniać po starcie | | `batch_id` | nie | klucz idempotencji retry (duplikat -> `"duplicate": true`); bez niego hash treści | | `clients[].external_id` | tak | id klienta w systemie źródłowym | | `clients[].fields` | nie | pola własne - zapisywane tylko klucze zdefiniowane w `Automation::CustomField`; nieznane pomijane i zliczane | Limit: 5000 rekordów na request. Odpowiedź: `202 Accepted` + `{ status, accepted, batch_id, duplicate }`. Przetwarzanie asynchroniczne (flow z debouncem + godzinowy cron-backstop). Wysyłaj pełny aktualny stan klienta, nie delty - dedup po `external_id` w batchu, ostatni stan wygrywa. Pola stałe klienta: `name, shortcut, first_name, last_name, company, email, phone, mobile_phone, www, tax_no, register_number, street, post_code, city, province, country, note, description, kind`. ### Podgląd i konfiguracja ``` GET /automation/import_batches.json?processed=false&source_code=... # batche w buforze GET /automation/import_batches/:id.json # pojedynczy batch GET /automation/import_batches/settings.json # konfiguracja, pola własne, źródła, statystyki PATCH /automation/import_batches/settings.json # { "settings": { "duplicate_policy": "match_tax_no|match_contacts|external_id_only", "update_existing": true, "batch_size": 2000 } } ``` --- ## Powiązane - [Import klientów z Fakturowni](https://intum.pl/pomoc/crm/import-klientow-z-fakturowni.md) - [Klienci](https://intum.pl/pomoc/crm/klienci.md)