PATCH/v1/apps/{app_id}

OAuth uygulamasını güncelleme

update_app

Gönderdiğiniz alanları değiştirir. scopes değerini daraltmak, daha önce verilmiş belirteçleri de hemen daraltır; genişletme yalnızca yeni yetkilendirmelere uygulanır. role ve data_profile yalnızca confidential bir uygulamaya uygulanır. İstemci türü değiştirilemez. 1.62.0 sürümünde eklendi.

Kimlik doğrulama

API anahtarını Authorization başlığında gönderin: Authorization: Bearer <anahtar>.

Yol parametreleri

app_idstringzorunlu
Uygulama kimliği (app_…); aynı zamanda client_id değeridir.
length ≤ 36

Başlık parametreleri

Idempotency-Keystring
Bir yazma işleminin güvenli yeniden denenmesi için idempotency anahtarı (aynı isteğin tekrarı işlemi ikinci kez çalıştırmaz): 1–255 yazdırılabilir ASCII karakteri; her mantıksal işlem için bir UUID v4 önerilir. 24 saat içinde aynı anahtarla yapılan yeniden deneme işlemi tekrar çalıştırmaz: kaydedilmiş yanıtı (durum, başlıklar ve gövde) Idempotency-Replayed: true başlığıyla döndürür. Aynı anahtar farklı bir yöntem, yol, Content-Type ya da gövdeyle kullanılırsa 409 api.idempotency_mismatch döner; ilk istek hâlâ çalışırken Retry-After: 1 ile birlikte 409 api.idempotency_in_progress döner. 5xx ya da 429 yanıtından sonra anahtar serbest bırakılır ve yeniden deneme işlemi tekrar çalıştırır. Anahtar kuruluşa ve çağırana özgüdür (API anahtarı, kullanıcı ya da özel kaynak anahtarı).
length ≥ 1, length ≤ 255

İstek gövdesi

application/json

Nesne: OAuthAppUpdate

namestring
Onay ekranı için ad.
length ≥ 1, length ≤ 100
descriptionstring
Onay ekranı için açıklama.
length ≤ 1000
homepage_urlstring | null
Uygulamanın web sitesi; null ya da boş dize onu kaldırır.
length ≤ 2000
redirect_urisarray of string
Yönlendirme URI’lerinin eksiksiz yeni listesi.
items ≤ 10
scopesarray of OAuthScope
Kapsamların eksiksiz yeni kümesi.
items ≥ 1
rolestring
Client credentials belirteçlerinin rolü (yalnızca confidential).
data_profilestring
Client credentials belirteçlerinin veri profili (yalnızca confidential).

Yanıtlar

200Başarılı yanıt

Yanıt başlıkları

RateLimit-Policy
Geçerli limitler, IETF taslağı draft-ietf-httpapi-ratelimit-headers biçiminde: virgülle ayrılmış "<name>";q=<quota>;w=<window in seconds> öğeleri. key, API anahtarının istek hızıdır (kota ani artış payıdır, zaman penceresi bu payın tamamen dolma süresidir; oturum için user, kimlik bilgisi olmadan ip); minute, day ve month, kuruluşun UTC’ye göre takvim dakikası, günü ve ayı için kotalarıdır.
RateLimit
RateLimit-Policy içindeki her limitten kalan: "<name>";r=<remaining>;t=<seconds until reset>.
X-RateLimit-Limit
RateLimit-Policy içindeki en sıkı girdinin limiti (en az istek hakkı kalan girdi).
X-RateLimit-Remaining
En sıkı limitte kalan istek sayısı.
X-RateLimit-Reset
En sıkı limitin sıfırlanmasına kalan saniye.
Idempotency-Replayed
true: yanıt bu Idempotency-Key için kaydedilmiş yanıttan yeniden verildi; işlem tekrar çalışmadı.

application/json

Nesne: OAuthApp

idstringzorunlu
Uygulama kimliği (app_ ve 32 onaltılık karakter); aynı zamanda client_id değeridir.
namestringzorunlu
Çalışanın onay ekranında gördüğü ad.
descriptionstringzorunlu
Onay ekranı için açıklama (boş olabilir).
homepage_urlstring | nullzorunlu
Uygulamanın web sitesi.
client_typeOAuthClientTypezorunlu
redirect_urisarray of stringzorunlu
İzin verilen yönlendirme URI’leri (dizeyle birebir eşleşme).
scopesarray of OAuthScopezorunlu
Uygulamanın isteyebileceği kapsamlar.
client_secret_prefixstring | nullzorunlu
Tanımak için istemci gizli değerinin ilk karakterleri; herkese açık uygulamada null.
rolestring | nullzorunlu
Client credentials belirteçlerinin rolü (admin, editor, verifier, viewer); herkese açık uygulamada null.
data_profilestring | nullzorunlu
Client credentials belirteçlerinin veri profili; herkese açık uygulamada null.
authorizationsintegerzorunlu
Etkin çalışan yetkilendirmelerinin sayısı.
created_atstring (date-time)zorunlu
updated_atstring (date-time)zorunlu

400İstek geçersiz: bir parametre değeri ya da nesnenin durumu işleme izin vermiyor (`detail` bir iletidir).

Yanıt başlıkları

RateLimit-Policy
Geçerli limitler, IETF taslağı draft-ietf-httpapi-ratelimit-headers biçiminde: virgülle ayrılmış "<name>";q=<quota>;w=<window in seconds> öğeleri. key, API anahtarının istek hızıdır (kota ani artış payıdır, zaman penceresi bu payın tamamen dolma süresidir; oturum için user, kimlik bilgisi olmadan ip); minute, day ve month, kuruluşun UTC’ye göre takvim dakikası, günü ve ayı için kotalarıdır.
RateLimit
RateLimit-Policy içindeki her limitten kalan: "<name>";r=<remaining>;t=<seconds until reset>.
X-RateLimit-Limit
RateLimit-Policy içindeki en sıkı girdinin limiti (en az istek hakkı kalan girdi).
X-RateLimit-Remaining
En sıkı limitte kalan istek sayısı.
X-RateLimit-Reset
En sıkı limitin sıfırlanmasına kalan saniye.

application/json

Nesne: Error

401Kimlik bilgisi gönderilmedi (ne oturum çerezi ne de API anahtarı) ya da anahtar bulunamadı.

Yanıt başlıkları

RateLimit-Policy
Geçerli limitler, IETF taslağı draft-ietf-httpapi-ratelimit-headers biçiminde: virgülle ayrılmış "<name>";q=<quota>;w=<window in seconds> öğeleri. key, API anahtarının istek hızıdır (kota ani artış payıdır, zaman penceresi bu payın tamamen dolma süresidir; oturum için user, kimlik bilgisi olmadan ip); minute, day ve month, kuruluşun UTC’ye göre takvim dakikası, günü ve ayı için kotalarıdır.
RateLimit
RateLimit-Policy içindeki her limitten kalan: "<name>";r=<remaining>;t=<seconds until reset>.
X-RateLimit-Limit
RateLimit-Policy içindeki en sıkı girdinin limiti (en az istek hakkı kalan girdi).
X-RateLimit-Remaining
En sıkı limitte kalan istek sayısı.
X-RateLimit-Reset
En sıkı limitin sıfırlanmasına kalan saniye.

application/json

Nesne: Error

403İşleme izin verilmiyor: rol yetersiz, koleksiyona ya da karta erişim yok, istek “View as” modunda çalışıyor ya da kuruluş askıya alınmış veya silinmiş (`detail`, `code: org_suspended | org_deleted` içeren bir nesnedir).

Yanıt başlıkları

RateLimit-Policy
Geçerli limitler, IETF taslağı draft-ietf-httpapi-ratelimit-headers biçiminde: virgülle ayrılmış "<name>";q=<quota>;w=<window in seconds> öğeleri. key, API anahtarının istek hızıdır (kota ani artış payıdır, zaman penceresi bu payın tamamen dolma süresidir; oturum için user, kimlik bilgisi olmadan ip); minute, day ve month, kuruluşun UTC’ye göre takvim dakikası, günü ve ayı için kotalarıdır.
RateLimit
RateLimit-Policy içindeki her limitten kalan: "<name>";r=<remaining>;t=<seconds until reset>.
X-RateLimit-Limit
RateLimit-Policy içindeki en sıkı girdinin limiti (en az istek hakkı kalan girdi).
X-RateLimit-Remaining
En sıkı limitte kalan istek sayısı.
X-RateLimit-Reset
En sıkı limitin sıfırlanmasına kalan saniye.

application/json

Nesne: Error

404Nesne yok ya da size açık değil. API, erişimi kısıtlı bir nesnenin var olduğunu belli etmez.

Yanıt başlıkları

RateLimit-Policy
Geçerli limitler, IETF taslağı draft-ietf-httpapi-ratelimit-headers biçiminde: virgülle ayrılmış "<name>";q=<quota>;w=<window in seconds> öğeleri. key, API anahtarının istek hızıdır (kota ani artış payıdır, zaman penceresi bu payın tamamen dolma süresidir; oturum için user, kimlik bilgisi olmadan ip); minute, day ve month, kuruluşun UTC’ye göre takvim dakikası, günü ve ayı için kotalarıdır.
RateLimit
RateLimit-Policy içindeki her limitten kalan: "<name>";r=<remaining>;t=<seconds until reset>.
X-RateLimit-Limit
RateLimit-Policy içindeki en sıkı girdinin limiti (en az istek hakkı kalan girdi).
X-RateLimit-Remaining
En sıkı limitte kalan istek sayısı.
X-RateLimit-Reset
En sıkı limitin sıfırlanmasına kalan saniye.

application/json

Nesne: Error

409Nesnenin durumu işleme izin vermiyor; örneğin yinelenen bir kayıt, süren bir dizinleme ya da zaten işlenmiş bir iş.

Yanıt başlıkları

RateLimit-Policy
Geçerli limitler, IETF taslağı draft-ietf-httpapi-ratelimit-headers biçiminde: virgülle ayrılmış "<name>";q=<quota>;w=<window in seconds> öğeleri. key, API anahtarının istek hızıdır (kota ani artış payıdır, zaman penceresi bu payın tamamen dolma süresidir; oturum için user, kimlik bilgisi olmadan ip); minute, day ve month, kuruluşun UTC’ye göre takvim dakikası, günü ve ayı için kotalarıdır.
RateLimit
RateLimit-Policy içindeki her limitten kalan: "<name>";r=<remaining>;t=<seconds until reset>.
X-RateLimit-Limit
RateLimit-Policy içindeki en sıkı girdinin limiti (en az istek hakkı kalan girdi).
X-RateLimit-Remaining
En sıkı limitte kalan istek sayısı.
X-RateLimit-Reset
En sıkı limitin sıfırlanmasına kalan saniye.

application/json

Nesne: Error

422Geçerlilik hatası: gövde ya da parametreler şemaya uymuyor (`detail` geçerlilik hatalarının listesidir) ya da bir parametre değeri aralığın dışında (`detail` bir iletidir).

Yanıt başlıkları

RateLimit-Policy
Geçerli limitler, IETF taslağı draft-ietf-httpapi-ratelimit-headers biçiminde: virgülle ayrılmış "<name>";q=<quota>;w=<window in seconds> öğeleri. key, API anahtarının istek hızıdır (kota ani artış payıdır, zaman penceresi bu payın tamamen dolma süresidir; oturum için user, kimlik bilgisi olmadan ip); minute, day ve month, kuruluşun UTC’ye göre takvim dakikası, günü ve ayı için kotalarıdır.
RateLimit
RateLimit-Policy içindeki her limitten kalan: "<name>";r=<remaining>;t=<seconds until reset>.
X-RateLimit-Limit
RateLimit-Policy içindeki en sıkı girdinin limiti (en az istek hakkı kalan girdi).
X-RateLimit-Remaining
En sıkı limitte kalan istek sayısı.
X-RateLimit-Reset
En sıkı limitin sıfırlanmasına kalan saniye.

application/json

Nesne: Error

429Çok fazla istek (`api.rate_limited`), kuruluşun dakika, gün ya da ay kotası doldu (`api.quota_exceeded`; `error.details` alanında `quota`, `limit` ve `reset_at` bulunur), kuruluşun limitine ulaşıldı ya da yanıt hizmeti meşgul (`answers.engine_busy`). `Retry-After` başlığındaki süre kadar bekleyin.

Yanıt başlıkları

Retry-After
İsteği yeniden denemeden önce beklenmesi gereken saniye sayısı.
RateLimit-Policy
Geçerli limitler, IETF taslağı draft-ietf-httpapi-ratelimit-headers biçiminde: virgülle ayrılmış "<name>";q=<quota>;w=<window in seconds> öğeleri. key, API anahtarının istek hızıdır (kota ani artış payıdır, zaman penceresi bu payın tamamen dolma süresidir; oturum için user, kimlik bilgisi olmadan ip); minute, day ve month, kuruluşun UTC’ye göre takvim dakikası, günü ve ayı için kotalarıdır.
RateLimit
RateLimit-Policy içindeki her limitten kalan: "<name>";r=<remaining>;t=<seconds until reset>.
X-RateLimit-Limit
RateLimit-Policy içindeki en sıkı girdinin limiti (en az istek hakkı kalan girdi).
X-RateLimit-Remaining
En sıkı limitte kalan istek sayısı.
X-RateLimit-Reset
En sıkı limitin sıfırlanmasına kalan saniye.

application/json

Nesne: Error

Hata kodları

Bu uç noktanın, her isteğin genel kodlarının yanı sıra error.code alanında döndürebileceği kodlar.

Güvenli yeniden denemeler

Her POST ve PATCH isteğiyle bir Idempotency-Key başlığı (örneğin bir UUID) gönderin. Aynı anahtarla 24 saat içinde yapılan yeniden deneme, isteği yeniden çalıştırmak yerine kaydedilmiş yanıtı döndürür.

Hız sınırları

Yanıtlarda RateLimit ve RateLimit-Policy başlıklarıyla birlikte daha eski X-RateLimit-Limit, X-RateLimit-Remaining ve X-RateLimit-Reset başlıkları bulunur. 429 yanıtında saniye cinsinden Retry-After başlığı vardır: bekleyin ve yeniden deneyin.

← apps · API başvurusu

curl -X PATCH 'https://api.sursa.com/v1/apps/APP_ID' \
  -H "Idempotency-Key: $(uuidgen)" \
  -H "Content-Type: application/json" \
  -d '{"name":"support","description":"Customer support articles","homepage_url":"string"}' \
  -H "Authorization: Bearer $SURSA_API_KEY"

Dene

API anahtarı

Anahtar bu sekmenin belleğinde kalır ve yalnızca https://api.sursa.com adresine gönderilir.

İstekler kuruluşunuzun gerçek verileri üzerinde çalışır.

app_id path *

Idempotency-Key header

Idempotency-Key

Bu alan boş bırakılırsa her istek için yeni bir anahtar oluşturulur.

İstek gövdesi (JSON)