Entegrasyonlar

Yüklenebilecek katalog şablonlarını ve sitede kurulu paketleri listeleyin.

GET /api/v1/{locale}/{websiteId}/integrations?resource=packages

Bir katalog şablonunu yükleyin. templateId veya slug verin. Yanıt packageId içerir. Gizli anahtar değerleri kopyalanmaz.

POST /api/v1/{locale}/{websiteId}/integrations

{
  "resource": "packages",
  "action": "install",
  "slug": "iyzico-sandbox"
}

Kurulu bir paketi, değişkenleri dahil okuyun. Her değişken {id, name, value} şeklindedir. id değerini siz verirsiniz. baseUrl bir değişkendir. Sandbox ile canlı ayrımı bu değer ve iki gizli anahtar adıdır; ayrı bir ortam sütunu yoktur.

GET /api/v1/{locale}/{websiteId}/integrations?resource=packages&id={packageId}

action create ile kendi paketinizi oluşturun veya action update ve packageId ile bir paketi değiştirin. variables gönderildiğinde liste değişir. Gönderilmeyen güncelleme alanları kalır. Boş ad, path name ile invalid_input döner. Güncelleme aynı uç noktaya action update, packageId ve input.variables ile gider.

POST /api/v1/{locale}/{websiteId}/integrations

{
  "resource": "packages",
  "action": "create",
  "input": {
    "name": "Checkout",
    "variables": [
      {
        "id": "11111111-1111-7111-8111-111111111111",
        "name": "baseUrl",
        "value": "https://sandbox-api.iyzipay.com"
      }
    ]
  }
}

MCP: get_integration_packages (no packageId lists them), install_integration_package, save_integration_package, get_integration_secrets, save_integration_secret, rotate_integration_secret, delete_integration_secret, get_integration_queries (no queryId lists them), save_integration_query, get_integration_webhooks (no webhookId lists them), save_integration_webhook, delete_integration_webhook.

Gizli anahtarlar

resource secrets ile gizli anahtar oluşturun, döndürün veya silin. Sorgu veya webhook oluştururken eksik ya da uydurma packageId, path packageId ile invalid_input döner. Sorgu veya webhook kaydı resource queries veya webhooks, action save ve oluştururken packageId ister. secretSlotRefs buradan dönen gizli anahtar id’sini saklar, adını değil.

Sorgular

Sorgu tanımında request.delivery queue (varsayılan) veya await olur. queue, çağıran döndükten sonra çalışır. await, veri isteği veya yaşam döngüsü yanıtından önce biter; böylece bir yanıt işleyicisi payment_page_url gibi bir alanı önce kayda yazabilir.

request.bodyAst sıralı bir JSON ağacıdır. Düğüm türleri null, boolean, number, string, binding, each, object ve array’dir. Metin değeri {"kind":"string","value":"tr"} şeklindedir. {"kind":"literal"} ve {"kind":"var"} gövde düğümü değildir. Bir bağlamanın tamamı {"kind":"binding","id":"<bağlama uuid>"} olur. object düğümü entries kullanır: [{"key":"locale","value":<düğüm>}].

bindings, {id, label, kind, ref} dizisidir. kind değerleri package_var, field, var, secret_slot, relation_one veya each’tir. package_var ref’i paket değişkeninin id’sidir. var ref’i eşleme değişkeninin adıdır. Aynı id’yi urlTemplate içinde {{binding:<id>}} olarak kullanın.

secretSlotRefs bir kimlik doğrulama yuvası adını create_integration_secret ile alınan gizli anahtar id’sine bağlar. Örnek: {"apiKey":"<gizli anahtar uuid>"}.

mapping.steps içindeki set_var, kind literal, field, system, var ve webhook’un yeridir. Örnek: {"type":"set_var","name":"locale","source":{"kind":"literal","value":"tr"}}. field ve var kaynakları path kullanır.

responseHandlers çağrı sonucunu kayda yazar. Her işleyicide id, name, enabled, constraints ve actions vardır. modify_field bir yanıt yolunu kayıt alanına kopyalar: {"type":"modify_field","fieldKey":"payment_page_url","source":{"kind":"path","path":"response.body.paymentPageUrl"}}. Ödeme durumu response.body.paymentStatus kullanır. paymentStatus boş ve response.body.status failure ise ikinci bir işleyici literal FAILURE yazabilir.

components[] şöyledir: { id, enabled?, relationPath? | inverse?, itemAst? }. enabled varsayılanı false’tur; atlanan veya false olan bir bileşen atlanır ve each düğümü hiçbir şey üretmez. Kaynak kayıttaki ileri çoklu alan için relationPath, bu kayda viaField ile işaret eden tür için inverse { objectTypeSlug, viaField } kullanın. itemAst bir ilgili satırın JSON gövdesidir. Gövde düğümü {"kind":"each","componentId":"<components[].id>"} olur ve satır dizisine genişler. Bir dizinin öğesi olan each düğümü o dizinin içine yayılır; tek öğesi each olan bir basketItems dizisi düz bir listedir. itemAst içindeki bağlama {"kind":"binding","id":"<bindings[].id>"} olur. Alan yolu binding id’sinde değil bindings[].ref üzerindedir. kind field veya relation_one ve ref line_total, satırdaki o alanı okur. ref id satır kaydının id’sini okur. product.name gibi noktalı bir ref, satırdan ilişkileri izler ve o kaydı çalışmanın yereline göre okur. kind var satırın içinde üst eşleme değişkeni olarak kalır. kind each bir satır değeri değildir. Nesne türü slug’ları tire (order-lines) veya alt çizgi içerebilir. Alan anahtarları snake_case kalır. get_integration_run (runId yoksa listeler), entegrasyon tanımlayabilen bir kullanıcı için her çalıştırmanın temizlenmiş isteğini ve upstream yanıtını döndürür. Herkese açık sayfa, giden gövdeyi değil upstream hatasını ve çalıştırma id’sini gösterir.

Üst gövdede kullanılan noktalı field veya relation_one ref’i, sorgunun kaynak türüne göre denetlenir (source.objectTypeSlug veya source.objectTypeId). Yalnızca bir inverse itemAst içinde kullanılan aynı ref, o inverse nesne türüne göre denetlenir. İlişki olmayan bir atlama, bindings içinde olmayan bir bağlama id’si, request.components içinde olmayan bir each componentId veya sitede türü olmayan bir inverse objectTypeSlug kayıtta 400 döner. Yaşam döngüsü eylemi update_matching_entries, objectTypeSlug türündeki mevcut satırları günceller. where 1–3 koşudur: { fieldKey, op, valueFrom?, value?, field? }. op eq, neq, empty, not_empty, lt veya gt olabilir. empty ve not_empty sağ taraf istemez. Diğerlerinde valueFrom literal (value) veya field (tetikleyen kayıttaki bir anahtar) olur. set, 1–8 öğelik bir dizidir. Her öğe { fieldKey, valueFrom: "literal", value } veya { fieldKey, valueFrom: "self" } şeklindedir. set bir nesne olursa 400 invalid_input döner ve path set’i gösterir. self, ziyaretçi o alanı yazamasa da tetikleyen kayda bir ilişki yazar. Eşleşme sınırlıdır. Eylemden sonra tetikleyen kaydın hesaplanan alanları aynı olaydaki sonraki eylemlerden önce yeniden hesaplanır; run_integration_query yeni toplamı görür.

Geçersiz bir sorgu path, received ve hint ile 400 invalid_input döner.

Webhook’lar

Gelen webhook bodyFormat değerini json, xml veya form yapar. form, application/x-www-form-urlencoded gövdesini ayrıştırır. target eski ve isteğe bağlı bir alandır. Davranışı handlers belirler; target olmadan bir form geri çağrısı geçerlidir. Geçersiz bir target nesnesi 400 invalid_input döner ve hiçbir şey yazılmaz.

Kayıt ve okuma yanıtındaki publicPath mutlak geri çağrı adresidir. Özel alan adı olmayan bir site https://hoc-site.com/api/integrations/{websiteId}/{urlName} kullanır. Özel alan adı https://{domain}/api/integrations/{urlName} kullanır. Website id’yi bir sayfa yolunda /api önüne koymayın. O adres bir sayfadır, bu geri çağrı değildir.

handlers, {id, name, enabled, constraints, actions} dizisidir. update_entry için objectTypeId veya objectTypeSlug, matchKeyPath ve fields gerekir. run_integration_query için queryId veya queryName gerekir. redirect successUrl, failureUrl, statusPath (varsayılan entry.payment_status), successValue (varsayılan SUCCESS), isteğe bağlı query ve isteğe bağlı localePath kullanır. query en fazla 8 { name, path } kaydıdır. path, entry.id veya entry.payment_error gibi bir entegrasyon yoludur ve genel URL’ye eklenir. localePath (örneğin locale) website birincil yerel ayarı yerine o genel yerel ayarı seçer. Göreli bir yönlendirme sitenin genel yoluyla öneklenir. Bir ödeme geri çağrısı siparişi güncelleyip retrieve sorgusunu çalıştırabilir, sonra yönlendirebilir.

Silmek için resource webhooks, action delete ve webhookId gönderin.

Tekrar koruması idempotency.keyParts üzerindedir; örneğin {"kind":"jsonPath","path":"token"}. Yol ayrıştırılmış gövdeden okunur; token, body.token ve webhook.body.token token adlı form alanını okur. Bir anahtarın ilk POST’u işleyicileri çalıştırır. Aynı anahtar için ilki sürerken gelen ikinci POST 409 in_flight döner. İşlenmiş bir tekrar, saklanan yönlendirmeyi 303 olarak yineler. Yönlendirme saklanmadıysa gövde 200 {"ok":true,"duplicate":true} olur.

İşleyici alan kaynakları literal veya path’tir. Webhook gövdesinin kökü webhook.body’dir (webhook.body.token). body kökü yoktur. kind webhook yalnızca mapping set_var için geçerlidir. Çözülemeyen bir path atlanır ve kayıtlı alanı silmez. Yazılan değerler alan şemasına, enum seçenekleri dahil, göre denetlenir.

successUrl ve failureUrl, / ile başlayan bir site yolu veya bu sitenin ya da platform kökeninin http(s) adresidir. Başka bir değer kayıtta 400 invalid_input döner. Location, iç sunucu adresini değil genel site kökenini kullanır (yol önekli geri çağrıda https://hoc-site.com, özel alan adında o alan adı). Göreli bir yol, localePath çözülürse o yerel ayarla, yoksa website birincil yerel ayarıyla öneklenir.

Geçersiz bir webhook path ile 400 invalid_input döner.