Skava Skava / Wiki

Geliştiriciler için Özel Öğeleri Bağlama

Bu sayfa, bir şirketin arka ucunu Skava'ya bağlayan geliştiriciler içindir. Bir API öğesinin nasıl oluşturulup yayına alındığı Özel Öğeler: API arayüzleri sayfasında anlatılır; burada ise hattın diğer ucunda gerçekleşmesi gereken her şeyi ele alıyoruz.

Fikri tek cümlede özetleyelim: Skava alanınızı bilmez. Tek bir formatı bilir, o da karttır. Kartta ne yazacağına siz karar verirsiniz; biz yalnızca biçimi, boyutu ve güvenliği kontrol ederiz. Bir malzeme siparişi bunun bir örneğidir; bir sonraki şirket kullanıcı geri bildirimi toplar, ondan sonraki ise şantiye fotoğrafını kendi kayıtlarına işler.

Akışın genel görünümü

  1. Bir şirket yöneticisi Skava'da bir API öğesi oluşturur: bir form ve arka ucunuzun adresi, yöntemi ve jetonu.
  2. Sohbetteki biri formu doldurup gönderir.
  3. Skava, arka uç sisteminizi çağırır ve doldurulan değerleri JSON olarak gönderir.
  4. Cevabınız, sohbette bir kart haline gelir.
  5. İsteğe bağlı olarak, daha sonra geri çağırma yoluyla yeni durumları bildirebilirsiniz. Her bildirim yeni bir kart oluşturur; önceki kart yerinde kalır.

Arka uç sisteminiz için gereksinimler

  • HTTPS. Yalnızca https://, http değil, adreste kimlik bilgisi yok, en fazla 2000 karakter.
  • Herkese açık erişilebilir. Ana bilgisayar yalnızca herkese açık IP adreslerine çözülmelidir. Yerel ana bilgisayar, özel ağlar, bağlantı yerel ve bulut meta verileri reddedilir ve bu her çağrıda kontrol edilir.
  • Sabit adres. Skava ana bilgisayarı bir kez çözer ve bağlantıyı o IP'ye sabitler. Çağrı sırasında DNS değişikliğinin etkisi yoktur.
  • Yönlendirme yok. "Doğru" adrese yapılan 301 yönlendirmesi bir hata olarak sayılır. Nihai adresi hemen girin.
  • Yanıt süresi. Zaman aşımı öğe başına yapılandırılabilir ve 30 saniye ile sınırlıdır. Daha uzun süre gerekiyorsa, hemen yanıt verin ve sonucu daha sonra geri çağırma yoluyla bildirin.
  • Yanıt boyutu. Skava en fazla 256 KiB okur.
  • Content-Type. Gövde yalnızca application/json ile ayrıştırılır.

Size ulaşan istek

Yöntem, öğeye bağlı olarak GET, POST, PUT veya PATCH olabilir. POST, PUT ve PATCH ile değerler JSON gövdesi olarak, GET ile sorgu parametreleri olarak gelir.

Kimlik doğrulama, öğede yapılandırılan adı ve değer öneki olan tek bir başlıktır, genellikle Authorization ve Bearer öneki. Jeton tarafımızda şifreli olarak saklanır. host, content-length, content-type, cookie ve accept-encoding başlıkları ayarlanamaz.

Gövde düz bir nesnedir. Anahtarları, öğeyi oluşturan kişi seçer; iç içe geçme yalnızca bir tablo veya ürün seçici eklendiğinde ortaya çıkar:

{"artikelnummer": "5100110", "menge": 20, "note": "Please deliver in the morning", "orderer": "Jonas Berger", "company": "Sanitar Berger GmbH", "project": "Spitalstrasse 11", "locale": "de", "callback_url": "https://chat.skava.io/api/v1/custom-elements/interactions/…", "callback_token": "…"}

Üç anahtar her zaman bizden gelir, bu yüzden kendiniz kullanmayın:

  • locale: kullanıcının dil kodu. Bu dilde yanıt verin; metinlerinizi biz çevirmiyoruz.
  • callback_url ve callback_token: bu etkileşim için geri çağırma, aşağıya bakın. Yalnızca çağrı bir sohbetten geldiğinde mevcut olurlar.

Ad, şirket, proje veya alt sohbet gibi bağlam alanları, sunucu tarafından doldurulur ve öğenin çalıştırıldığı kanaldan türetilir. Değiştirilmiş bir istemci, orada farklı bir proje adı iddia edemez.

Yanıt: kart biçimi

2xx yanıtı ve bir card nesnesi döndürün. Sohette görünen kart tam olarak budur:

{"card": {"v": 1, "title": "Order BST-10001", "state": "pending", "status_text": "Order received", "icon": "package", "fields": [{"label": "Order number", "value": "BST-10001"}, {"label": "Expected", "value": "14/08/2026"}]}}

  • v (zorunlu): 1 tamsayısı. Metin olarak ("1") gönderilirse reddedilir. Bu alan yoksa yanıt kart olarak sayılmaz ve öğede yapılandırılan yanıt eşlemesi uygulanır.
  • title: kartın başlığı.
  • state: yalnızca renk ve simge tonu belirler; değer ok, pending, warn veya error olabilir. Bilinmeyen bir değer ok olarak ele alınır ve bir ipucu gösterilir.
  • status_text: yorumlamadığımız serbest metin. Kartın üst kısmında yer alır ve sohbet listesinde ile bildirimde de görünür.
  • fields: label ve value içeren bir liste. En fazla 20 kayıt, label 80 karakter, value 200, title ve status_text ise 120 karakter. Çok uzun değerler reddedilmez, kısaltılır: bir sipariş, küçük bir detay yüzünden başarısız olmamalıdır.
  • icon: aşağıya bakın.

Skava'nın metinleriniz sohbeti ulaşmadan önce yaptığı işlemler: satır sonları ve kontrol karakterleri kaldırılır (sağdan sola yazılan bir karakter, tutarın görüntülenmesini tersine çevirebilir), geri tırnaklar değiştirilir ve [SKAVA: ile başlayan her şey etkisiz hale getirilir. Son işlem, bir kart değerinin farklı bir sohbet öğesi, örneğin bir ödeme talebi olarak okunmasını önler.

Alanlardaki bağlantılar, HTML ve görseller ayarlanamaz. Sohbet güvenli bir ortamdır ve harici bir arka uçtan gelen tıklanabilir bir adres, giriş sayfasını yeniden inşa etmeye davet olurdu.

Kullanıcının girdileri sunucuya aittir: ilk kartta görünürler ve üzerine yazamazsınız. Sohbet içinde bunlar, gerçekten gönderilen verilerin kaydıdır.

Simgeler

icon ile karta başlıkta kendi işareti eklenir. İki yöntem:

Bir ad paketlenmiş setten: package, package-check, package-open, box, boxes, truck, forklift, warehouse, settings, cog, gauge, wrench, hammer, drill, hard-hat, ruler, paint-roller, construction, clipboard-check, receipt, file-text, camera, clock, calendar-clock, circle-check, circle-alert, triangle-alert, send, mail-check, shopping-cart, credit-card, map-pin.

Veya kendi SVG'niz bir dize olarak. Skava bundan yalnızca geometriyi alır (path, circle, ellipse, rect, line, polyline, polygon ve sayısal öznitelikleri) ve kendi görselini oluşturur. Betikler, stiller, dış referanslar, foreignObject ve olay öznitelikleri atılır; bir doctype veya varlık reddedilmeye yol açar; dosya en fazla 8 KiB olabilir ve en fazla 16 şekil içerebilir. Renk, çizgi kalınlığı ve boyut Skava tarafından ayarlanır, bu nedenle bir simge bir denetim gibi davranamaz. 24x24 ızgarası üzerinde çalışın.

icon yoksa varsayılan işaret kalır.

Geri çağırma: sonraki durumları bildirme

Çağrı callback_url ve callback_token içerir. Sonraki yeni durumları bildirmek için bunları kullanın:

POST <callback_url>, Authorization: Bearer <callback_token> ve Content-Type: application/json ile, gövde en fazla 32 KiB:

{"card": {"v": 1, "title": "Order BST-10001", "state": "pending", "status_text": "Shipped", "icon": "truck", "fields": [{"label": "Tracking number", "value": "DPD123456789"}]}, "seq": 3, "final": false}

Kartın dışında üç isteğe bağlı değer vardır:

  • seq: kendi sayacınız. Daha küçük veya eşit bir değere sahip raporlar, iki raporun birbirini geçmesini önlemek için elenir. seq yoksa son ulaşan kazanır.
  • final: etkileşimi kapatır. Jeton geçersiz hale gelir ve başka kartlar görünmez. Takip sorusu olmayan akışlar için ilk yanıtta da kullanılabilir.
  • notify: kartı okunmamış sayacı ve bildirimi olmadan sessizce göndermek için false olarak ayarlayın. Kimseyi uyandırmaması gereken ara adımlar için idealdir. Ayarlanmazsa kart tamamen normal bir mesajdır.

Her rapor, sohbetin kendi kartı haline gelir, önceki kart kalır. Böylece hangi durumun raporlandığı okunabilir. Buradan bir öneri çıkar: yalnızca değişenleri gönderin. Sipariş numarasını, kalemleri ve toplamı dördüncü kez tekrarlayan bir kart, okuyucu için sadece gürültüdür.

İki sınır: aynı raporun iki kez gönderilmesi ikinci bir kart üretmez ve bir etkileşim en fazla 50 kart gönderebilir. Bir etkileşim raporları 90 gün boyunca kabul eder.

Yanıt vermeniz gereken yanıtlar

  • 200 ve {"result": "success", "updated": true, "seq": 3, "closed": false, "hints": []}. İpuçlarını okuyun: kısaltılan veya düşürülen öğeleri belirtirler.
  • 401: yanlış token veya etkileşim kimliği. Tekrar denemeyin.
  • 410: etkileşim kapatıldı veya süresi doldu. Tekrar denemeyin.
  • 422: kart kullanılamıyor, neden olarak hints veriliyor. Önce bunu düzeltin.
  • 400 bozuk JSON, 413 çok büyük, 429 çok fazla istek (geri çekilerek yeniden deneyin), 500 bizim hatamız, daha sonra tekrar deneyin.

Örnek 1: durum geçmişine sahip bir sipariş

1. adım, arka uçunuza gönderilen istek:

POST https://api.example.com/v1/orders
Authorization: Bearer <your token>
{"artikelnummer": "5100110", "menge": 20, "orderer": "Jonas Berger", "company": "Sanitar Berger GmbH", "locale": "de", "callback_url": "https://chat.skava.io/api/v1/custom-elements/interactions/1111…", "callback_token": "secret"}

2. adım, anlık yanıtınız:

{"card": {"v": 1, "title": "Order BST-10001", "state": "pending", "status_text": "Order received", "icon": "package", "fields": [{"label": "Order number", "value": "BST-10001"}, {"label": "Expected", "value": "14/08/2026"}]}}

Sohbet artık bir paket simgesi, durum ve kullanıcının girdilerini içeren bir kart gösterir.

3. adım, seçim sırasında:

POST <callback_url> to {"card": {"v": 1, "title": "Order BST-10001", "state": "pending", "status_text": "Being picked", "icon": "cog", "fields": []}, "seq": 2, "notify": false}

Alanları olmayan sessiz bir ikinci kart: yalnızca durum değişti.

4. adım, gönderim sırasında:

POST <callback_url> to {"card": {"v": 1, "title": "Order BST-10001", "state": "pending", "status_text": "Shipped", "icon": "truck", "fields": [{"label": "Tracking number", "value": "DPD123456789"}, {"label": "Carrier", "value": "DPD"}]}, "seq": 3}

Bu kart birini uyandırabilir, bu yüzden notify: false yok.

5. adım, teslimat sırasında:

POST <callback_url> to {"card": {"v": 1, "title": "Order BST-10001", "state": "ok", "status_text": "Delivered", "icon": "package-check", "fields": []}, "seq": 4, "final": true}

final ile etkileşim kapatılır ve token artık çalışmaz.

Örnek 2: takipçi eylemleri olmayan bir işlem

Her akışın bir geçmişi yoktur. Sisteminize bir şey ileten tek bir alanı olan bir öğe için yalnızca bir yanıt gerekir:

{"card": {"v": 1, "title": "Filed", "state": "ok", "status_text": "Stored under project 4711", "icon": "clipboard-check", "fields": [{"label": "Case", "value": "4711"}]}, "final": true}

Burada final: true önemlidir: aksi halde bir daha hiçbir şey raporlamasanız bile etkileşim 90 gün boyunca geçerli bir token ile açık kalır.

Katalogdan ürün seçici

Şirket ürün kataloğunu yükledikten sonra, öğe ürün seçici bloğunu içerebilir. Kullanıcı buradan bir sepet oluşturur ve siz bunu, öğeyi oluşturan kişinin seçtiği anahtarın altında bir liste olarak alırsınız:

{"items": [{"artikelnummer": "5100110", "menge": 20}, {"artikelnummer": "5100111", "menge": 2}], "note": "…"}

Anahtar serbest olduğundan, sabit bir isim aramak yerine bu yapıya sahip ilk listeyi arayın. Göndermeden önce Skava, her bir sayının gerçekten o şirketin kataloğunda var olup olmadığını ve en fazla 50 ürün olduğunu kontrol eder. Kartta ürünler, ürün görseli, adı ve miktarı ile birlikte bir liste olarak görünür.

Test

  • Öğe editöründeki Ping, token ve veri olmadan çıplak bir HEAD gönderir. Herhangi bir yanıt verin; herhangi bir HTTP yanıtı erişilebilir sayılır.
  • Test isteği, örnek değerlerle gerçek bir çağrı başlatır, öğe hâlâ taslakken bile çalışır ve isteği, yanıtı ile kart doğrulayıcısının mesajlarını gösterir.
  • Yanındaki Önizleme sekmesinde: Yanıt JSON'ınızı yapıştırın, kontrol edin ve bitmiş kartı ile ipuçlarını görün. Sunucuda, üretimdekiyle aynı kodla kontrol edilir.
  • Örnek sunucu: Tam bir örnek tedarikçi api.skava.io adresinde çalışır ve yukarıda açıklanan her şeyi kullanır. Kaynağı, example_order_server/ altında depoda bulunur, yaklaşık 600 satırlık saf standart kütüphane kodudur ve kopyalanmak üzere tasarlanmıştır.

Bilmeniz gereken diğer hususlar

  • Kart, tamamen normal bir sohbet mesajıdır. Aramada görünür, alıntılanabilir ve geçmişte kalır.
  • Sistem göndericisi tarafından gönderilir, şirketinizin hesabı tarafından değil. Yine de öğeyi çalıştıran kişinin tarafında görünür ve kimin sisteminin yazdığını başlıkta belirtir.
  • Kimin çalıştırabileceği öğede tanımlanır: yalnızca şirket üyeleri veya öğeyle sohbet paylaşan dış kişiler de dahil. Şirketiniz sohbetten ayrıldığında izin kendiliğinden sona erer.
  • Tokeni süresi dolmuş bir API öğesi uyku halindedir: güncel uygulamalar menüde gizler ve yine de gönderilen çağrı sunucu tarafında reddedilir. Bir yönetici için yeni bir token saklar, bu da yayınlanmış bir arayüzde çalışır.

İlgili

Oluşturma ve yayınlama: Özel Öğeler: API arayüzleri. Arayüzler yerine doldurulabilir belgeler: Özel Öğeler: Belgeler.