Integracja skracacza URL z Notion: OAuth + dwukierunkowa synchronizacja bazy danych

Integracja skracacza URL z Notion przeszła z wersji Beta do wersji Live 4 czerwca 2026 roku. Jeśli używasz Notion jako centrum kampanii, Elido odczytuje URL-e z dowolnej wybranej bazy danych, tworzy markowe krótkie linki na Twojej domenie, zapisuje je z powrotem do tabeli i śledzi zmiany adresów docelowych. Jedno kliknięcie OAuth, żadnych wklejanych sekretów, a mapowanie pól jest konfigurowane osobno dla każdej bazy danych.

Ten artykuł opisuje krok połączenia OAuth wraz z uprawnieniami, strukturę sześciu kolumn i dwukierunkowy przepływ edycji z rozwiązywaniem konfliktów. Jeśli czytałeś wcześniejszy przewodnik po krótkich linkach w Notion, to jest głębsze zagłębienie w temat.

OAuth jednym kliknięciem: co tak naprawdę dzieje się po naciśnięciu Połącz

Stare przepływy oparte na wklejaniu tokenów wymagały wygenerowania wewnętrznego tokenu integracji Notion, wklejenia go, a następnie ręcznego udostępnienia każdej bazy danych integracji. To już historia. Nowy przepływ to trzy kliknięcia: Połącz w Elido, wybierz obszar roboczy i bazy danych na ekranie zgody Notion, gotowe. Wymiana OAuth przebiega zgodnie ze standardem opisanym w dokumentacji uwierzytelniania API Notion, z PKCE przy wymianie kodu autoryzacji.

Przyznawane uprawnienia są celowo wąskie:

• read_content - odczyt właściwości Destination, Tags i Title w wybranych bazach danych.
• insert_content - tworzenie nowych wierszy, gdy poprosisz Elido o wygenerowanie linku ze źródła zewnętrznego (Zap, webhook, CSV).
• update_content - zapisywanie z powrotem właściwości Short URL, Clicks, QR i Last Synced.

Elido nigdy nie prosi o dostęp do odczytu całego obszaru roboczego ani do stron, których nie zaznaczyłeś. Notion egzekwuje to też po stronie serwera: zapytanie do bazy danych poza zakresem uprawnień zwraca 403. Dokumentacja API Notion dla operacji na bazach danych opisuje metody używane przez integrację.

Po zakończeniu zgody przeglądarka trafia na api.elido.app/v1/oauth/notion/callback z kodem autoryzacji. api-core wymienia kod na token dostępu, szyfruje token kluczem KMS obszaru roboczego (zgodnie z ADR-0036) i przechowuje go w integration_credentials. Token w postaci jawnej nigdy nie trafia na dysk ani do logów. Wpis trafia też do dziennika audytu, żeby administrator mógł zobaczyć, kto połączył który obszar roboczy Notion i kiedy.

Przycisk połączenia znajduje się w zakładce Integracje każdego obszaru roboczego - tak samo jak w przypadku każdego innego dostawcy w katalogu integracji. Na stronie integracji z Notion znajdziesz zrzut ekranu ekranu zgody. Uprawnienia można cofnąć z poziomu Ustawień Notion, panelu Połączenia - cofnięcie tam wyzwala webhook, który usuwa token po stronie Elido w ciągu 60 sekund.

Dwa tryby: dołącz lub utwórz

W trybie dołączania wskazujesz Elido na istniejącą bazę danych z właściwością URL. Elido dodaje tylko te kolumny, których potrzebuje, bez zmieniania nazw czegokolwiek. W trybie tworzenia Elido tworzy nową bazę danych "Elido Links" wewnątrz wybranej strony. Większość zespołów wybiera tryb dołączania, bo ich tabela kampanii już istnieje z historią z wielu kwartałów. W obu przypadkach schemat jest identyczny.

Mapowanie pól: sześć kolumn i ich uzasadnienie

Oto układ kolumn używany przez integrację. Nazwy są domyślne i można je zmienić dla każdej bazy danych osobno w Ustawienia, Notion, Mapowanie pól.

Kolumna	Typ w Notion	Kierunek	Uwagi
Short URL	URL	Elido zapisuje	Tylko do odczytu po stronie użytkownika; edycja nie ma żadnego efektu.
Destination	URL	Notion zapisuje	Cel, na który wskazuje krótki link. Edytowalne.
Tags	Wielokrotny wybór	Dwukierunkowy	Tagi są łączone sumą zbiorów w przypadku konfliktu.
Clicks	Liczba	Elido zapisuje	Odczytywane co 5 minut. Tylko do odczytu.
QR	Pliki	Elido zapisuje	PNG kodu QR o rozmiarze 1024px dla krótkiego URL.
Last Synced	Data	Elido zapisuje	Znacznik czasu UTC ostatniej synchronizacji.

Kilka wyborów wymaga wyjaśnienia.

Clicks celowo nie jest w czasie rzeczywistym. Notion nie ma prymitywów strumieniowania, a odpytywanie ich endpointu przy każdym kliknięciu szybko wyczerpałoby limit zapytań. Pięć minut odpowiada świeżości, jakiej potrzebuje większość zespołów operacyjnych. W przypadku danych w czasie rzeczywistym uruchom webhook dla zdarzeń kliknięcia linku i przekaż go do własnego dashboardu. Notion to widok kampanii; webhook to strumień danych.

QR jest właściwością Files, a nie URL. Notion nie renderuje zewnętrznych URL-i obrazków w tabelach, ale wyświetla dołączone pliki jako miniatury. Elido ładuje PNG podczas pierwszej synchronizacji i przeładowuje go tylko wtedy, gdy zmieni się krótki URL. Sprawdź stronę funkcji kodów QR i przewodnik QR GS1.

Tags jest dwukierunkowe z sumą zbiorów. Jedyna kolumna, do której obie strony zapisują. Oznacz wiersz w Notion tagiem "launch-2026", Elido ma "winter-promo" z Zapa - przy następnej synchronizacji oba tagi istnieją po obu stronach. Usunięcia są propagowane. Dziennik audytu rejestruje każdą zmianę.

W kwestii parametrów UTM, przewodnik po szablonach UTM pozwala przypiąć szablon do folderu, żeby każdy link dziedziczył właściwy utm_source. Kolumna Destination pozostaje czysta, a Elido dołącza parametry w momencie rozwiązywania kliknięcia za pomocą reguł inteligentnych linków.

Dwukierunkowy przepływ edycji: kto wygrywa, gdy Notion i Elido się nie zgadzają

To część, na której najbardziej zależy zespołom, bo narzędzia synchronizacji mają historię cichych nadpisań. Oto kontrakt.

Worker wewnątrz api-core odpytuje co pięć minut każdą połączoną bazę danych w poszukiwaniu zmian od ostatniego znaku wodnego last_edited_time. Na zmianę właściwości wczytuje mapowanie pól i ustala własność. Reguły są stałe:

• Notion posiada: Destination, Tags (strona zapisu), Title.
• Elido posiada: Short URL, Clicks, QR, Last Synced.
• Wspólne: Tags (strona odczytu; obie strony widzą scalony zbiór).

Jeśli pole należące do Notion zmieniło się w Notion, Elido aktualizuje stan wewnętrzny i emituje zdarzenie integration.notion.sync. Jeśli pole należące do Elido się zmieniło (inkrementacja licznika kliknięć), Elido zapisuje je z powrotem przy następnej synchronizacji.

Interesujący przypadek to kolizja. Powiedzmy, że zmieniasz Destination w Notion o 14:02:10, a Zap zapisuje nowe Destination do Elido o 14:02:30, w tym samym pięciominutowym oknie. Notion posiada Destination, więc Notion wygrywa. Elido odrzuca zapis Zapa, dodaje komentarz do wiersza ("Konflikt Destination o 14:02:30, zachowano wartość Notion, patrz dziennik audytu") i emituje zdarzenie konfliktu, które można subskrybować przez webhooki. Zap nasłuchuje i decyduje, czy spróbować ponownie, czy wysłać alert.

Nigdzie nie ma cichych nadpisań. Każdy zapis jest rejestrowany. Każdy konflikt dostaje komentarz w wierszu. Dla trwałego zapisu możesz przesłać strumień audytu do swojego hurtowni danych za pomocą przewodnika eksportu ClickHouse lub bezpośrednio korzystać z API GraphQL.

Kiedy zmiana celu NIE powinna być propagowana

Czasem edytujesz Destination jako wersję roboczą. Dwa wzorce pomagają w takiej sytuacji.

Właściwość Status jako strażnik. Dodaj pole Select o nazwie "Sync" z wartościami Draft, Live, Paused. Integracja synchronizuje tylko wiersze, gdzie Sync = Live. Pracuj w Drafcie, przełącz na Live - następny tick go odbierze. Większość zespołów marketingowych w końcu korzysta z tego wzorca.

Wstrzymanie całej bazy danych. Ustawienia, Notion, wstrzymanie per baza danych. Przydatne podczas migracji lub masowych edycji.

Przewodnik konfiguracji: od zera do pierwszego zsynchronizowanego wiersza w 4 minuty

1. Połącz Notion. Ustawienia obszaru roboczego, Integracje, Notion, Połącz. Wybierz obszar roboczy, zaznacz bazy danych, Zezwól.
2. Wybierz bazę danych. Ustawienia, Notion, "Dodaj bazę danych". Rozwijana lista pokazuje wszystkie przyznane bazy danych. Wybierz jedną.
3. Zamapuj pola. Potwierdź Destination, Title i resztę. Brakuje właściwości? Elido zaproponuje ich utworzenie.
4. Wybierz domenę. Wybierz markową domenę dla krótkich linków. Brak własnej domeny? Wybierz domyślną - migracja to jedno kliknięcie później.
5. Zapisz i wypełnij. Elido odczytuje każdy wiersz, generuje krótki link dla tych z Destination ale bez Short URL i zapisuje wyniki. Istniejące Short URL-e zostają bez zmian.

Realny czas to około 4 minut dla 200 wierszy. Większe wypełnienia trafiają na limit trzech żądań na sekundę Notion w bezpłatnych obszarach roboczych. Baza danych z 5000 wierszami wypełnia się w około 30 minut; worker przetwarza partiami i samodzielnie wznawia pracę po nałożeniu limitu.

Kiedy używać tego zamiast Zapiera lub bezpośrednio API

Istnieją trzy ścieżki, które się nie wykluczają.

Natywna integracja to właściwy wybór domyślny, jeśli Notion jest miejscem pracy. OAuth, rozwiązywanie konfliktów, dziennik audytu, mapowanie pól, bez kodu.

Zap sprawdza się przy wieloetapowych przepływach ("gdy wiersz zostanie dodany I pojawi się reakcja Slack, utwórz link"). Przy bezpośrednim mapowaniu wiersza na link natywna integracja jest szybsza i tańsza. Zobacz artykuł o automatyzacji z Zapierem.

REST API sprawdza się, gdy budujesz własny przepływ pracy na bazie Elido. Dla deweloperów tworzących integracje produktowe, kod źródłowy w services/api-core/internal/integrations/notion/ jest na tyle mały, że można go przeczytać w jednym posiedzeniu.

W porównaniu z Bitly lub Rebrandly: żaden z nich nie posiada natywnej integracji z Notion w chwili pisania tego artykułu. Oba wymagają Zapiera lub skryptu własnego. Sprawdź stronę vs Bitly dla porównania i stronę cenową dla planów obejmujących nieograniczoną liczbę baz danych Notion.

Rozwiązywanie problemów: cztery kwestie zgłoszone podczas Bety

Przez osiem tygodni Bety pojawiły się cztery kategorie problemów. Wszystkie są teraz obsłużone w kodzie, ale warto wiedzieć, na co zwrócić uwagę.

"Nie znaleziono bazy danych" po zmianie nazwy obszaru roboczego. Jeśli administrator Notion zmieni nazwę obszaru roboczego, ID obszaru roboczego pozostaje stabilne, ale buforowane metadane stają się nieaktualne po naszej stronie na do godziny. Obejście: naciśnij "Wymuś ponowną synchronizację" w Ustawienia, Notion. TTL cache w produkcji wynosi 15 minut, więc to głównie artefakt Bety.

Limit zapytań przy dużym wypełnieniu. Limit Notion per integracja to trzy żądania na sekundę. Baza danych z 5000 wierszami mocno go uderza podczas pierwszego wypełnienia. Worker stosuje wykładniczy backoff (250ms, 500ms, 1s, 2s, maksymalnie 8s) i wznawia pracę. W dzienniku aktywności pojawi się "Throttled by Notion, resuming"; to normalne.

Niezgodność typu właściwości. Najczęstszy błąd w Becie. Użytkownik wybrał kolumnę Notion typu "Tekst" zamiast "URL" dla Destination. Walidator mapowania pól teraz to wykrywa przy zapisie i odmawia kontynuowania. Jeśli widzisz "Destination musi być właściwością URL", najpierw zmień typ kolumny w Notion.

Użytkownik wielu obszarów roboczych ze wspólnymi bazami danych. Jeśli ta sama osoba jest członkiem dwóch obszarów roboczych Notion i oba chcą połączyć się z Elido, każdy obszar roboczy potrzebuje własnego uprawnienia OAuth. Token jest per obszar roboczy, nie per użytkownik. Przepływ połączenia obsługuje to poprawnie; po prostu kliknij Połącz dwa razy.

W przypadku czegokolwiek spoza tej listy strona kontaktowa trafia bezpośrednio do zespołu integracji. Problemy są tam dostrzegane szybciej niż w ogólnym wsparciu.

Co będzie dalej

Dwa elementy w harmonogramie. Przepis "formularz Notion do krótkiego linku", żeby wypełnienie formularza tworzyło śledzony link. Oraz dwukierunkowa synchronizacja właściwości Workspace, żeby link mógł podążać za wierszem przenoszonympomiędzy bazami danych. Oba planowane na Q3; zaznaczymy je w changelogu.

Do mierzenia efektów, przewodnik po analityce krótkich linków wyjaśnia, które metryki naprawdę mają znaczenie i jak skonfigurować wiersze dashboardu Notion, żeby odpowiadały na właściwe pytania.