REST API

REST API, kendi sistemlerinizin çalışma alanınızla çalışmasını sağlar: kişileri bir CRM ile eşitleyin, mağazanızdan olay gönderin, müşterilere başka bir araçtan cevap verin ya da konuşmaları otomatik kapatın.

• Temel adres: https://app.shopxare.com/api/v1
• Biçim: JSON gönderilir, JSON döner. Zamanlar UTC, ISO 8601.
• Makine okunur referans: /api/v1/openapi.json (OpenAPI 3.1; Postman, Insomnia ya da bir kod üreticisine aktarabilirsiniz).

Token'lar

Token'ı Ayarlar → API bölümünde oluşturun (sahipler ve yöneticiler ya da rolünde geliştirici izni olan herkes). Şifrenizi onaylar, bir ad, yetkiler ve geçerlilik süresi seçersiniz; token yalnızca bir kez gösterilir — o anda kopyalayın, biz sadece özetini (hash) saklarız.

Her istekte gönderin:

curl https://app.shopxare.com/api/v1/me \
  -H "Authorization: Bearer sxa_…"

Token, onu oluşturan ekip arkadaşı adına çalışır. O kişinin rolünün izin verdiğinden fazlasını asla yapamaz; kişi çalışma alanından ayrılır ya da devre dışı bırakılırsa token çalışmayı bırakır. Token'ı aynı yerden istediğiniz an iptal edebilirsiniz.

Uç noktalar

Müşteriye cevap verme

curl -X POST https://app.shopxare.com/api/v1/conversations/01K7…/messages \
  -H "Authorization: Bearer sxa_…" \
  -H "Content-Type: application/json" \
  -H "Idempotency-Key: siparis-1042-kargoda" \
  -d '{"body": "Siparişiniz kargoya verildi 📦"}'

Cevap müşteriye konuşmanın kanalından — Messenger, e-posta ya da Telegram — gelen kutusundan yazılmış gibi ulaşır. İç not için "type": "note" kullanın. Aynı Idempotency-Key ile tekrarlanan istek ikinci kez göndermez, ilk mesajı döner (201 yerine 200).

Kapatma veya atama

curl -X PATCH https://app.shopxare.com/api/v1/conversations/01K7… \
  -H "Authorization: Bearer sxa_…" -H "Content-Type: application/json" \
  -d '{"status": "closed"}'

assignee_id (/teammates'ten bir ekip arkadaşı kimliği ya da null), team_id, priority (normal, high) ve status (open, snoozed_until ile snoozed, closed) değiştirilebilir. Her değişiklik gelen kutusundaki gibi konuşmada görünür ve iş akışları normal çalışır.

Kişi oluşturma veya güncelleme

curl -X POST https://app.shopxare.com/api/v1/contacts \
  -H "Authorization: Bearer sxa_…" -H "Content-Type: application/json" \
  -d '{"email": "[email protected]", "name": "Lena", "external_id": "user-7", "attributes": {"plan": "pro"}}'

Birini GET /contacts?email=… ya da ?external_id=… ile bulun. PATCH isteğinde yalnızca gönderdiğiniz alanlar değişir; attributes birleştirilir, null verilen anahtar silinir. external_id, kimlik doğrulamada Messenger'a verdiğiniz kullanıcı kimliğiyle aynıdır; API ve Messenger aynı kişiyi görür.

Olay kaydetme

curl -X POST https://app.shopxare.com/api/v1/contacts/01K7…/events \
  -H "Authorization: Bearer sxa_…" -H "Content-Type: application/json" \
  -d '{"name": "order_placed", "meta": {"order_id": "A-1042", "total": 59.9}}'

JavaScript API'deki Shopxare('trackEvent', …) ile aynıdır, ama sunucunuzdan.

Sayfalama

Listeler en yeniden eskiye {"object": "list", "data": [...], "next_cursor": "…"} döner. next_cursor değerini null olana kadar cursor olarak geri gönderin. limit 1–100 arasıdır (varsayılan 25). Değişiklikleri eşitlemek için updated_since ile filtreleyin.

Mesajlar eskiden yeniye listelenir: has_more true olduğu sürece aldığınız son id değerini after_id olarak gönderin.

Hatalar

Hatalar hep aynı biçimdedir:

{ "error": { "code": "validation_failed", "message": "…", "fields": { "email": ["…"] } } }

İstek sınırları

İstekler token başına dakikalık sayılır; sınır paketinizden gelir ve Ayarlar → API bölümünde gösterilir. Her cevapta X-RateLimit-Limit ve X-RateLimit-Remaining başlıkları bulunur.

Değişikliklerden haberdar olma

API sormak ve değiştirmek içindir. Bir şey olduğunda — yeni konuşma, cevap, kapanan talep — haber almak için webhook'ları kullanın.