Kendi API’nizi ekleme

Asistanın sizin verinizden cevap üretebilmesi için, kendi sisteminizin uç noktalarını araç olarak tanıtırsınız. Bu sayfa o bağlantıyı nasıl kuracağınızı anlatıyor.

Ön koşullar

Sorgulanacak veriyi döndüren bir API ucu — kendi CRM, ERP veya abone yönetim sisteminizde
Ucun dışarıdan erişilebilir olması (veya uygun ağ erişiminin sağlanmış olması)
Kimlik doğrulama yöntemi ve gerekli anahtar

Uç yoksa ne olurSisteminizde uygun bir API ucu yoksa önce onun geliştirilmesi gerekir. Bu, WiChat tarafında değil sizin yazılımınızda yapılacak bir iştir.

Adım 1 — Uç noktayı hazırlayın

Asistan için iyi bir uç nokta şu özelliklere sahiptir:

Özellik	Neden
Tek iş yapar	Bir uç bir soruyu cevaplasın; "her şeyi döndüren" uçlar asistanı şaşırtır
Az alan döndürür	Asistan gördüğü her alanı kullanabilir; fazlası sızma riskidir
Hızlı yanıt verir	Müşteri bekliyor; özellikle telefonda gecikme fark edilir
Net hata döndürür	Kayıt bulunamadığında bunu açıkça belirtsin

Örnek istek ve yanıt

istek

GET https://api.demo.local/siparis/durum?siparis_no=DM-10045
Authorization: Bearer sk_••••••••

yanıt

{
  "bulundu": true,
  "durum": "kargoya verildi",
  "teslim_tahmini": "2 iş günü",
  "takip_no": "TK000123456"
}

Kayıt bulunamadığında:

yanıt — bulunamadı

{
  "bulundu": false,
  "mesaj": "Bu numarayla bir sipariş bulunamadı."
}

Neden bu biçim iyiYanıt sade ve okunabilir. Asistan bulundu alanına bakarak ne diyeceğine karar verebilir; gereksiz müşteri bilgisi içermiyor.

Adım 2 — Kimlik doğrulama

Ucunuz herkese açık olmamalıdır. Yaygın yöntem, isteğin başlığında bir anahtar taşımaktır:

istek başlığı

Authorization: Bearer sk_••••••••

Anahtar yönetimiAnahtarı yalnızca araç tanımında saklayın; kod örneklerine, dokümanlara veya mesajlara yazmayın. Anahtarın yalnızca gereken uçlara erişimi olsun — tüm sisteminize erişen bir anahtar kullanmayın.

Adım 3 — Aracı tanımlayın

Uç noktanızı asistana tanıtırken şunları belirlersiniz:

Alan	Değer (örnek)
Araç adı	`siparis_durumu_getir`
Açıklama	"Sipariş numarasıyla siparişin durumunu, tahmini teslim tarihini ve kargo takip numarasını getirir."
Uç nokta	`https://api.demo.local/siparis/durum`
Yöntem	`GET`
Kimlik doğrulama	Başlıkta anahtar
Parametre	`siparis_no` → sorgu parametresi olarak gönderilir

Açıklamanın nasıl yazılacağı kritiktir — ayrıntı için tool calling rehberine bakın.

Adım 4 — Parametre eşleme

Asistanın konuşmadan çıkardığı değerin, uç noktanızda hangi alana gideceğini belirlersiniz.

Örnekte müşteri "DM-10045" yazdığında, asistan bunu siparis_no parametresi olarak tanır ve uç noktaya ?siparis_no=DM-10045 şeklinde gönderir.

Biçim farklılıklarıMüşteri numarayı boşluklu, küçük harfle veya eksik yazabilir. Uç noktanızın esnek davranması (veya akışta bir Koşul düğümüyle önceden doğrulama yapılması) hata oranını düşürür.

Adım 5 — Test

Ucu tek başına deneyin

Aracı tanımlamadan önce uç noktanızın doğru çalıştığını kendiniz test edin.

Asistana sorun

Kendi hesabınızdan ilgili soruyu sorun; asistanın aracı çağırdığını görün.

Bulunamama durumunu deneyin

Var olmayan bir numara verin; asistanın uydurmadan doğru cevap verdiğini doğrulayın.

Cevabın biçimini kontrol edin

Asistan ham veriyi olduğu gibi mi yapıştırıyor, yoksa doğal bir cümle mi kuruyor?

Sorun giderme

Belirti	Olası sebep	Ne yapmalı
Asistan aracı hiç çağırmıyor	Açıklama belirsiz	Açıklamayı ne zaman kullanılacağını da anlatacak şekilde netleştirin
Yanlış araç çağrılıyor	İki aracın açıklaması benzer	Açıklamaları birbirinden ayrışacak şekilde yazın
Araç çağrılıyor ama hata dönüyor	Kimlik doğrulama veya parametre sorunu	Ucu kendiniz aynı parametrelerle çağırıp karşılaştırın
Cevap çok teknik	Uç fazla ham alan döndürüyor	Yanıtı sadeleştirin, yalnızca gereken alanları bırakın
Yanıt geç geliyor	Uç yavaş	Ucu hızlandırın; telefonda gecikme belirgin hissedilir

Sonraki adımServis anahtarı ve webhook ile daha geniş entegrasyon için CRM/ERP entegrasyon rehberine bakın.