Özel Öğeler: API

Bir API arayüzü, Skava'nın doldurulan değerlerini JSON olarak belirlediğiniz bir adrese (sizin arka uçunuza) gönderdiği bir formdur. Bu sayede Skava'yı kendi sistemlerinizle güvenle entegre edebilirsiniz.

Bir API arayüzü oluşturun

Bir arayüz, girdi alanlarından (bunlar JSON'u oluşturur), hedef adresten ve kimlik doğrulamadan oluşur.

1. Alanlar oluşturun: Her alanın bir JSON anahtarı vardır. Sağ tarafta, arka uçunuza tam olarak bu şekilde gönderilen JSON önizlemesini canlı olarak görürsünüz.
2. Adres (URL): Arka uçunuzun https:// adresi. Yalnızca HTTPS ve herkese açık adresler izinlidir (aşağıdaki Güvenlik bölümüne bakın).
3. Yöntem: POST (varsayılan), PUT, PATCH veya GET. GET kullanıldığında değerler gövdede gönderilmek yerine sorgu parametreleri olarak eklenir.
4. Kimlik doğrulama: Başlık adını (örn. Authorization) ve değer önekini (örn. Bearer ) belirleyin, ardından jetonu kaydedin. İsteğe bağlı olarak bir son kullanma tarihi belirleyin.
5. Yanıt alanları (isteğe bağlı): Arka uç yanıtındaki hangi değerlerin görüntüleneceğini yol ile tanımlayın: örn. order.id veya items[0].sku.
6. Ping ve Test Request ile kontrol edin, ardından Release yapın.

Token'ı güvenli bir şekilde saklayın

Token şifreli olarak saklanır ve istemcilere asla geri döndürülmez: uygulama yalnızca bir tokenin ayarlanıp ayarlanmadığını ve ne zaman sona ereceğini gösterir. Gönderim sırasında Skava, bunu sunucu tarafında yapılandırılan başlığa ekler. Bir son kullanma tarihi belirlediyseniz, Skava süre dolunca isteği reddeder ve tokeni yenilemenizi ister.

Test: Ping ve Test İsteği

• Ping: Hafif bir erişilebilirlik kontrolüdür. Sadece adresinizin yanıt verip vermediğini kontrol eder, bu sırada token veya form verisi göndermez. Erişilebilirliği, durumu ve yanıt süresini gösterir. İlk adım olarak idealdir.
• Test İsteği: gerçek deneme çalışması: adresinize token dahil örnek verileri gönderir ve hem tam yanıtı hem de çıkarılan yanıt alanlarını gösterir.

Yönetici olarak, yayına almadan önce entegrasyonu doğrulamak için taslak modundayken her ikisini de çalıştırabilirsiniz.

Taslak Oluştur ve Yayınla

Her arayüz taslak olarak başlar ve serbestçe düzenlenebilir. Her şey hazır olduğunda Yayınla ile yayınlarsınız.

Güvenlik

Ekip, yayınlanmış bir arayüzü nasıl kullanır

Bir arayüz yayınlandıktan sonra, tüm şirket üyeleri editör gerektirmeden doğrudan bir sohbetten onu tetikleyebilir. Ortak bir giriş veya ara bir iletişim kutusu yoktur: her yayınlanan öğe, onu sunan şirketin logosuyla birlikte artı menüsünde kendi adıyla yer alır.

1. Sohbette alttaki Artı simgesine dokunun ve istediğiniz öğeye, örneğin Malzeme siparişi öğesine dokunun.
2. Formu doldurun ve Gönder'e tıklayın.
3. Sonuç, sohbet içinde bir kart olarak görünür ve sohbeti kullanan herkes tarafından görüntülenebilir.

Yapay zekanın bir öğe oluşturmasına izin verin

Şirket yöneticisi olarak editörü kendiniz kullanmak zorunda değilsiniz. Skava asistanına sohbetten, örneğin "katalogum için adet ve teslimat adresi içeren bir sipariş formu oluştur" diyebilirsiniz. Asistan bunun bir taslak oluşturur, alanları daha sonra tek tek değiştirebilir ve yüklediğiniz ürün kataloğunuzu bilir: siparişler için ürün numarası için metin alanı yerine ürün seçici önerir.

Ayrıca şunları da belirleyebilir: uç nokta ve yöntem ile kitle ("sadece şirket üyeleri" veya "aynı sohbetteki dış kişiler de"). Kitle için doğrudan ayarlamak yerine önce sorar, çünkü dışarıdan birinin neyi çalıştırabileceğini o belirler.

Açıkça dokunmadığı şey: erişim belirteci. Asla istemez ve asla kabul etmez, çünkü sohbet mesajları saklanır. Bunu editörde kendiniz girersiniz, aksi halde hiçbir çağrı yapılmaz. Ve yayınlayamaz: son adım sizde kalır, böylece müşterilere kontrolsüz bir şey görünmez.

Kim çalıştırabilir

"Endpoint" sekmesi, bir öğeyi kimin kullanabileceğini belirtir. Varsayılan ayar, şirketinizin üyeleridir. İkinci ayar, öğeyi dışarıdaki kişilere açar; ancak bu, yalnızca şirketinizden birinin de bulunduğu sohbetlerde geçerlidir: Tam da bunun için tasarlanan durum, sizden sipariş veren müşteri. Şirketiniz sohbetten ayrıldığında, izin kendiliğinden sona erer.

Kendi kataloğunuzdaki ürünler

Kataloğunuzu yükledikten sonra, oluşturucu bir ürün seçici bloğu sunar. Bakım gerektiren seçenekler yoktur: liste sizin kataloğunuzdur. Sipariş veren kişi listede arama yapar, görseli, adı ve ürün numarasını görür; arka uç sisteminiz de ürün numarasını alır. Skava, kataloğunuzda olmayan bir numarayı reddeder. Miktar için yanına normal bir sayı alanı ekleyin.

Kartı kendiniz tanımlayın

Arka uç, kartın ne söyleyeceğine karar verir. Skava yalnızca biçim, boyut ve güvenliği kontrol eder, anlamı değil: ne sipariş durumlarını ne de alan adlarını bilir. Bunu yapmak için bir card nesnesiyle yanıt verin:

{"card": {"v": 1, "title": "Order 10001", "state": "pending", "status_text": "Being picked", "fields": [{"label": "Tracking number", "value": "DPD123456789"}]}}

• v 1 tam sayısı olmalıdır. Bu değer yoksa yanıt bir kart olarak sayılmaz ve öğede yapılandırılan yanıt eşlemesi uygulanır.
• state yalnızca renk ve ikondur: ok, pending, warn veya error. Anlam taşıyan her şey status_text alanına serbest metin olarak girilir.
• fields, etiket ve değer çiftlerinden oluşan en fazla 20 girdilik bir listedir. Çok uzun değerler reddedilmek yerine kısaltılır, böylece bir sipariş küçük bir detay yüzünden asla başarısız olmaz.

Kullanıcının girdileri sunucuya aittir: Arka uç ne gönderirse göndersün, bunlar olduğu gibi kalır. Bunlar, sohbette gerçekten gönderilenlerin kaydıdır.

Daha sonra durumu bildirme

Öğe çalıştığında Skava iki ek değer gönderir: callback_url ve callback_token. Daha sonra yeni bir durumu oraya bildirin ve sohbetin yanı sıra telefonda da yeni bir kart görünür, biri bakarken. Önceki kart kalır, böylece hangi durumun bildirildiği okunabilir. Yukarıdakiyle aynı card nesnesini, Authorization: Bearer <callback_token> başlığıyla POST yöntemiyle gönderin. Kartın yanına üç isteğe bağlı değer gider:

• seq: kendi sayacınız. Daha küçük veya eşit bir değere sahip olan raporlar atılır, böylece iki rapor birbirini geçemez.
• final: etkileşimi kapatır. Jeton geçersiz hale gelir ve kart kesinleşir.
• notify: Kartı sessizce göndermek, okunmamış sayacı ve bildirim oluşturmadan göndermek için false olarak ayarlayın. Kimseyi uyandırmaması gereken ara adımlar için idealdir. Bu ayar yapılmazsa kart tamamen normal bir mesaj olarak görünür.

Bir etkileşim en fazla 50 kart paylaşabilir. Aynı raporun iki kez gönderilmesi ikinci bir kart oluşturmaz.

Skava, kısaltma veya düşürme varsa 200 yanıtı ve hints listesi döndürür; kart kullanılamazsa 422 döndürür. Etkileşimler 90 gün boyunca raporları kabul eder.

Kartlar, Skava'nın sistem göndericisi tarafından paylaşılır; öğeyi çalıştıran kişi veya kendi şirketinizin bir hesabı tarafından değil. Hangi sistemin yazdığını kartın başlığı belirtir.

Kopyalanabilir tam bir örnek, depoda example_order_server/ altında bulunur ve api.skava.io adresinde çalışır.

İlgili

Doldurulabilir bir belge şablonu oluşturmak mı istiyorsunuz? Özel Öğeler: Belgeler sayfasına göz atın.

Sıkça Sorulan Sorular