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

**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/).

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

Her sayfa, üst sayfasının adını taşıyan bir klasöre yerleştirilmiş, başlığı, Notion id'si, URL'si ve
`last_edited_time`'ı frontmatter'da olan tek bir Markdown dosyası olur:

```
notion/Engineering/Runbooks/Rotating the signing key.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: 5000 sayfa 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 satırından **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 (ADR-0049). Doğrulandıktan sonra kendi push webhook'unu sunar —
ama her boşluğu kapatmaz: paylaşımı kaldırılan bir sayfa yalnızca tam bir çalışmada fark edilir.
Doğrulanana kadar, ya da o boşluk için, senkronizasyon bir çalışma gerçekleştiğinde olur: kaynakta
**Sync**'e basın, projede **Re-index**'e basın, ya da bir zamanlamayla `POST /api/projects/:id/reindex`'i
çağırın — bkz. [Admin API](/tr/docs/admin-api/).

## 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 connection**, `unauthorized` ile başarısız olur | 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.