Herkese açık API

Yardım masası tek bir herkese açık API sunar: bir GraphQL uç noktası. Şemadaki her işlem, bir kişisel erişim jetonuyla (Personal Access Token, PAT) tarayıcı dışından erişilebilir.

Bu sayfa sözleşmenin kendisidir — neyin kararlı olduğu, nasıl kimlik doğrulanacağı, kapsamların neye izin verdiği ve hataların nasıl biçimlendiği. hdmx CLI bunun üzerine kuruludur ve API sürümleme bu yüzeyin nasıl geliştiğini anlatır.

Uç nokta

POST https://<your-host>/backend/<subdomain>/api/<version>/graphql

<subdomain> hesabınızı tanımlar (oturum açarken kullandığınız adın aynısı).
<version>, 2026-07 gibi tarihli bir API sürümüdür — bkz. API sürümleme. Sürüm bölümünü atlayıp …/backend/<subdomain>/graphql adresini de çağırabilirsiniz; bu durumda istek, desteklenen en eski sürüm tarafından karşılanır ve her yanıt hangi sürümün cevap verdiğini size bildirir.

Kimlik doğrulama

Kişisel erişim jetonunu Bearer kimlik bilgisi olarak gönderin:

Authorization: Bearer hdmx_<random>

Bir PAT uzun ömürlüdür (ancak son kullanma tarihi zorunludur), kapsamlar taşır, IP ile sınırlıdır ve iptal edilebilir. Tek bir hesaba bağlıdır: bir jetonu başka bir hesabın alt alan adında sunmak HTTP 401 ile reddedilir.

Jeton oluşturma

Jetonları temsilci uygulamasında Settings → API tokens altında kendiniz oluşturup yönetin:

New token düğmesine tıklayın.
Daha sonra tanıyabileceğiniz bir ad verin.
Bir son kullanma süresi seçin (en fazla 365 gün — "hiçbir zaman" seçeneği yoktur).
Bir erişim politikası belirleyin — bu jetonun ihtiyaç duyduğu kaynakları tam olarak, okuma ya da okuma-yazma düzeyinde açın. Varsayılan olarak hiçbir şeye erişim yoktur.
İzin listesine en az bir IP adresi veya CIDR ekleyin (zorunlu — bkz. IP izin listesi). Form, mevcut IP adresinizi sizin yerinize ekleyebilir.
Gözden geçirin ve oluşturun. Jetonun tamamı yalnızca bir kez gösterilir — hemen kopyalayın. Yalnızca bir özet (hash) saklandığı için jeton bir daha asla gösterilemez; kaybederseniz yeni bir jeton almak için mevcut jetonu döndürün.

Daha sonra bir jetonun erişim politikasını ve izin listesini düzenleyebilir, jetonu döndürebilir (yeni bir gizli anahtar üretirken eskisi kısa bir tolerans süresi boyunca çalışmaya devam eder; böylece kesintisiz geçiş yaparsınız) ve iptal edebilirsiniz. Her jeton, en son ne zaman ve nereden kullanıldığını ve ayrıca son etkinlik günlüğünü gösterir.

Kapsamlar

Erişim kaba taneli olup kaynak ailelerine göre düzenlenmiştir. Bir jeton sabit bir kapsam kümesi taşır; her üst düzey işlem bunlardan birini denetler.

Kapsam	Verdiği yetki
`tickets:read`	Talepleri, mesajları, taslakları, geçmişi, ekleri ve raporları okuma
`tickets:write`	Talep oluşturma / güncelleme / silme, mesaj gönderme, ek yükleme. `tickets:read` yetkisini de kapsar
`chat:read`	Sohbetleri, görüşmeleri, mesajları ve oturumları okuma
`chat:write`	Temsilci mesajı gönderme, görüşmelere katılma / ayrılma / kapatma / yeniden açma. `chat:read` yetkisini de kapsar
`customers:read`	Müşteri kayıtlarını okuma
`customers:write`	Müşteri kayıtlarını oluşturma / güncelleme / birleştirme. `customers:read` yetkisini de kapsar
`settings:read`	Hesap ayarlarını okuma (departmanlar, durumlar, öncelikler, posta kutuları — gizli bilgiler hariç)

Posta kutusu kimlik bilgisi alanları (IMAP/SMTP kullanıcı adları, parolaları ve sunucuları) kapsam ne olursa olsun bir jetona asla döndürülmez — bu gizli bilgiler e-posta sağlayıcınıza aittir ve herkese açık API'nin erişemeyeceği yerde kalır.

Hata sınıflandırması

GraphQL yanıtları errors[].extensions.code alanını kullanır:

Kod	Anlamı	HTTP
`SCOPE_DENIED`	Jetonda gerekli kapsam yok. `extensions.valid_values`, işlemi karşılayacak kapsamları listeler	200
`RATE_LIMITED`	Jeton başına istek bütçesi tükendi. `extensions.retryAfter` sıfırlamaya kalan saniye sayısıdır ve `Retry-After` başlığı da aynı sayıyı taşır	429
`INVALID_API_TOKEN`	Jeton bulunamadı, biçimi hatalı veya başka bir nedenle kullanılamıyor	200

İptal edilmiş jetonlar, süresi dolmuş jetonlar, hesaplar arası uyuşmazlıklar ve IP izin listesi reddi, sorgu çalıştırılmadan önce engellenir ve GraphQL gövdesi olmayan HTTP 401 olarak döner. Jetonlu bir istekte alınan 401'i "bu jeton artık bu istek için geçerli değil — son kullanma tarihini, kapsamlarını ve IP izin listesini denetle" biçiminde değerlendirin.

İstek limitleri

Jetonlu her istek şu başlıkları taşır:

X-RateLimit-Limit: 120
X-RateLimit-Remaining: 96
X-RateLimit-Reset: 1715692800

Varsayılan bütçe jeton başına dakikada 120 istektir. Okuma da olsa yazma da olsa her istek 1 birim harcar. Limitin aşılması, Retry-After başlığı ve extensions.code = "RATE_LIMITED" ile birlikte HTTP 429 döndürür; düzgün davranan bir istemci sıfırlama anına kadar bekler.

IP izin listesi

Kendi kendine oluşturulan her jeton en az bir IP veya CIDR taşımak zorundadır — "herhangi bir IP" jetonu diye bir şey yoktur. Her isteğin kaynak IP'si jetonun listesiyle karşılaştırılır; eşleşmeyen istek HTTP 401 ve extensions.sub_code = "ip_not_allowed" ile reddedilir.

IPv4, IPv6 ve CIDR aralıklarının tümü kabul edilir. Tek bir sunucu için /32 (IPv4) veya /128 (IPv6) kullanın.
Aralıklar kaydedilirken doğrulanır ve normalleştirilir.
İzin listesi oluşturulduktan sonra düzenlenebilir — düzenlemek gizli anahtarı değiştirmez.

Jetonu kararlı bir çıkış noktasından kullanın: bir CI koşucusu, zamanlanmış bir görev, sabit bir ofis NAT'ı veya bilinen bir IP aralığındaki kendi sunucularınız. Sızdırılmış bir jeton, izin listesinin dışındaki hiçbir yerden işe yaramaz.

Jeton etkinliği

Bir jetonun yaptığı her kimliği doğrulanmış istek kaydedilir: zaman, işlem adı, kaynak IP, sonuç (başarı, hata, limit aşımı, kapsam reddi, iptal edilmiş veya süresi dolmuş) ve gidiş-dönüş gecikmesi. Bir jeton beklenmedik davrandığında bakılacak iz budur.

Sürümleme ve kullanımdan kaldırma

API, tarihli YYYY-MM sürümleriyle sürümlenir. URL'de bir sürümü sabitleyin; en az 12 ay boyunca kararlı kalır. Kullanımdan kaldırmalar, kullandığınız bir şey ortadan kalkmadan önce iletişim içinde duyurulur. Politikanın tamamı için bkz. API sürümleme.

Şemayı keşfetme

Şema kendini tanımlar: türleri üretmek ve yüzeyi incelemek için sürümlü uç noktaya karşı standart GraphQL iç gözlemini kullanın. Etkileşimli GraphQL Playground …/backend/<subdomain>/playground adresinde bulunur.

curl ile hızlı başlangıç

Bu örnekler helpdesk.example.com sunucusunu, acme alt alan adını, 2026-07 sürümünü ve $TOKEN içindeki bir jetonu varsayar.

Geçerli kullanıcıyı okuma (herhangi bir kapsam)

curl -sS https://helpdesk.example.com/backend/acme/api/2026-07/graphql \
  -H "Authorization: Bearer $TOKEN" \
  -H "Content-Type: application/json" \
  -d '{"query":"{ currentUser { id email firstname lastname } }"}'

Son talepleri listeleme (`tickets:read`)

curl -sS https://helpdesk.example.com/backend/acme/api/2026-07/graphql \
  -H "Authorization: Bearer $TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "query": "query ($first: Int!) {
      ticketList(first: $first) {
        edges { node { code subject status { name } updatedAt } }
      }
    }",
    "variables": { "first": 10 }
  }'

Herkese açık bir yanıt gönderme (`tickets:write`)

curl -sS https://helpdesk.example.com/backend/acme/api/2026-07/graphql \
  -H "Authorization: Bearer $TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "query": "mutation ($input: SaveTicketInput!) {
      saveTicket(input: $input) {
        ticket { code }
        error { code message }
      }
    }",
    "variables": {
      "input": {
        "id": "TICKET-UUID-HERE",
        "message": "Thanks — fixing this now.",
        "messageType": "PUBLIC"
      }
    }
  }'

Günlük kullanımda hdmx CLI bu yüzeyin tamamını kullanışlı komutların arkasına sarar.

Herkese açık API

Uç nokta​

Kimlik doğrulama​

Jeton oluşturma​

Kapsamlar​

Hata sınıflandırması​

İstek limitleri​

IP izin listesi​

Jeton etkinliği​

Sürümleme ve kullanımdan kaldırma​

Şemayı keşfetme​

curl ile hızlı başlangıç​

Geçerli kullanıcıyı okuma (herhangi bir kapsam)​

Son talepleri listeleme (tickets:read)​

Herkese açık bir yanıt gönderme (tickets:write)​