# Notion

> API üzerinden bir Notion çalışma alanını indekslemek — bir integration oluşturmak, sayfaları paylaşmak, neyin içeri alındığı, ve dışa aktarım zip alternatifi.

- Güncelleme: 2026-10-30
- Kaynak: https://contextator.com/tr/docs/notion/
- Dil: tr-TR
- Yazar: Muhammet Şafak

---
Bir Notion çalışma alanını doğrudan API üzerinden indeksleyin: dahili bir integration ile paylaşılan
her sayfa Markdown'a dönüştürülür ve senkronize tutulur. Değişen sayfalar yeniden render edilir;
paylaşımı durdurulan sayfalar kaldırılır.

Bir integration oluşturmak istemiyorsanız, bir Notion **Export → Markdown & CSV** zip'ini de
yükleyebilirsiniz — aşağıda [dışa aktarım yolu](#dışa-aktarım-zipi-alternatifi)ne bakın.

## 1. Bir integration oluşturun

1. **notion.so/profile/integrations**'a gidin ve dahili bir integration oluşturun.
2. Token'ını kopyalayın (`ntn_` ya da `secret_` ile başlar).

## 2. Sayfaları onunla paylaşın

Notion'da, indekslenmesini istediğiniz her sayfayı ya da veritabanını açın ve onu integration ile
paylaşın (**… → Connections → integration'ınız**). Bir üst sayfayı paylaşmak, çocuklarını da paylaşır.

Bunu yapana kadar Contextator'a hiçbir şey görünmez — yepyeni bir integration hiçbir şey görmez.

## 3. Kaynağı ekleyin

**Add source → Notion**

| Alan | Notlar |
|-------|-------|
| **Name** | Bağlama öneki. Değiştirilemez |
| **Integration token** | `SECRET_KEY` ile şifrelenmiş saklanır, bir daha gösterilmez |
| **Root pages or databases** | Opsiyonel. Sayfa ya da veritabanı id'leri — ya da yalnızca URL'leri, id ayıklanır. Satır başına bir tane. İntegration ile paylaşılan her şeyi almak için boş bırakın |

Kaynak kaydedildikten sonra satırındaki **Test**'e (ya da **Edit** diyaloğundaki **Test connection**'a)
basın: integration'ın kendi kullanıcısını okur ve adıyla yanıt verir (`Connected as Docs Importer`),
böylece herhangi bir indeksleme başlamadan önce yanlış bir token belli olur.

> Bir kaynak bir token saklayabilmeden önce `SECRET_KEY` ayarlanmış olmalıdır (32+ karakter). Bkz.
> [Yapılandırma](/tr/docs/configuration/).

## Connect with Notion (OAuth)

0.6.0'dan beri bir kaynağı yetkilendirmenin ikinci bir yolu var: **Connect with Notion**. Bir integration oluşturup
token'ını yapıştırmak yerine sayfaları Notion'ın kendi sayfa seçicisinde seçersiniz. **Kendi kaydettiğiniz bir public
connection** gerekir (`notion.so/profile/integrations` altında, dahili değil *public* bir connection) — Contextator'a ait
bir connection yoktur — ve instance'ta üç değişken: `NOTION_OAUTH_CLIENT_ID`, `NOTION_OAUTH_CLIENT_SECRET` ve bir
yönlendirme URI'si (`NOTION_OAUTH_REDIRECT_URI` ya da `PUBLIC_BASE_URL`'den türetilir; bkz.
[Yapılandırma](/tr/docs/configuration/#connect-with-notion-oauth)). Hiçbiri ayarlı değilse hiçbir şey değişmez: dashboard
yalnızca token alanını gösterir.

- Yönlendirme URI'si bu instance'ı adlandırmalıdır: `https://<alan-adınız>/api/sources/notion/oauth/callback` ya da
  kendi makinenizdeki bir instance için `http://localhost:<port>/api/sources/notion/oauth/callback`. IP adresi olmaz.
- Dashboard'u aynı host'ta açın: oturum çerezleri bir host adına aittir; yönlendirme URI'si `localhost` derken dashboard
  `127.0.0.1`'de açıksa tarayıcı, oturum açmadığınız bir host'a geri gönderilir.
- Yalnızca kimlik ve gizli anahtardan biri ayarlıysa, ne yönlendirme URI'si ne de `PUBLIC_BASE_URL` ayarlıysa ya da
  `SECRET_KEY` eksikse başlangıç reddedilir.
- Yalnızca oturum açmış bir proje editor'ü dashboard'dan başlatabilir; bir API token'ı ya da `ADMIN_TOKEN` başlatamaz,
  çünkü bu bir tarayıcı gidiş dönüşüdür.
- Erişim ve yenileme token'ı `SECRET_KEY` ile şifrelenmiş saklanır. Notion erişim token'ını reddedince kaynak onları
  yeniler; iptal edilmiş bir bağlantı çalışmayı **Reconnect** isteyerek bitirir, bu da kaynağı adını ve ayarlarını
  değiştirmeden yeniden yetkilendirir.
- Bir OAuth kaynağının **webhook'u yoktur**: bir public connection'ın webhook'u tek bir kaynağa değil connection'a
  aittir, bu yüzden güncel tutmayı zamanlama sağlar. Proje dışa aktarımı token'ları bırakır, bu yüzden içe aktarılmış bir
  OAuth kaynağı Reconnect ister. `{` ile başlayan bir Notion `secret`'ı API üzerinden `400 invalid_request` ile
  reddedilir: bu bir OAuth bağlantısının biçimidir ve onu yalnızca dashboard akışı oluşturur.

## Neyin içeri alındığı

Her sayfa, üst sayfa başına bir klasöre yerleştirilmiş, başlığı, Notion id'si, URL'si ve
`last_edited_time`'ı frontmatter'da olan tek bir Markdown dosyası olur. Dosya ve klasör adları, başlığın
slug hali artı Notion id'sinin ilk sekiz karakteridir; bir veritabanında duran sayfa ise
`database--<id'nin ilk sekiz karakteri>` klasöründe yer alır:

```
notion/engineering--1a2b3c4d/runbooks--5e6f7a8b/rotating-the-signing-key--9c0d1e2f.md
```

Render edilen blok türleri: paragraflar, üç başlık seviyesinin tümü (katlanabilir bir başlığın altına
katlanmış bloklar dahil), iç içe geçmeleriyle madde işaretli, numaralı ve yapılacaklar listeleri,
alıntılar, callout'lar, kod blokları, tablolar, ayraçlar, denklemler, yer imleri, görseller ve dosya
bağlantıları. Bilinmeyen blok türleri, sayfayı başarısız kılmak yerine atlanır, böylece yeni bir Notion
özelliği bir içe aktarımı asla bozmaz.

Kaynak başına sınırlar: varsayılan olarak 5000 sayfa (`NOTION_MAX_PAGES`, 1 ile 100 000 arası, instance başına ayarlanır — bkz. [Yapılandırma](/tr/docs/configuration/)) ve 25 seviye iç içe geçme. İstekler saniyede yaklaşık üçe
kısıtlanır, ki bu Notion'ın belgelenmiş hız sınırıdır — büyük bir çalışma alanı ilk senkronizasyonda
biraz zaman alır ve sonrasında hızlıdır.

## Senkronize tutmak

Her indeksleme çalışmasının başında, Contextator çalışma alanını yeniden çeker ve **yalnızca
`last_edited_time`'ı değişen sayfaları yeniden render eder**. Artık paylaşılmayan ya da silinmiş bir
sayfanın dosyası kaldırılır.

Notion'ın kendi push webhook'u bir git sağlayıcısının tersi yönde çalışır: URL yine de bir Notion
subscription'ına yapıştırılır, başka yerdeki [Push Webhook'ları](/tr/docs/push-webhooks/) ile aynı
örüntü, ama sır ters yönde akar. Önce kaynağın **Edit** diyaloğundaki **Open verification window** ile
**15 dakikalık bir doğrulama penceresi** açın; Notion'ın o URL'e ilk gönderimi token'ı taşır, o da
doğrulamayı bitirmek için Notion'ın *Webhooks* sekmesine geri yapıştırılır. Doğrulandıktan
sonra bir sayfa düzenlendiğinde, silindiğinde ya da taşındığında bir senkronizasyon başlatır — birkaç
saniye içinde değil, çünkü bir gönderim yığını tek bir çalışmaya indirgenir ve çalışmalar arasında en az
`WEBHOOK_MIN_INTERVAL_MINUTES` (varsayılan olarak 5) vardır — ama her boşluğu kapatmaz: Notion, bir
sayfanın paylaşımı kaldırıldığında hiçbir olay göndermez; yani paylaşımın kaldırılmasının kendine ait bir olayı yoktur.
Sayfayı bir sonraki tam senkronizasyon düşürür; onu başka bir sayfa için gelen bir webhook'un, **Sync**'in ya da
**Sync every** aralığının başlatmış olması fark etmez. Aralığın kontrolü paylaşım kaldırmayı tek başına göremez:
yalnızca çalışma alanındaki en yeni düzenleme zamanına bakar, yani düzenlemeleri fark eder, paylaşım
kaldırmalarını değil.

Başka hiçbir şey senkronizasyon başlatmazsa garantiyi zamanlanmış kontrol verir ve bu sınırlıdır. Zamanlanmış bir kaynak, son başarılı senkronizasyonu `SYNC_MAX_SKIP_HOURS` değerinden
(varsayılan 24 saat) eskiyse, kontrol ne derse desin eksiksiz senkronize edilir. Sayfa o çekimde yoktur, bu yüzden
dosyası kaldırılır: paylaşımı kaldırılan bir sayfa, bu süre artı kaynağın kendi **Sync every** aralığı, en fazla bir
dakika ve senkronizasyonun kendi süresi ya da süren bir çalışma kadar bir süre içinde indeksten ve arama sonuçlarından çıkar. Değişkeni `0` yaparsanız sınır kapanır; sayfa, çalışma alanında
herhangi bir yerdeki bir sonraki düzenleme bir çalışmayı tetikleyene kadar kalır. *Never* olarak ayarlanmış bir kaynak
zamanlanmış değildir, bu yüzden sınır ona ulaşmaz.

Paylaşımı kaldırılan bir sayfayı hemen düşürmek için kaynakta **Sync**'e basın, projede **Re-index**'e basın ya da
`POST /api/projects/:id/reindex`'i çağırın — sayfa o çekimde yoktur, bu yüzden dosyası kaldırılır
(bkz. [Admin API](/tr/docs/admin-api/)). Webhook doğrulanana kadar düzenlemeleri yakalayan **Sync every**'dir.

## Bir şeyler yanlış olduğunda

Token reddedilirse, ya da yapılandırılan root sayfalarının **hiçbiri** okunamıyorsa, senkronizasyon
**başarısız olur** ve bunu bildirir. Boş bir çalışma alanı bildirmez — ki bu aksi halde daha önce içeri
alınan her sayfayı silerdi. Projenin diğer kaynakları yine de indekslenir, ve proje şunu bildirir:

```
2/3 sources synced; notion: No configured Notion root could be read — 1a2b3c4d… (object_not_found)
```

*Bazı* root'lar okunabiliyor ve diğerleri okunamıyorsa, okunabilenler içeri alınır ve başarısızlıklar
bildirilir.

| Belirti | Neden ve çözüm |
|---------|---------------|
| **Test**, Notion'ın geçersiz bir API token'ı hakkındaki kendi mesajıyla yanıt verir (hata kodu `unauthorized`) | Yanlış ya da iptal edilmiş token. Yeni bir tane oluşturun ve yapıştırın |
| Kaynak hiçbir şey içeri almaz | Henüz integration ile hiçbir şey paylaşılmamış. Sayfaları paylaşın (**… → Connections**) |
| Belirli bir sayfa eksik | O — ya da üst sayfası — integration ile paylaşılmamış, ya da 25 seviyeden daha derinde |
| Bir root id için `object_not_found` | Id yanlış, ya da o sayfa integration ile paylaşılmamış |
| Bir veritabanının satırları eksik | Yalnızca içindeki sayfaları değil, veritabanının kendisini paylaşın |

## Dışa aktarım zip'i alternatifi

Bir integration oluşturamıyorsanız, Notion'dan dışa aktarın (**… → Export → Markdown & CSV**) ve
zip'i içerik türü **Notion export** olan bir **Upload files** kaynağı olarak yükleyin. Notion'ın her
dosya ve klasör adına eklediği 32 karakterlik sayfa id'si, yollardan ve onlara işaret eden
bağlantılardan ayıklanır, ve dışa aktarımın içindeki iç içe geçmiş `Part-1.zip` otomatik olarak açılır.

Ödünleşim: hiçbir şey kendiliğinden senkronize olmaz — içerik değiştiğinde yeniden dışa aktarır ve
yeniden yüklersiniz.
