Bu sayfa, bir şirketin arka ucunu Skava'ya bağlayan geliştiriciler içindir. Bir API öğesinin nasıl oluşturulup yayınlandığı Ö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.

Fikir tek cümlede: Skava alanınızı bilmez. Sadece bir formatı bilir: kart. İçeriğinin ne olacağını siz belirlersiniz; biz yalnızca şekli, boyutu ve güvenliğini kontrol ederiz. Bir malzeme siparişi buna örnektir; bir sonraki şirket kullanıcı geri bildirimlerini toplar, bir sonraki ise saha fotoğrafını kendi kayıtlarında saklar.

Akışa genel bakış

1. Bir şirket yöneticisi Skava'da bir API öğesi oluşturur: bir form ve arka ucunuzun adresi, metodu ile token'ı.
2. Sohbet içindeki biri formu doldurur ve gönderir.
3. Skava, arka uç sunucunuzu çağırır ve doldurulan değerleri JSON olarak gönderir.
4. Yanıtınız, sohbet penceresinde bir kart olarak görünür.
5. İsteğe bağlı olarak, daha sonra yeni durumları geri çağırma (callback) yoluyla bildirebilirsiniz. Her bildirim yeni bir kart oluşturur; önceki kart yerinde kalır.

Arka uç sunucunuz için gereksinimler

• HTTPS. Sadece https:// protokolü kullanılabilir; http kullanılamaz, adreste kimlik bilgileri bulunamaz ve en fazla 2000 karakter olabilir.
• Genel erişilebilir. Ana bilgisayar yalnızca genel IP adreslerine çözülmelidir. Yerel 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 adresine sabitler. Çağrı sırasında yapılan DNS değişikliği hiçbir etki yaratmaz.
• Yönlendirme yok. "Doğru" adrese yapılan 301 yönlendirmesi bir hata olarak sayılır. Son adresi hemen girin.
• Yanıt süresi. Zaman aşımı her öğe için yapılandırılabilir ve 30 saniye ile kesin olarak sınırlandırılmıştır. Daha uzun bir süreye ihtiyacınız varsa, 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.

Sizin tarafınıza 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 ise 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 ön eki şeklindedir. Jeton tarafımızda şifrelenmiş 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 ekledikleri yerlerde görünür:

{"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 onları kendiniz kullanmayın:

• locale: kullanıcının dil kodu. Cevabınızı bu dilde verin; metinlerinizi biz çevirmeziz.
• callback_url ve callback_token: bu tek etkileşim için geri çağırma, aşağıya bakın. Bunlar yalnızca çağrı bir sohbetten geldiğinde mevcuttur.

İsim, şirket, proje veya alt sohbet gibi bağlam alanları, elemanın çalıştırıldığı kanaldan türetilerek sunucu tarafından doldurulur. Manipüle edilmiş bir istemci burada farklı bir proje adı iddia edemez.

Yanıt: kart formatı

2xx yanıtı ve bir card nesnesi ile cevap verin. Sohbet içindeki 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): tamsayı 1. Metin olarak ("1") reddedilir. Bu olmadan yanıt bir kart olarak sayılmaz ve öğede yapılandırılan yanıt eşleştirmesi uygulanır.
• title: kartın başlığı.
• state: yalnızca renk ve ikon tonu, ok, pending, warn, error değerlerinden biri. Bilinmeyen bir değer ok olarak geri döner ve bir ipucu alırsınız.
• status_text: yorumlamadığımız serbest metin. Kartın üst kısmında yer alır ve aynı zamanda sohbet listesinde ve bir bildirimde görünen metindir.
• fields: label ve value içeren bir liste. En fazla 20 giriş, label 80 karakter, value 200, title ve status_text her biri 120 karakter. Çok uzun değerler kısaltılır, reddedilmez: bir sipariş detay yüzünden başarısız olmamalıdır.
• icon: aşağıya bakın.

Skava, metinlerin sohbeti ulaşmadan önce neler yapar: satır sonları ve kontrol karakterleri kaldırılır (sağdan sola bir karakter, bir tutarın görüntülenmesini tersine çevirebilir), ters tırnak işaretleri değiştirilir ve [SKAVA: ile başlayan her şey etkisiz hale getirilir. Sonuncusu, bir kart değerinin farklı bir sohbet öğesi olarak (örneğin bir ödeme isteği) okunmasını engeller.

Alanlardaki bağlantılar, HTML ve resimler ayarlanamaz. Bir sohbet güvenli bir ortamdır ve yabancı bir arka uçtan tıklanabilir bir adres, bir giriş sayfasını yeniden oluşturmak için bir davet olur.

Kullanıcının girdileri sunucuya aittir: ilk kartta görünürler ve bunları üzerine yazamazsınız. Sohbette bunlar, aslında gönderilen şeyin kaydıdır.

Semboller

icon ile kart, başlığa kendi işaretiyle sahip olur. İki yol:

Özelleştirilmiş kümeden bir ad: 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.

Ya da kendi SVG'niz bir dize olarak. Skava bundan yalnızca geometriyi alır (path, circle, ellipse, rect, line, polyline, polygon ve sayısal nitelikleriyle) ve kendi resmini oluşturur. Komut dosyaları, stiller, dış referanslar, foreignObject ve olay nitelikleri atılır; bir belge türü veya varlık reddedilmesine 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 belirlenir, bu nedenle bir simge bir kontrol olarak gizlenemez. 24x24 ızgarayla çalışın.

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

Geri çağırma: Daha sonraki durumların bildirilmesi

Çağrı callback_url ve callback_token içerir. Yeni durumları daha sonra bildirmek için bunları kullanın:

POST <callback_url> ile Authorization: Bearer <callback_token> ve Content-Type: application/json, 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 yanı sıra üç isteğe bağlı değer bulunmaktadır:

• seq: Kendi sayaçınız. Daha küçük veya eşit bir değere sahip bildirim atılır, böylece iki bildirim birbirinin önüne geçemez. seq olmadan son gelen kazanır.
• final: etkileşimi sonlandırır. Token geçersiz hale gelir ve başka kart görünmez. Takip soruları olmayan akışlarda first cevabında da kullanılabilir.
• notify: kartı sessizce göndermek, okunmamış sayısını ve bildirim oluşturmadan göndermek için false olarak ayarlayın. Kimseyi uyandırmaması gereken ara adımlar için uygundur. Bu ayar yoksa kart tam anlamıyla normal bir mesajdır.

Her rapor sohbetinde kendi kartını oluşturur, önceki rapor yerinde kalır. Böylece hangi durumun raporlandığı anlaşılır. Buradan bir öneri çıkar: sadece değişenleri gönderin. Sipariş numarasını, kalemleri ve toplamı dördüncü kez tekrar eden bir kart, okuyucu için sadece gürültüdür.

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

Yanıt vermeniz gereken cevaplar

• 200 ve {"result": "success", "updated": true, "seq": 3, "closed": false, "hints": []}. İpuçlarını okuyun: kısaltılan veya atlanan öğ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 hints içinde. Önce düzeltin.
• 400 bozuk JSON, 413 çok büyük, 429 çok fazla istek (geri sayım ile tekrar deneyin), 500 hatamız, daha sonra tekrar deneyin.

Örnek 1: Durum geçmişi olan bir sipariş

Adım 1, arka uç sunucunuza yapılan 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"}

Adım 2, anlık cevabı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 ikonu, durumu ve kullanıcının girdilerini gösteren bir kart içeriyor.

Adım 3, daha sonra sipariş hazırlanırken:

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

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

Adım 4, kargolama:

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.

Adım 5, teslimat:

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 gerektirmeyen bir eylem

Her akışın bir geçmişi yoktur. Bir öğeyi sisteminize ileten tek bir alanı olan bir eleman yalnızca bir yanıt gerektirir:

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

final: true burada önemlidir: aksi takdirde etkileşim, bir daha hiçbir şey bildirmeseniz bile geçerli bir jetonla 90 gün boyunca açık kalır.

Kataloğundaki ürün seçici

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

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

Anahtar ücretsiz olduğu için, sabit bir isim yerine bu yapıya sahip ilk listeyi arayın. Göndermeden önce Skava, her sayının o firmanın katalogunda gerçekten var olup olmadığını kontrol eder; en fazla 50 madde. Kartta maddeler, ürün görseli, ad ve miktar ile bir liste olarak görünür.

Test

• Öğe düzenleyicisindeki Ping, token ve veri içermeyen çıplak bir HEAD gönderir. Herhangi bir şeyle yanıt verin; herhangi bir HTTP yanıtı erişilebilir sayılır.
• Test isteği, öğe hala taslak olsa bile örnek değerlerle gerçek bir çağrı yapar ve isteği, yanıtı ve kart doğrulayıcısının mesajlarını gösterir.
• Yanındaki sekmedeki Önizleme: Yanıt JSON'unuzu yapıştırın, kontrol edin ve tamamlanmış kartı ile ipuçlarını görün. Bu, üretimdekiyle aynı kod kullanılarak sunucuda kontrol edilir.
• Örnek sunucu: api.skava.io adresinde yukarıda anlatılanların tamamını kullanan tam bir örnek tedarikçi çalışmaktadır. Kaynağı, kopyalanması amacıyla hazırlanmış yaklaşık 600 satırlık saf standart kütüphane kodu olan example_order_server/ dizininde yer almaktadır.

Bilmeniz gereken diğer hususlar

• Kart, tamamen normal bir sohbet mesajıdır. Aramalarda görünür, alıntılanabilir ve geçmişte saklanır.
• Bu mesaj, şirketinizin bir hesabı tarafından değil, sistem göndericisi tarafından gönderilir. Yine de öğeyi çalıştıran kişinin tarafında görünür ve başlıkta hangi sistemin yazdığı belirtilir.
• Kimlerin çalıştırabileceği öğede belirlenir: yalnızca şirket üyeleri veya sohbeti paylaşan dış kişiler de dahil. Şirketiniz sohbetten ayrıldığında izin otomatik olarak sona erer.
• Süresi dolmuş bir token'a sahip API öğesi pasif durumdadır ve bir yönetici yeni bir token kaydetene kadar menüde görünmez.

İlgili

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