Özel Öğeler: API

API arayüzü, doldurulan değerlerini Skava'nın JSON olarak sizin belirlediğiniz bir adrese (kendi arka ucunuza) gönderdiği bir formdur. Böylece Skava'yı kendi sistemlerinize güvenli biçimde bağlarsınız.

API arayüzü kurma

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

1. Alanları oluşturun: her alan bir JSON anahtarı alır. Sağda JSON önizlemesini canlı görürsünüz, arka ucunuza tam olarak bu şekilde gönderilir.
2. Adres (URL): arka ucunuzun https:// adresi. Yalnızca herkese açık HTTPS adreslerine izin verilir (aşağıdaki Güvenlik bölümüne bakın).
3. Yöntem: POST (varsayılan), PUT, PATCH veya GET. GET ile değerler gövdede gönderilmek yerine adrese parametre olarak eklenir.
4. Kimlik doğrulama: başlık adını (örneğin Authorization) ve değer önekini (örneğin Bearer ) belirleyin, ardından token'ı kaydedin. İsterseniz bir son kullanma tarihi de verin.
5. Yanıt alanları (isteğe bağlı): arka uç yanıtındaki hangi değerlerin gösterileceğini yol ile tanımlayın, örneğin order.id veya items[0].sku.
6. Ping ve Test Request ile kontrol edin, sonra Yayınla deyin.

Token'ı güvenle saklama

Token şifreli saklanır ve istemcilere asla geri verilmez: uygulama yalnızca bir token'ın tanımlı olup olmadığını ve ne zaman süresinin dolacağını gösterir. Gönderim sırasında Skava onu sunucu tarafında belirlediğiniz başlığa ekler. Bir son kullanma tarihi verdiyseniz, o tarihten sonra Skava çağrıyı reddeder ve token'ı yenilemenizi ister.

Test etme: Ping ve Test Request

• Ping hafif bir erişilebilirlik kontrolüdür. Yalnızca adresinizin yanıt verip vermediğini denetler ve bu sırada ne token ne de form verisi gönderir. Erişilebilirliği, durumu ve yanıt süresini gösterir. İlk adım olarak idealdir.
• Test Request gerçek denemedir: adresinize token dahil örnek veri gönderir ve size hem tam yanıtı hem de çıkarılan yanıt alanlarını gösterir.

Yönetici olarak her ikisini de arayüz henüz taslakken çalıştırıp bağlantıyı yayınlamadan önce kontrol edebilirsiniz.

Taslak ve yayınlama

Her arayüz önce bir taslaktır 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 şirketin tüm çalışanları onu doğrudan sohbetten çalıştırabilir, düzenleyiciye gerek kalmaz. Akış belge şablonlarındaki ile aynıdır: seç, doldur, gönder.

1. Sohbette aşağıdaki Artı'ya dokunun ve Özel Öğe'yi seçin.
2. Listeden istediğiniz şablonu ya da arayüzü seçin.
3. Formu doldurun ve Gönder'e basın.
4. Sonuç sohbette bir kart olarak görünür, sohbetteki herkes görebilir.

Öğeyi yapay zekâya kurdurun

Şirket yöneticisi olarak düzenleyiciyi kendiniz kullanmak zorunda değilsiniz. Sohbette Skava asistanına söyleyin, örneğin: “bana kataloğumdan miktar ve teslimat adresi içeren bir sipariş formu kur”. Bundan bir taslak oluşturur, sonrasında alanları tek tek değiştirebilir ve yüklediğiniz ürün kataloğunuzu bilir: siparişler için ürün numarasına metin alanı yerine ürün seçiciyi önerir.

Ayrıca ayarlayabildikleri: endpoint ve yöntem, bir de kullanıcı çevresi (“yalnızca şirket çalışanları” ya da “aynı sohbetteki dışarıdan kişiler de”). Kullanıcı çevresini kendiliğinden ayarlamak yerine önce sorar, çünkü bu, dışarıdan kimin bir şey çalıştırabileceğini belirler.

Kesinlikle dokunmadığı şey: erişim token'ı. Onu asla istemez ve asla kabul etmez, çünkü sohbet mesajları saklanır. Onu düzenleyicide kendiniz girersiniz, yoksa hiçbir çağrı gitmez. Ve yayınlayamaz: son adım sizde kalır, böylece müşterilere denetlenmemiş hiçbir şey görünmez.

Kimler çalıştırabilir

“Endpoint” sekmesi bir öğeyi kimlerin kullanabileceğini belirler. Varsayılan, şirketinizin çalışanlarıdır. İkinci ayar onu dışarıdan kişilere de açar, ama yalnızca şirketinizden birinin de bulunduğu bir sohbette, yani tam olarak amaçlandığı durumda: sizden sipariş veren müşteri. Şirketiniz sohbetten ayrıldığında bu yetki kendiliğinden sona erer.

Kendi kataloğunuzdan ürünler

Ürün kataloğunuzu yükledikten sonra düzenleyici bir ürün seçici bloğu sunar. Bakımını yapmanız gereken bir seçenek yoktur: liste, kataloğunuzun kendisidir. Sipariş veren kişi onda arama yapar, görseli, adı ve ürün numarasını görür, arka ucunuza ise ürün numarası ulaşır. Kataloğunuzda olmayan bir numarayı Skava reddeder. Miktar için yanına normal bir sayı alanı koyun.

Kartı kendiniz tanımlayın

Kartın ne söyleyeceğine arka ucunuz karar verir. Skava yalnızca biçimi, boyutu ve güvenliği denetler, anlamı asla: ne sipariş durumlarını bilir ne de alan adlarını. Bunun 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 tam sayı 1 olmalıdır. O olmadan yanıt kart sayılmaz ve öğede tanımlanmış yanıt eşlemesi geçerli olur.
• state yalnızca rengi ve simgeyi belirler: ok, pending, warn ya da error. Anlam taşıyan her şey serbest metin olarak status_text içine girer.
• fields, etiket ve değerden oluşan bir listedir, en fazla 20 kayıt. Fazla uzun değerler reddedilmek yerine kısaltılır, böylece bir sipariş asla ufak bir ayrıntı yüzünden başarısız olmaz.

Kullanıcının girdikleri sunucuya aittir: arka ucunuz ne gönderirse göndersin dokunulmadan kalır. Sohbette gerçekte neyin gönderildiğinin kaydı onlardır.

Durumu sonradan bildirme

Öğe çalıştığında Skava iki ek değer gönderir: callback_url ve callback_token. Oraya sonradan yeni bir durum bildirin, sohbette yeni bir kart belirir, biri bakarken telefonda da. Öncekisi yerinde kalır, böylece hangi durumun ne zaman bildirildiği okunabilir. Yukarıdaki card nesnesinin aynısını POST ile ve Authorization: Bearer <callback_token> başlığıyla gönderin. Kartın yanına üç isteğe bağlı değer eklenebilir:

• seq: kendi sayacınız. Daha küçük ya da eşit değerli bir bildirim yok sayılır, böylece iki bildirim birbirini geçemez.
• final: etkileşimi kapatır. Token geçersizleşir ve kart kesinleşir.
• notify: kartın sessizce yayınlanması için false yapın, okunmamış sayacı olmadan ve bildirim olmadan. Kimseyi uyandırmaması gereken ara adımlar için. Bu olmadan kart gayet normal bir mesajdır.

Bir etkileşim en fazla 50 kart yayınlayabilir. Aynı bildirimin iki kez gönderilmesi ikinci bir kart oluşturmaz.

Bir şey kısaltıldıysa ya da atıldıysa Skava 200 ve bir hints listesiyle yanıt verir, kart kullanılamaz durumdaysa 422 ile. Bir etkileşim 90 gün boyunca bildirim kabul eder.

Kartları Skava'nın sistem göndericisi yayınlar, öğeyi çalıştıran kişi değil ve kendi şirketinizden bir hesap da değil. Hangi sistemin yazdığı kartın başlığında belirtilir.

Kopyalanmaya hazır eksiksiz bir örnek depoda example_order_server/ altında bulunur ve api.skava.io adresinde çalışır.

İlgili

Bunun yerine doldurulabilir bir belge şablonu mu kurmak istiyorsunuz? Bakın: Özel Öğeler: Belgeler.

Sık sorulan sorular