YusralAPI ve MCP
Kendi yazılımınızın verilerinizle çalışmasını sağlama ya da bir yapay zeka asistanı bağlama.
API ve MCP Professional aboneliğine dahildir.
Başka yazılımların Yusral ile çalışmasının iki yolu var:
- API: kendi yazılımınız ya da bir geliştiricinin kurduğu bir entegrasyon için; örneğin web sitenizden dosya oluşturmak ya da bir muhasebe programından firmaları güncellemek.
- MCP: Claude veya ChatGPT gibi yapay zeka asistanları için. Asistanlar siz istediğinizde dosyalarınızı, görevlerinizi ve müşterilerinizi okuyup güncelleyebilir, sizin kontrol edip göndereceğiniz yanıtlar hazırlayabilir.
Her şey Ayarlar > Entegrasyonlar > API altında bulunur.
Yapay zeka asistanı bağlama (MCP)
- Yapay zeka asistanı bağlama altındaki MCP adresi değerini kopyalayın. Adres şudur:
https://app.yusral.com/mcp. - Adresi yapay zeka asistanınıza bağlayıcı (connector) olarak ekleyin.
- Asistan sizden Yusral hesabınızla giriş yapmanızı ve erişim vermenizi ister. Ekranda uygulamanın neler yapabileceği yazar: dosyalarınızı, görevlerinizi, notlarınızı, firmalarınızı ve kişilerinizi okuma, oluşturma ve değiştirme; ayrıca sizin kontrol edip kendiniz göndereceğiniz bir yanıt önerme. Bunu okuyun ve Erişim izni ver düğmesine tıklayın.
Bunun için bir API anahtarına ihtiyacınız yoktur. Bağlantı, onu onaylayan kişinin adına kaydedilir ve o kişinin yetkileriyle çalışır: sizin göremediğiniz veya yapamadığınız şeyi asistan da yapamaz. Birden fazla organizasyonun üyesiyseniz erişim tüm organizasyonlarınız için geçerlidir ve asistan önce hangisinde çalışacağını sorar.
Bir asistan neler yapabilir
| Araç | Ne yapar |
|---|---|
find_cases | Serbest metin ve durum veya sorumlu gibi filtrelerle dosya arar |
get_case | Tek bir dosyayı, en son notları, mesajları ve tüm görevleriyle okur |
find_tasks | Tüm organizasyonda görev arar |
search_everything | Dosyalarda, firmalarda, kişilerde ve görevlerde aynı anda, notların ve mesajların metninde de arar |
get_customer | Tek bir firmayı kişileri ve en son dosyalarıyla ya da tek bir kişiyi firmalarıyla okur |
get_vocabulary | Organizasyonunuzun durumları, öncelikleri, türleri, kategorileri, kaynakları ve üyeleri |
create_case | Bir dosya açar |
update_case | Bir dosyayı değiştirir; her değişiklik sizin adınıza geçmişe kaydedilir |
add_case_note | Yalnızca çalışma arkadaşlarına açık bir iç not ekler |
draft_reply | Müşteriye bir yanıt hazırlar, aşağıya bakın |
create_task | Bir dosyaya bağlı ya da bağımsız bir görev oluşturur |
update_task | Bir görevi değiştirir veya tamamlandı olarak işaretler |
save_relation | Bir firma ekler veya değiştirir |
save_contact | Bir kişi ekler veya değiştirir ve firmalara bağlar |
list_organisations | Organizasyonlarınızı gösterir, yalnızca birden fazla organizasyonun üyesiyseniz |
Bir asistanın yapamadıkları: silme, birleştirme, ayarları, üyeleri veya faturalamayı değiştirme ya da kendi başına e-posta gönderme.
Asistanın hazırladığı yanıtlar
Asistandan bir müşteriye yanıt vermesini isterseniz bir taslak yazar. Müşteriye hiçbir şey gitmez. Taslak, dosyada Yaz altında Yapay zeka asistanınızdan taslak olarak bekler. Okuyun, düzenleyiciye koymak için Kullan seçeneğini seçin, gerektiği yerde değiştirin ve kendiniz gönderin. Sil ile taslağı atarsınız. Aynı dosya için yeni bir taslak öncekinin yerini alır.
Erişimi Profil > Bağlı uygulamalar bölümünden kaldırırsınız, bkz. Outlook takvimi ve bağlı uygulamalar.
API anahtarı oluşturma
Anahtarı Sahip veya Yönetici olarak oluşturursunuz.
- API anahtarları altında Yeni anahtar düğmesine tıklayın.
- Anahtara ne için kullanıldığını anlatan bir Ad verin, örneğin Exact entegrasyonu.
- Geçerlilik süresi seçin: 30 gün sonra, 90 gün sonra (varsayılan), Bir yıl sonra veya Süresi dolmaz. Süresi dolmaz seçeneğini yalnızca sürekli çalışması gereken bir entegrasyon için seçin.
- Yetkiler altında anahtarın neleri yapabileceğini işaretleyin. Gerekenden fazlasını vermeyin.
- Anahtar oluştur düğmesine tıklayın ve anahtarı hemen kopyalayın. Anahtarı yalnızca şimdi görürsünüz. Kaybettiniz mi? Yeni bir anahtar oluşturun ve eskisini iptal edin.
Bir anahtara şu yetkileri verebilirsiniz:
| Bölüm | Yetkiler | API'de |
|---|---|---|
| Dosyalar | Görüntüle, Ekip arkadaşlarının dosyalar kayıtlarını da görüntüle, Oluştur, Düzenle | ticket:read, ticket:readAll, ticket:create, ticket:update |
| Görevler | Görüntüle, Ekip arkadaşlarının görevlerini de görüntüle, Oluştur, Düzenle | task:read, task:readAll, task:create, task:update |
| Notlar | Görüntüle, Oluştur | note:read, note:create |
| Firmalar | Görüntüle, Oluştur, Düzenle | company:read, company:create, company:update |
| Kişiler | Görüntüle, Oluştur, Düzenle | contact:read, contact:create, contact:update |
Bir anahtar, onu oluşturan kişinin yetkileriyle çalışır
Bir anahtar hiçbir zaman onu oluşturan çalışma arkadaşından fazlasını yapamaz. O kişinin yetkileri azalırsa anahtar da bir sonraki istekten itibaren daha az yetkiyle çalışır. Kişi organizasyondan ayrılırsa Oluşturan sütununda Eski üye yazar. Bu yüzden kalıcı entegrasyonların anahtarlarını organizasyonda kalacak bir hesapla oluşturun.
Anahtarlarınızı yönetme
Listede her anahtar için Anahtar, Erişim, anahtarı kimin oluşturduğu (Oluşturan), en son ne zaman kullanıldığı (Son kullanım) ve Durum görünür: Aktif, İptal edildi veya Süresi doldu.
- İptal et: anahtar bir sonraki istekten itibaren çalışmaz. Bu geri alınamaz. Anahtar listede kalır, böylece en son ne zaman kullanıldığını yine görürsünüz.
- Sil: anahtar, en son kullanıldığı tarihle birlikte listeden kaybolur. Bundan sonra anahtarın ne yaptığını geriye dönük olarak inceleyemezsiniz.
Geliştiriciler için
Her uç noktayı ve her alanı içeren tam başvuru belgesi API belgelerinde bulunur. Orada bir isteği hemen deneyebilirsiniz. OpenAPI belirtimini Postman'e veya Insomnia'ya aktarabilir ya da bir istemci oluşturmak için kullanabilirsiniz. İkisini de API kullanımı altında, Temel URL ile birlikte bulursunuz: https://app.yusral.com/api/v1.
| Uç nokta | Ne yapar |
|---|---|
GET /me | Organizasyonu, aboneliği ve anahtarınızın gerçekte sahip olduğu yetkileri gösterir |
GET /vocabulary | Tüm geçerli durumlar, öncelikler, türler, kategoriler, kaynaklar ve üyeler |
GET, POST /cases | Dosyaları listeler veya oluşturur |
GET, PATCH /cases/{id} | Tek bir dosyayı okur veya değiştirir |
GET /cases/{id}/messages | Bir dosyanın e-postaları |
GET, POST /cases/{id}/notes | Bir dosyanın notlarını okur veya not ekler |
GET /cases/{id}/tasks | Bir dosyanın görevleri |
GET, POST /tasks | Görevleri listeler veya oluşturur |
GET, PATCH /tasks/{id} | Tek bir görevi okur veya değiştirir |
GET, POST /relations | Firmaları listeler veya oluşturur |
GET, PATCH /relations/{id} | Tek bir firmayı okur veya değiştirir |
GET, POST /contacts | Kişileri listeler veya oluşturur |
GET, PATCH /contacts/{id} | Tek bir kişiyi okur veya değiştirir |
Önceden bilmek isteyeceğiniz birkaç şey:
Kimlik doğrulama. Anahtarı Authorization: Bearer <anahtar> ya da x-api-key: <anahtar> olarak gönderin. GET /api/v1/me ile başlayın: bu, anahtarınızın gerçekte neler yapabildiğini gösterir.
Hata vermeyen kısa bir liste. ticket:readAll yetkisi olmayan bir anahtar, yalnızca onu oluşturan çalışma arkadaşına atanmış dosyaları görür. O çalışma arkadaşının rolünde Ekip arkadaşlarının dosyalar kayıtlarını da görüntüle yetkisi yoksa da durum aynıdır, bkz. Yalnızca kendi işleri. Aynısı task:readAll ile görevler için de geçerlidir. GET /api/v1/me içindeki restrictedToOwnCases bunun geçerli olup olmadığını söyler.
Firmalar ve kişiler. Yeni bir firma uygulamadakiyle aynı kontrollerden geçer: bir ad ve bir e-posta alan adı organizasyonunuzda yalnızca bir kez bulunabilir, bireysel bir müşterinin KDV numarası veya e-posta alan adı olmaz. Bkz. Firmalar ve kişiler.
Kimlik yerine adlar. Yazarken bir durumu, önceliği veya türü bir insanın gördüğü haliyle verebilirsiniz, örneğin "status": "In afwachting". GET /api/v1/vocabulary tüm geçerli değerleri tek seferde verir.
Sayfalama. Her liste bir imleçle çalışır: nextCursor değerini, null olana kadar cursor olarak geri gönderin.
Güvenle yeniden deneme. Bir POST isteğinde Idempotency-Key gönderin. Bir zaman aşımından sonra yeniden denerseniz hiçbir şey iki kez oluşturulmaz.
Çok hızlı olmasın. Art arda çok fazla istek gönderirseniz 429 yanıtı alırsınız; Retry-After kaç saniye beklemeniz gerektiğini söyler.
Bildirimsiz içe aktarma. Bir içe aktarmada binlerce dosya veya görev atıyorsanız "notify": false gönderin. Yoksa sorumlu her dosya için bir bildirim ve bir e-posta alır.