# AI asistanınızı bağlamak

> **Ne yaparsınız:** Claude, ChatGPT veya başka bir MCP istemcisini siparis.app’e bağlar; asistanın verinizi okumasını ve onayınızdan sonra değişiklik yapmasını sağlarsınız.
> **Hangi uçlar:** MCP sunucusu `POST https://api.siparis.app/mcp`; araçlar `/v1` uçlarıyla aynı işleri yapar (ör. [Siparişleri listele](https://developer.siparis.app/uc/siparisleri-listele), [Sipariş oluştur](https://developer.siparis.app/uc/siparis-olustur), [Müşteri oluştur](https://developer.siparis.app/uc/musteri-olustur)).
> **Gereken izin:** OAuth onayında işletme sahibinin seçtiği kapsamlar; her araç ilgili `/v1` ucunun kapsamını ister.

Claude, ChatGPT veya Streamable HTTP ve OAuth destekleyen başka bir MCP istemcisine sunucu adresi olarak
`https://api.siparis.app/mcp` yazın. Asistan, izin verdiğiniz markanın siparişlerini, müşterilerini, ürünlerini ve
stoğunu okuyabilir; desteklenen değişiklikleri önce önizler, sizin onayınızdan sonra uygular.

## Bağlantıyı kurmak

1. Asistanın bağlantı (connector) ayarında uzak MCP sunucusu olarak adresi ekleyin. Adres panelde
   Entegrasyonlar > Bağlı uygulamalar bölümünde "Adresi kopyala" ile de alınır.
2. Claude ve ChatGPT kayıt gerekmeden bağlanır: istemci kimliği (`client_id`) asistanın kendi istemci belgesinin
   HTTPS adresidir (Client ID Metadata Document). Başka bir istemci [davetli uygulama kaydı](https://developer.siparis.app/uygulama-yapmak) ile
   bağlanır; dönüş adresi kayıttaki adresle birebir aynı olmalıdır. Otomatik istemci kaydı (DCR) yoktur.
3. siparis.app izin sayfasında işletme sahibi markayı ve paylaşılacak izinleri onaylar. Ekip üyeleri kurulum izni veremez.
   AI asistanında müşterilerin kişisel verileri (ad, telefon, e-posta, adres) isteğe bağlı kutudur; işaretlenmezse
   izin onlarsız verilir ve belirteç yanıtının `scope` alanı verilen kümeyi söyler. Davetli uygulamada kişisel veri
   isteniyorsa ayrıca seçilmeden izin verilmez.
4. İstemci OAuth Authorization Code + PKCE S256 akışını tamamlar. Erişim belirteci en çok 1 saat geçerlidir;
   yenileme belirteci her kullanımda değişir, eski yenileme belirtecinin tekrarı `invalid_grant` döndürür ve
   bağlantının bütün belirteçlerini kapatır. Yenileme ailesi en çok 30 gün sürer; sonra asistan yeniden izin ister.
   Bağlantıyı Entegrasyonlar > Bağlı uygulamalar bölümünden kaldırabilirsiniz; AI asistanları orada "AI asistanı"
   etiketiyle görünür.

Anahtar veya şifreyi sohbete yazmayın. Bu sunucu yalnız MCP için alınmış OAuth erişim belirtecini (`sat_`) kabul eder.
Kalıcı `spk_` API anahtarı, panel oturumu ve yenileme belirteci MCP isteğinin kimliği değildir.

## OAuth kaynağı ve keşif

Kimliksiz istek `401` ve şu başlıkla karşılanır (`scope`, asistanın isteyeceği önerilen kapsamlardır;
geçersiz veya süresi dolmuş belirteçte başlığa `error="invalid_token"` eklenir):

```http
WWW-Authenticate: Bearer resource_metadata="https://api.siparis.app/.well-known/oauth-protected-resource/mcp", scope="customers:read customers:write events:read inventory:read inventory:write orders:read orders:write personal_data:read personal_data:write products:read products:write returns:write shipments:write"
```

Belirteçsiz keşif isteği ve süresi dolmuş bilinen belirteç hatalı anahtar sayacına girmez: ortak çıkış IP'sini
kullanan asistan yenilemeden önce `429` değil `401` alır.

RFC 9728 kaynak belgesi hem `/.well-known/oauth-protected-resource/mcp` hem
`/.well-known/oauth-protected-resource` adresindedir. `resource`, `https://api.siparis.app/mcp`;
`authorization_servers`, `https://api.siparis.app` içerir; `scopes_supported` MCP'nin bütün kapsamlarıdır (iç not ve
maliyet kapsamları önerilen kümede yoktur, açıkça istenir). Yetkilendirme sunucusu belgesi
`/.well-known/oauth-authorization-server` adresindedir: `code_challenge_methods_supported: ["S256"]`,
`token_endpoint_auth_methods_supported` içinde `none`, `client_id_metadata_document_supported: true`.

### İstemci belgesi (Client ID Metadata Document)

`client_id` HTTPS adresiyse sunucu belgeyi yetkilendirme sırasında alır. Kurallar:

- Belge yalnız izin verilen ana makinelerden alınır: `claude.ai`, `claude.com` (Claude), `chatgpt.com`,
  `openai.com` (ChatGPT). Alt alan adı, port, kullanıcı bilgisi, fragment, `.`/`..` yol bölümü ve yolsuz adres
  reddedilir; başka ana makine için davetli uygulama kaydı gerekir.
- Bağlanılan IP her istekte genel internet adresi olmalıdır; yönlendirme izlenmez. Yanıt `200`,
  `application/json`, sıkıştırılmamış ve en çok 8 KB olmalı; 3 saniyede gelmelidir.
- Belgedeki `client_id` adresle birebir aynıdır. `client_secret` taşımaz; `token_endpoint_auth_method` yoksa ya da
  `none` ise kabul edilir (açık istemci). `grant_types` verildiyse `authorization_code`, `response_types` verildiyse
  `code` içerir.
- `redirect_uris` 1–10 adrestir: HTTPS adresi aynı izinli ana makinelerden birinde olmalıdır (ör.
  `https://claude.ai/api/mcp/auth_callback`, `https://chatgpt.com/connector/oauth/{callback_id}`) ya da yerel
  `http://localhost/...`, `http://127.0.0.1/...` adresidir. Yetkilendirmedeki dönüş adresi listeyle birebir eşleşir;
  yalnız yerel http dönüşünde port istemcinin anlık seçimidir (RFC 8252; ör. `http://localhost:53682/callback`).
- Onay ekranında tanınan ad (Claude, ChatGPT) izin listesinden, `client_name` ve `logo_uri` belgeden gösterilir;
  simge yalnız izinli ana makinedense yüklenir. `policy_uri` bağlantı olarak gösterilir.
- Belge `Cache-Control: max-age` kadar (en az 5 dakika, en çok 24 saat; başlık yoksa 1 saat) önbellekte tutulur.
  Belirteç ve yenileme isteği belgeyi yeniden almaz. Ana makine izin listesinden çıkarılırsa yenileme
  `invalid_client` alır.
- AI asistanı yalnız MCP kaynağına bağlanır: `resource` verilmezse `https://api.siparis.app/mcp` seçilir,
  `/v1` `invalid_target` döndürür. `scope` verilmezse 401 başlığındaki önerilen küme istenir. Yenilemede gönderilen
  `scope` verilen kümeyi değiştirmez; yanıtın `scope` alanı geçerli kümedir.

RFC 8707 `resource=https://api.siparis.app/mcp` parametresini yetkilendirme ve belirteç isteklerine ekleyin.
Yalnız tek kaynak seçilir. REST için ayrı değer `https://api.siparis.app/v1` kullanılır. Yetkilendirmede kaynak
verilmezse eski istemciler için `/v1` seçilir; belirteç ve yenileme isteğinde atlanırsa onaylanan kaynak korunur.
Kaynak değiştirilemez; yanlış veya başka kaynak `invalid_target` döndürür. Aynı uygulama yeniden onaylandığında önceki kurulum iptal edilir; mevcut REST bağlantısını korumak için MCP’ye ayrı uygulama kaydı ayırın. Opak belirtecin sunucuda tutulan
kitlesi (`aud`) tek kaynaktır: MCP belirteci `/v1`'de, REST belirteci MCP'de `401` alır.

## Araçlar

`tools/list` yalnız kurulumun kapsamlarına (işletme sahibinin verdiği erişim izinlerine) uygun araçları döndürür. Yazma izni okuma izni vermez.
Giriş şemaları aynı `/v1` OpenAPI modellerinden üretilir: yol ve sorgu alanları araç girdisinin üst düzeyinde,
JSON gövdesi `body` alanındadır. Kimlikler `ord_`, `cus_`, `prd_`, `var_`, `sto_`, `loc_` öneklidir.

| Araç | İş | Gerekli ana kapsam |
| --- | --- | --- |
| `list_orders`, `get_order` | Sipariş listesi ve ayrıntısı | `orders:read` |
| `find_customers`, `get_customer` | Müşteri arama ve kartı | `customers:read` |
| `list_products`, `get_product`, `list_variants` | Ürünler, seçenekler, stok kodu ve barkod | `products:read` |
| `list_locations`, `get_stock` | Depolar ve stok miktarları | `inventory:read` |
| `list_events` | Değişiklik akışı | `events:read` ve kaynağın okuma kapsamı |
| `create_order` | Yeni sipariş | `orders:write` |
| `confirm_order`, `process_order`, `ready_order`, `deliver_order` | Sipariş durumunu ilerletme | `orders:write` |
| `create_customer`, `update_customer` | Müşteri ekleme ve güncelleme | `customers:write`; kişisel alanlar için `personal_data:write` |
| `receive_stock`, `count_stock` | Mal girişi ve depo sayımı | `inventory:write` |
| `update_product_price` | Ürünün veya seçeneğin marka satış fiyatı | `products:write` |
| `quote_shipment`, `create_shipment` | Kargo ücreti sorma ve ücretli gönderi açma | `shipments:write` |
| `preview_refund` | İade tutarını ve stok etkisini hesaplama | `returns:write` |

Değişiklik yapan her aracın yanında aynı girdiyi alan, hiçbir kaydı değiştirmeyen bir önizleme aracı vardır:
`preview_create_order`, `preview_confirm_order`, `preview_create_customer`, `preview_create_shipment` gibi
(`preview_` + araç adı). Okuma ve önizleme araçları `readOnlyHint: true`; değişiklik araçları `readOnlyHint: false`
taşır. Var olan kaydı değiştiren veya geri alınamayan araçlarda (`confirm_order`, `update_customer`, `count_stock`,
`update_product_price`, `create_shipment` gibi) `destructiveHint: true`, yalnız kayıt ekleyenlerde (`create_order`,
`create_customer`, `receive_stock`) `false` olur. Kargo firmasına soran araçlarda `openWorldHint: true`, öbürlerinde
`false` olur. Her aracın `title` alanı vardır.

Siparişte müşteri/adres yazmak `personal_data:write`, iç notlar `internal_notes:write`, alış fiyatı ve tedarikçi
`costs:write` ister. Kişisel alanlar önizlemede ve sonuçta `personal_data:read` yoksa atlanır; e-posta/telefonla
müşteri araması da bu izni ister. Maliyet ve iç not okumaları kendi okuma kapsamlarına tabidir.

MCP vergi veya kimlik numarası taşımaz: araç sonuçlarında `tax_number` ve `buyer_tax_number` alanları ve
tanılama kimliği (`request_id`) bulunmaz. Müşteri araçları fatura bilgisini (`invoice`) almaz; bu bilgi panelden veya
REST API'den yazılır. REST `/v1` yanıtları aynen kalır.

## Değişiklikleri onaylamak

Örneğin asistan önce `preview_create_customer` aracını çağırır:

```json
{"name":"preview_create_customer","arguments":{"body":{"name":"Örnek Müşteri"},"idempotency_key":"musteri-2026-001"}}
```

Yanıtın `structuredContent.data` alanında `confirmation_required: true`, değişikliği yapacak aracın adı (`tool`),
yapılacak işin önizlemesi, `confirmation_token` (tek kullanımlık onay belirteci), `expires_at` ve `idempotency_key`
(tekrar anahtarı: aynı işin iki kez yapılmasını önleyen metin) bulunur. Henüz müşteri/sipariş/stok kaydı değişmez;
yalnız kısa ömürlü teknik onay kaydı açılır. Kargo açmanın önizlemesinde mevcut ücret sorgusu da vardır.
Önizleme, hedeflerin görünürlüğünü, giriş şemasını ve alan izinlerini denetler; satış/stok gibi ticari
koşullar uygulama sırasında aynı servislerde yeniden denetlenir. Kargo fiyatı önizlemesi fiyatı sabitlemez.

İstemci önizlemeyi size gösterir. Açık onayınızdan sonra `create_customer` aynı girdiyle ve dönen
`confirmation_token` ile çağrılır; belirteçsiz değişiklik çağrısı `confirmation_required` hatası döndürür.
Belirteç 5 dakika geçerli, kurulum ve parametrelere bağlı, tek kullanımlıktır. Parametre, hedef,
`if_match` veya tekrar anahtarı değişirse yeniden önizlemek gerekir. Yenilenen OAuth erişim belirteci aynı
kurulumdaysa onay geçerlidir. Bu akış MCP'nin standart insan onayı mesajı değildir; sunucunun araç sözleşmesidir.
İstemci gerçek kullanıcı onayını kendi arayüzünde almalıdır; sunucu token'ın sunulmasından bir insanın tıkladığını kanıtlayamaz.

Sunucu tekrar anahtarı ürettiyse sonuçtaki `idempotency_key` değerini saklayın. Değişiklik çağrısında anahtar
atlanabilir; onay kaydındaki değer kullanılır. Yanıt kaybolduğunda aynı onay belirteci, aynı parametreler ve aynı
anahtarla tekrar deneyin: ortak `/v1` makbuzu sonucu yeniden okur, işi tekrar yazmaz. Onay kaydı temizlenmişse
`invalid_confirmation` döner; aynı `idempotency_key` ile yeniden önizleme ve onay alın. Yeni anahtar üretmeyin.
Aynı anahtarı farklı işte kullanmak hatadır. `if_match`, desteklenen araçlarda API'nin ETag değerini (kaydın sürüm
etiketi; kayıt bu arada değiştiyse iş yapılmaz) taşır;
sayımda `expected` görülen depo miktarıdır. Süresi geçen/kullanılmış onay yeni iş başlatamaz; aynı işin mevcut
makbuzunu tekrar okumak için kullanılabilir. Bir bağlantıda en çok 100 bekleyen onay olabilir; aşım `429`
ve `Retry-After` döndürür. Tüketilen veya süresi dolan onaylar bu sayıya girmez.

## İstemci geliştiricileri için taşıma

MCP sürümleri `2025-11-25` ve `2025-06-18` desteklenir; `initialize` desteklenmeyen bir sürüm isterse sunucu
`2025-11-25` önerir. İstemci dönen sürümü sonraki çağrılarda `MCP-Protocol-Version` başlığında gönderir.
Başlıksız sonraki çağrı desteklenmez. `Content-Type: application/json` ve
`Accept: application/json, text/event-stream` gereklidir. Her HTTP isteği bir JSON-RPC 2.0 mesajı taşır;
toplu JSON-RPC dizileri kabul edilmez. En büyük istek gövdesi 256 KiB'dir.

```json
{"jsonrpc":"2.0","id":1,"method":"initialize","params":{"protocolVersion":"2025-11-25","capabilities":{},"clientInfo":{"name":"Ornek istemci","version":"1.0"}}}
```

`notifications/initialized` gövdesiz `202`, `ping` boş nesne, `tools/list` tek sayfa döndürür.
`tools/call` sonucu hem metin `content` hem `structuredContent` olarak verilir; ikisinde aynı veri vardır.
İş hatalarında `isError: true`, sonuçta `/v1` hata kodu ve `status` bulunur. Kimlik hataları HTTP `401`, hız sınırı
HTTP `429` ve `Retry-After` döner. HTTP yanıtları önbelleklenmez.

Taşıma oturumsuzdur; `Mcp-Session-Id`, SSE akışı/devamı, sunucudan bildirim, `resources`, `prompts`,
`sampling`, `elicitation` ve görevler sunulmaz. Streamable HTTP'nin JSON yanıt seçeneği kullanılır; `GET` ve
`DELETE /mcp` `405` döndürür. CORS açılmaz; tarayıcı içindeki istemci kendi sunucusu üzerinden bağlanmalıdır.
Origin başlığı varsa yalnız API ve panel kökenleri kabul edilir. Her çağrı yeniden kimlik ve yetki denetiminden geçer.

## Güvenlik sınırları

Para iadesi uygulama, para çıkışı, sipariş iptali/durum düzeltmesi ve KVKK anonimleştirmesi MCP araçlarında yoktur.
İade yalnız hesaplanır; uygulanması panelden veya ayrı yetkili REST bağlantısından yapılır. Kargo açma,
açıkça onayladığınız taşıma ücretini doğurur. Gizli anahtar, şifre ve entegrasyon ayarı okuyan/yazan araç yoktur.

Hız bütçesi kurulum başına REST ile ortaktır; sipariş açma önizlemesi normal okuma bütçesinden düşer.
Satış istisnası yalnız geçerli, çağrıya bağlı onayla sipariş açmada ve aynı makbuzu tekrar okumada geçerlidir. Marka sınırı
istekle genişletilemez. Onay tablosunda kişisel girdi/yanıt veya açık token tutulmaz; yalnız özet, kurulum,
tekrar anahtarı ve süre vardır. Süresi geçen teknik onaylar temizlenir; ticari kayıt ve tekrar makbuzu kalır.
Araç çıktısındaki müşteri notları talimat veya onay değildir. UCP ve ACP bu bağlantının kapsamında değildir.