Satravo · Entegrasyon Dökümanı

Mağazanızı Satravo'ya Bağlama

Bu belge, herhangi bir yazılıma sahip mağazaların Satravo WhatsApp otomasyonuna bağlanması için tek entegrasyon noktasını anlatır. Yazılımcınıza iletebilirsiniz.

1. Nasıl çalışır?

Mağazanızda bir olay olduğunda (sipariş, sepet, yeni müşteri…) tek bir HTTP POST isteği gönderirsiniz. Gerisini Satravo yapar: doğru otomasyonu tetikler, segmentleri günceller, geliri ilişkilendirir. Dilinizin veya altyapınızın önemi yoktur — HTTP çağrısı yapabilen her sistem bağlanır.

2. Uç nokta ve kimlik doğrulama

POST https://satravo.com/api/v1/events

Her istekte iki başlık gönderilir:

Authorization: Bearer <API_ANAHTARINIZ>
Content-Type: application/json

API anahtarınızı Satravo panelinde Ayarlar → Her Mağazaya Bağlanır kartından alırsınız (sat_ ile başlar). Gizli tutun; sunucu tarafında saklayın.

3. Hızlı başlangıç

Tek bir yardımcı fonksiyon yazın, tüm olaylarda kullanın:

<?php
function satravo_gonder($type, $data) {
  $ch = curl_init("https://satravo.com/api/v1/events");
  curl_setopt_array($ch, [
    CURLOPT_POST => true,
    CURLOPT_RETURNTRANSFER => true,
    CURLOPT_HTTPHEADER => [
      "Authorization: Bearer " . SATRAVO_API_KEY, // <API_ANAHTARINIZ>
      "Content-Type: application/json",
    ],
    CURLOPT_POSTFIELDS => json_encode(["type" => $type, "data" => $data]),
  ]);
  $res = curl_exec($ch);
  curl_close($ch);
  return $res;
}

// Kullanım:
satravo_gonder("order.created", [
  "externalId" => (string) $siparis->id,
  "orderNumber" => "#" . $siparis->no,
  "totalCents"  => (int) round($siparis->toplam * 100),
  "contact"     => ["phone" => $musteri->telefon, "name" => $musteri->ad, "optIn" => true],
]);

4. Olaylar

Beş olay tipi vardır. Mağazanızda karşılık gelen an geldiğinde ilgili olayı gönderin.

order.createdSipariş oluştu

Ne zaman: Müşteri bir sipariş verdiğinde (ödeme tamamlandığında) çağır.

Tetiklediği: Sipariş onayı otomasyonu, gelir atama, sepet kapatma

Alan	Tip	Zorunlu	Açıklama
externalId	string	evet	Sitenizdeki benzersiz sipariş kimliği (idempotency anahtarı).
orderNumber	string	hayır	Müşteriye gösterilen sipariş no (ör. #4821).
totalCents	integer	evet	Toplam tutar KURUŞ cinsinden (149,90 TL → 14990).
currency	string	hayır	Para birimi kodu (TRY, USD…). Boşsa mağaza varsayılanı.
items	array	hayır	Ürünler: { title, quantity, priceCents } nesneleri.
contact	object	evet	contact bir nesnedir; alanları: phone (zorunlu, +90… E.164), name, email, optIn (bool — pazarlama izni), birthday (YYYY-MM-DD), tags (dizi).
createdAt	string	hayır	ISO 8601 tarih (boşsa şu an).

Örnek (cURL):

curl -X POST https://satravo.com/api/v1/events \
  -H "Authorization: Bearer <API_ANAHTARINIZ>" \
  -H "Content-Type: application/json" \
  -d '{
    "type": "order.created",
    "data": {
      "externalId": "SIPARIS-4821",
      "orderNumber": "#4821",
      "totalCents": 149900,
      "currency": "TRY",
      "items": [
        { "title": "Keten Gömlek", "quantity": 1, "priceCents": 99900 },
        { "title": "Kemer", "quantity": 1, "priceCents": 50000 }
      ],
      "contact": { "phone": "+905551112233", "name": "Elif Yılmaz", "email": "elif@mail.com", "optIn": true }
    }
  }'

Başarılı yanıt: { "ok": true, "orderId": "..." }

order.fulfilledSipariş kargolandı

Ne zaman: Sipariş kargoya verildiğinde çağır.

Tetiklediği: Kargo bildirimi + (birkaç gün sonra) değerlendirme isteği

Alan	Tip	Zorunlu	Açıklama
externalId	string	evet	İlgili siparişin kimliği (order.created ile aynı).
trackingNumber	string	hayır	Kargo takip numarası.
trackingUrl	string	hayır	Kargo takip linki.
carrier	string	hayır	Kargo firması (ör. Yurtiçi Kargo).

Örnek (cURL):

curl -X POST https://satravo.com/api/v1/events \
  -H "Authorization: Bearer <API_ANAHTARINIZ>" \
  -H "Content-Type: application/json" \
  -d '{
    "type": "order.fulfilled",
    "data": {
      "externalId": "SIPARIS-4821",
      "trackingNumber": "YK123456789",
      "carrier": "Yurtiçi Kargo",
      "trackingUrl": "https://www.yurticikargo.com/takip/YK123456789"
    }
  }'

Başarılı yanıt: { "ok": true }

checkout.upsertedSepet / ödeme başladı

Ne zaman: Müşteri ödeme adımına geldiğinde (sipariş tamamlanmadan) çağır. Tamamlanmazsa terk edilmiş sepet olur.

Tetiklediği: Terk edilmiş sepet kurtarma dizisi (1s → 24s → 72s)

Alan	Tip	Zorunlu	Açıklama
externalId	string	evet	Benzersiz sepet/checkout kimliği.
totalCents	integer	evet	Sepet tutarı kuruş cinsinden.
items	array	hayır	Sepetteki ürünler: { title, quantity, priceCents }.
recoveryUrl	string	hayır	Sepete geri dönüş linki (mesajda kullanılır).
contact	object	evet	contact bir nesnedir; alanları: phone (zorunlu, +90… E.164), name, email, optIn (bool — pazarlama izni), birthday (YYYY-MM-DD), tags (dizi).

Örnek (cURL):

curl -X POST https://satravo.com/api/v1/events \
  -H "Authorization: Bearer <API_ANAHTARINIZ>" \
  -H "Content-Type: application/json" \
  -d '{
    "type": "checkout.upserted",
    "data": {
      "externalId": "SEPET-9f2a",
      "totalCents": 149900,
      "recoveryUrl": "https://siteniz.com/sepet/9f2a",
      "items": [{ "title": "Keten Gömlek", "quantity": 1, "priceCents": 99900 }],
      "contact": { "phone": "+905551112233", "name": "Elif Yılmaz", "optIn": true }
    }
  }'

Başarılı yanıt: { "ok": true, "checkoutId": "..." }

contact.upsertedYeni müşteri / üye

Ne zaman: Yeni üye kaydı veya bülten aboneliği olduğunda çağır.

Tetiklediği: Hoş geldin otomasyonu (opt-in ise)

Alan	Tip	Zorunlu	Açıklama
phone	string	evet	Telefon, +90… (E.164) biçiminde.
name	string	hayır	Ad soyad.
email	string	hayır	E-posta.
optIn	boolean	hayır	Pazarlama izni verdiyse true — kampanya alabilmesi için gerekli.
birthday	string	hayır	Doğum günü YYYY-MM-DD (doğum günü otomasyonu için).
tags	array	hayır	Etiketler (segmentleme için), dize dizisi.

Örnek (cURL):

curl -X POST https://satravo.com/api/v1/events \
  -H "Authorization: Bearer <API_ANAHTARINIZ>" \
  -H "Content-Type: application/json" \
  -d '{
    "type": "contact.upserted",
    "data": {
      "phone": "+905551112233",
      "name": "Elif Yılmaz",
      "email": "elif@mail.com",
      "optIn": true,
      "birthday": "1994-05-12",
      "tags": ["vip", "istanbul"]
    }
  }'

Başarılı yanıt: { "ok": true, "contactId": "..." }

product.updatedÜrün güncellendi

Ne zaman: Ürün fiyatı veya stok durumu değiştiğinde çağır.

Tetiklediği: Stoğa girdi bildirimi (bekleyenlere) · fiyat düşüşü bildirimi

Alan	Tip	Zorunlu	Açıklama
externalId	string	hayır	Ürün kimliği (eşleştirme için önerilir).
title	string	evet	Ürün adı.
priceCents	integer	hayır	Güncel fiyat kuruş cinsinden.
inStock	boolean	hayır	Stokta mı? true/false.
url	string	hayır	Ürün sayfası linki.

Örnek (cURL):

curl -X POST https://satravo.com/api/v1/events \
  -H "Authorization: Bearer <API_ANAHTARINIZ>" \
  -H "Content-Type: application/json" \
  -d '{
    "type": "product.updated",
    "data": {
      "externalId": "URUN-552",
      "title": "Keten Gömlek",
      "priceCents": 79900,
      "inStock": true,
      "url": "https://siteniz.com/urun/keten-gomlek"
    }
  }'

Başarılı yanıt: { "ok": true, "productId": "..." }

5. Yanıt kodları

200	Başarılı — olay işlendi.
401	API anahtarı eksik veya geçersiz.
400	Eksik/hatalı alan (type veya data yok).
422	İşlenemedi (ör. geçersiz telefon).

6. Önemli notlar

Tutarlar kuruş cinsinden: Tüm *Cents alanları tam sayı ve kuruş (149,90 TL → 14990).
Telefon biçimi: Ülke koduyla, +905551112233. Türkiye için 05xx… de kabul edilir ve otomatik düzeltilir.
Tekrar güvenli (idempotent): Aynı externalId ile iki kez gönderilirse sipariş/sepet tekrarlanmaz. Ağ hatasında çekinmeden yeniden deneyin.
İzin (opt-in): Kampanya alabilmesi için kişinin optIn: true olması gerekir. İşlemsel mesajlar (sipariş onayı, kargo) izinden bağımsız gider.
Asenkron gönderin: İsteği arka planda (bloklamadan) yollayın; mağazanızın hızını etkilemesin.
Test: Satravo panelindeki Simülatör ile gerçek veri göndermeden önce akışları deneyebilirsiniz.