REST API Referansı | Cxperium Dokümantasyon

Kimlik Doğrulama

Tüm istekler https://api.cxperium.com adresine, /api/… yolu altında ve HTTPS üzerinden gönderilir. Her isteğe API anahtarınızı taşıyan apikey başlığını ekleyin.

ornek-istek.sh

curl https://api.cxperium.com/api/contacts?page=1&limit=10 \
  -H "apikey: $CX_API_KEY"

Anahtar oluşturma — panelde Ayarlar → Api Entegrasyonu ekranında Oluştur'a basın; Premium ve Enterprise planlarda kullanılabilir. Adım adım anlatım: API Oluşturma ve Bağlantı İşlemleri.
Postman koleksiyonu — aynı ekrandaki Koleksiyonu Görüntüle düğmesi, bu sayfadaki tüm uçları örnek gövdeleriyle içeren koleksiyonu verir.
Hesap başına tek anahtar — yeni anahtar oluşturulduğunda önceki anında geçersiz olur. Alt kullanıcı da Api Entegrasyonu ekranından anahtar oluşturabilir; bu işlem hesabın ortak anahtarını yeniler.
Anahtarı gizli tutun — anahtar hesabınızın tamamına erişir. Tarayıcıda çalışan koda ya da mobil uygulamaya gömmeyin; sunucunuzdan çağırın. Sızdığını düşünürseniz panelden yeniden oluşturun; eski anahtar geçersiz olur.

Geçersiz, eksik ya da planı uygun olmayan anahtar 401 döner:

401.json

{ "error": "Invalid API key!" }

Genel Kurallar

İstek ve yanıt biçimi tüm uçlarda aynıdır. Gövdeler JSON'dur (Content-Type: application/json); tek istisna dosya ekli talep oluşturma (multipart/form-data).

Yanıt zarfı

yanit.json

# Başarılı istek (200 / 201)
{ "status": 201, "success": true, "message": "OK", "data": { … } }

# Doğrulama hatası (400) — hangi alanın neden reddedildiği error/message içinde
{ "status": 400, "success": false, "error": "MEDIA_NOT_SUPPORTED_ON_CHANNEL", "message": "…" }

# Hız sınırı (429)
{ "error": "Too many requests, please slow down." }

Konu	Kural
Sayfalama	Liste uçlarında `page` (1'den başlar) ve `limit` sorgu parametreleri. Varsayılan sıralama `createdAt` azalan; `sort` parametresine JSON verebilirsiniz: `sort={"createdAt":-1}`.
Filtre	`filter` parametresi URL-kodlanmış JSON'dur: `filter={"phone":"9055"}`. Metin alanları büyük/küçük harf duyarsız "içerir" eşleşir; `tags` alanı dizi olarak verilebilir.
Kimlikler	Tüm `_id` değerleri 24 karakterlik hexadecimal string.
Telefon	Ülke kodlu, artı işareti ve boşluk olmadan: `905551112233`.
Tarihler	ISO 8601, UTC. Dışa aktarma uçlarında `date_type` (`TODAY`, `THIS_WEEK`, `THIS_MONTH`, `THIS_YEAR`) ya da `start` / `end` (`YYYY-MM-DD`).
Hız sınırı	IP başına dakikada 100 istek. Aşımda `429`; kalan kotayı `RateLimit` yanıt başlıklarından okuyabilirsiniz.
Gövde boyutu	Medya taşıyan uçlarda en fazla 10 MB.
Dil	İsteğe bağlı `language` başlığı (`TR`, `EN` …) yanıt mesajlarının dilini belirler.

Kişiler (Contacts)

Kişi tektir: telefon numarası kimliktir. Aynı numarayla ikinci bir oluşturma isteği yeni kayıt açmaz, mevcut kaydı günceller.

Uç nokta	Açıklama
GET`/api/contacts`	Sayfalı, filtreli liste. `filter={"userProfileName":"Ayşe"}` gibi.
GET`/api/contacts/phone/:phone`	Telefona göre tek kişi.
GET`/api/contacts/:id`	Kimliğe göre tek kişi.
POST`/api/contacts`	Kişi oluştur (varsa güncelle). Gövde aşağıda.
POST`/api/contacts/bulk`	Toplu oluştur: `{ "data": [ {…}, {…} ], "uniqueData": "phone" }`. `uniqueData` verilirse aynı değere sahip mevcut kayıtlar yeniden oluşturulmaz.
PUT`/api/contacts/:id`	Güncelle; yalnızca değişen alanları gönderin (`phone`, `userProfileName`, `email`, `language`, `tags`, `custom`).
PUT`/api/contacts`	Toplu etiket ata: `{ "contact_ids": ["…"], "tags": ["…"] }`.
PUT`/api/contacts/delete/:id`	Kişiyi sil.
PUT`/api/contacts/delete-many`	Koşula göre toplu sil: `{ "condition": [ { "column": "phone", "operation": "EQUAL", "value": "9055…" } ] }`. `operation`: `EQUAL`, `NOT_EQUAL`, `CONTAINS`.
PATCH`/api/contacts/anonymize/:phone`	Kişiyi anonimleştir (KVKK "unutulma" talepleri için).

POST /api/contacts

{
  "phone": "905551112233",          // zorunlu
  "userProfileName": "Ayşe Yılmaz", // zorunlu — panelde görünen ad
  "email": "ayse@ornek.com",
  "language": "TR",
  "tags": ["66201122334455667788990a"],
  "custom": { "musteriNo": "C-4821", "segment": "vip" }  // serbest özel alanlar; yeni anahtarlar panelde sütun olur
}

Etiketler

Kişi etiketleri ve talep etiketleri ayrı listelerdir.

Uç nokta	Açıklama
GET`/api/tags`	Kişi etiketlerini sayfalı listeler.
POST`/api/tags`	Kişi etiketi oluştur: `{ "name": "VIP", "color": "#ff0f30" }`.
GET`/api/ticket/tags`	Talep etiketlerini listeler.
POST`/api/ticket/tag`	Talep etiketi oluştur.

Mesaj Gönderimi

WhatsApp kuralı: müşteri size son 24 saat içinde yazdıysa serbest mesaj gönderebilirsiniz; aksi halde yalnızca Meta onaylı bir şablonla ulaşabilirsiniz. Uçlar bu iki duruma göre ayrılır.

Uç nokta	Açıklama
POST`/api/send-message`	Açık oturumdaki kişiye serbest mesaj. `type`: `TEXT`, `IMAGE`, `DOCUMENT`, `VIDEO`. Medyayı `link` (URL) ya da `media` (Base64) + `file_name` ile verin.
POST`/api/notification/send-single`	Tek kişiye onaylı şablonla bildirim (oturum penceresi gerekmez). Gövde Bildirimler bölümünde.
POST`/api/message/one-person`	Tek kişiye anket daveti: `{ "name": "…", "survey_id": "…", "phone": "9055…", "tags": [] }`.
POST`/api/message/bulk`	Koşula uyan kişilerden gönderim grubu oluşturur (henüz göndermez): `{ "name", "survey_id", "condition": [ { "column", "operation", "value" } ] }`.
POST`/api/message/send/:id`	Oluşturulan grubu gönderir. Gövde boş.
POST`/api/message/direct`	Tek kişiye, özel şablon parametreleriyle (`customNotification`) anında anket daveti.
POST`/api/message/basic-direct`	`direct` ile aynı; şablon alanları (`template_name`, `template_lang`, `bodyPayload`) gövdenin kökünde.
GET`/api/message`	Gönderim görevlerini listeler.
GET`/api/message/task/:taskId`	Bir gönderim görevinin durumu.

POST /api/send-message

# Metin
{ "type": "TEXT", "phone": "905551112233", "text": "Merhaba! Siparişiniz kargoya verildi." }

# Adresle görsel
{ "type": "IMAGE", "phone": "905551112233", "link": "https://ornek.com/kampanya.jpg", "text": "Eylül kampanyası" }

# Base64 ile belge
{ "type": "DOCUMENT", "phone": "905551112233", "media": "JVBERi0xLjcK…", "file_name": "fatura.pdf" }

Yanıt 201 ve gönderdiğiniz gövdeyi data içinde döndürür. Kanal medya desteklemiyorsa 400 ve MEDIA_NOT_SUPPORTED_ON_CHANNEL alırsınız.

Anketler

Anketler panelde tasarlanır; API ile listeler, sonuçları okur ve kişiye özel ön verili linkler üretirsiniz.

Uç nokta	Açıklama
GET`/api/survey/form`	Anketleri sayfalı listeler.
GET`/api/survey/pure-survey`	Sade liste (kimlik ve ad), sayfasız.
GET`/api/survey/form/:id`	Anket formu: sorular, seçenekler, akış.
GET`/api/statistic/:survey_id`	Anket sonuçları (oturumlar ve cevaplar), sayfalı.
GET`/api/survey/pre-start/:surveyForm_id`	Bu anket için üretilmiş ön verili linkleri listeler.
POST`/api/survey/pre-start/:surveyForm_id`	Ön verili kısa link üretir. Gövde serbest JSON'dur (`{ "orderNo": "12345", "segment": "vip" }`); alanlar anket akışında ve webhook'larda `preData` olarak gelir. Yanıtta `data` kısa linki taşır: `https://cxpe.net/pXXXXXXXX`.

Bildirimler (Şablon Mesajları)

Bildirim şeması, Meta'ya onaya gönderilen WhatsApp şablonunun Cxperium'daki karşılığıdır. Şema oluşturma, listeleme ve silme Professional ve üstü planlarda açıktır.

Uç nokta	Açıklama
POST`/api/notification/schema`	Şablon oluşturup Meta onayına gönderir. Zorunlu: `name`, `category` (`UTILITY`, `MARKETING`, `AUTHENTICATION`), `lang`. İsteğe bağlı: `headerOptions`, `bodyOptions`, `footerText`, `buttonOptions`, `carouselOptions`.
GET`/api/notification/schema`	Şablonları ve onay durumlarını listeler.
GET`/api/notification/schema/:id`	Tek şablon.
DELETE`/api/notification/schema/:templateName`	Şablonu siler.
POST`/api/notification/send-single`	Tek kişiye şablonla bildirim gönderir. Gövde aşağıda.
GET`/api/notification/form`	Bildirim gönderim görevlerini listeler.
GET`/api/notification/form/:taskId`	Bir görevin ayrıntısı.
GET`/api/notification/export`	Bildirim kayıtlarını Excel olarak dışa aktarır (`date_type` ya da `start`/`end`).
GET`/api/notification/notification-message-status/:id`	Bir bildirimin iletim durumu (gönderildi, teslim edildi, okundu, başarısız).

POST /api/notification/send-single

{
  "contact": { "phone": "905551112233" },
  "notification": {
    "template_name": "siparis_kargoda",     // Meta onaylı şablon adı
    "name": "Kargo bildirimi",              // görev adı (panelde görünür)
    "data": {
      "template_lang": "tr",
      "bodyPayload": ["Ayşe", "TR-48291"],  // {{1}}, {{2}} … sırasıyla
      "headerPayload": { "format": "IMAGE", "link": "https://ornek.com/kargo.jpg" },  // medyalı başlık varsa
      "buttonPayload": [ { "type": "QUICK_REPLY", "payload": "kargo_takip" } ]         // şablonda buton varsa
    }
  }
}

Gövdeyi şablonunuzun yapısına göre doldurun: değişkeni olmayan şablonda bodyPayload boş dizi, başlığı olmayan şablonda headerPayload verilmez. Toplu gönderim tamamlandığında NOTIFICATION_SENDING_COMPLETED webhook olayı gelir.

Talepler (Ticket)

Talep durumları NEW, OPEN, PENDING, CLOSED. Talep oluşturma dosya eklenebildiği için multipart/form-data kabul eder.

Uç nokta	Açıklama
GET`/api/ticket`	Sayfalı, filtreli, sıralı liste: `filter={"status":"NEW"}&sort={"createdAt":-1}`.
GET`/api/ticket/:_id`	Tek talep, yorumlarıyla.
GET`/api/ticket/task/:taskId`	Panelde görünen talep numarasına göre.
GET`/api/ticket/contact/:contactNumber`	Telefona göre kişinin talepleri.
GET`/api/ticket/contact-by-id/:_id`	Kişi kimliğine göre talepler.
GET`/api/ticket/assignee-count`	Temsilci başına açık talep sayıları.
GET`/api/last-answer/:id`	Talebin son cevabı.
POST`/api/ticket`	Talep oluştur (multipart). Alanlar: `subject`, `contactId`, `message` (zorunlu); `tags` (JSON dizi), `media` (bir ya da daha fazla dosya).
POST`/api/ticket/send-comment/user/:_id`	Talebe panel kullanıcısı adına yorum: `{ "message": "…" }`.
POST`/api/ticket/send-comment/phone/:_id/:phone`	Talebe kişiye WhatsApp'tan giden mesaj/yorum: `{ "message": "…" }`.
POST`/api/ticket/:_id/wa/:phone/comments`	Kişinin WhatsApp'tan gönderdiği yorumu talebe ekler (bot entegrasyonları için).
PATCH`/api/assignee-change/:_id/:type/:assigneeId`	Talebi bir kullanıcıya atar.

talep-olustur.sh

curl -X POST https://api.cxperium.com/api/ticket \
  -H "apikey: $CX_API_KEY" \
  -F "subject=Kargo gecikmesi" \
  -F "contactId=6612cc33dd44ee55ff667788" \
  -F "message=Siparişim 5 gündür elime ulaşmadı." \
  -F 'tags=["66201122334455667788990a"]' \
  -F "media=@fatura.pdf"

Oluşturma, durum ve atama değişiklikleri ile yorumlar için webhook olayları vardır: Talep olayları.

Canlı Sohbet

Canlı destek sohbetleri panelde temsilcilerin gördüğü kayıtlardır. API ile sohbet açabilir, mesaj gönderebilir, ekip ve durum değiştirebilirsiniz.

Uç nokta	Açıklama
POST`/api/chat`	Sohbet oluştur: `{ "contactId": "…", "message": "…", "teamId": "…" }` (yalnızca `contactId` zorunlu). Kişinin açık sohbeti varsa o döner.
GET`/api/chat`	Sohbetleri listeler. Atanmamış yeni sohbetler: `filter={"status":"NEW","assignee":{"exists":false}}`.
GET`/api/chat/active/:id`	Kişinin açık sohbeti var mı.
POST`/api/chat/send-message`	Kişiye mesaj gönderir, gerekirse sohbeti açar: `{ "message": "…", "contactId": "…" }`.
POST`/api/chat/send-message/:_id`	Var olan sohbete mesaj (`message` ve/veya `media`).
POST`/api/chat/send-message/phone/:_id`	Telefon üzerinden mesaj: `{ "phone": "9055…", "message": { "text": "…" } }`.
PATCH`/api/chat/team-change/:_id/:teamId`	Sohbeti başka ekibe taşır.
PATCH`/api/chat/status-change/:_id/:status`	Durumu değiştirir (`NEW`, `OPEN`, `PENDING`, `CLOSED`).
PUT`/api/chat/:_id/tags`	Sohbete etiket atar: `{ "tags": ["…"] }`.
GET`/api/chat/export`	Sohbet kayıtlarını dışa aktarır (`date_type` ya da `start`/`end`).
PUT`/api/chat/settings/timeout`	Oturum zaman aşımı ayarını günceller.
GET`/api/business-hours`	Çalışma saatleri; `/api/business-hours/:phone` belirli numara için.
GET`/api/teams`	Ekipleri listeler.
GET`/api/subuser`	Alt kullanıcıları (temsilcileri) listeler; `/api/subuser/:id` tek kayıt, `PUT` ile günceller (örn. `chatAssignmentThreshold`).

Sohbet açılış, mesaj, durum ve atama olayları için: Sohbet olayları.

Webhook Yönetimi

Webhook tanımlarını panelden ya da API'den yönetebilirsiniz; ikisi aynı kaydı görür. Gönderim Enterprise plana özeldir.

Uç nokta	Açıklama
POST`/api/webhook`	Oluştur ya da güncelle (adres eşleşirse günceller): `webhook_adress`, `webhook_time` (olay kodları), `access_survey` (anket kimlikleri ya da `["*"]`), `webhook_active`.
GET`/api/webhook`	Tanımlı webhook'ları listeler.
DELETE`/api/webhook`	Adrese göre siler: `{ "webhook_adress": "https://…" }`.

Olay kodları ve gönderilen alanlar: Webhook Referansı.

Asistan, Katalog, Pipeline ve Diğer

Chatbot entegrasyonlarının kullandığı asistan uçları, WhatsApp katalog/ürün mesajları ve Pipeline (satış hattı) yönetimi.

Yapay zekâ asistanı

Uç nokta	Açıklama
GET`/api/assistant/configuration`	Asistan yapılandırması.
GET`/api/assistant/intent`	Niyet (intent) listesi.
GET`/api/assistant/localization`	Yerelleştirme metinleri; `/:languageId` tek dil.
POST`/api/assistant/localization`	Toplu metin ekle: `{ "data": [ { "languageId", "key", "value" } ] }`.
POST`/api/assistant/session`	Kişi oturumu oluştur/güncelle: `{ "phone", "language", "data": [ { "message", "isLast" } ], "isActive" }`.
GET`/api/assistant/session`	Oturumlar; `/:phone` numaraya, `/api/assistant/session-id/:id` kimliğe göre.
POST`/api/assistant/report`	Asistan rapor kaydı: `{ "phone", "intentName", "message", "nlp" }`; `/api/assistant/bulk-report` toplu.
GET`/api/assistant/report`	Raporlar (`start`, `end`); `/export` Excel; `/session-without-ticket` aralıkta yazıp talebi olmayan numaralar.
POST`/api/assistant/shopping-carts`	Sepet kaydı: `{ "cartKey", "customerId", "productCode", "quantity", "unitPrice" }`; `PUT` günceller, `GET /:cartKey` okur.
PATCH`/api/assistant/stage/:id`	Bilgi tabanı (stage) güncelle; `/file/:fileId/status` dosya işleme durumunu günceller.
GET`/api/waba`	Hesabın WhatsApp numarası bilgileri.

Katalog ve ürün mesajları yalnızca Meta Cloud API

Uç nokta	Açıklama
GET`/api/catalog/catalogs`	Katalogları listeler; `POST` yeni katalog oluşturur.
GET`/api/catalog/products`	Ürünleri listeler; `POST` ekler, `DELETE /:productId` siler.
GET`/api/catalog/commerce-settings`	Sepet ve katalog görünürlüğü; `POST` ile güncellenir.
POST`/api/catalog/send/single-product`	Tek ürün mesajı; `/multi-product` çoklu ürün, `/catalog` katalog mesajı.

Pipeline (satış hattı)

Uç nokta	Açıklama
GET`/api/funnel/stages`	Aşamaları listeler; `POST` oluşturur, `PATCH /:id` günceller, `DELETE /:id` siler, `POST /:id/move-stage` sırasını değiştirir.
GET`/api/funnel/cards`	Aday kartlarını listeler; `POST` oluşturur, `PATCH /:id` günceller, `DELETE /:id` siler, `POST /:id/move-card` aşama değiştirir.
POST`/api/funnel/cards/search-by-custom-field`	Özel alana göre kart arar.
POST`/api/funnel/cards/:id/add-activity`	Aktivite ekler (`todo`, `call`, `mail`, `meeting`, `document`); `PATCH …/update-activity/:activityId`, `DELETE …/remove-activity`.
POST`/api/funnel/cards/:id/add-log`	Not/günlük ekler; `DELETE …/remove-log`. Benzer şekilde `add-follower`/`remove-follower` ve `add-attachment`/`remove-attachment`.

Pipeline'ın panel kullanımı için CRM Özellikleri → Pipeline makalesine bakın.

REST API Referansı.