Bildirimler API

POST /v1/notifications

Sunucu anahtarı, kapsam notifications:send. Anahtar başına sınırlı. Idempotency-Key kabul eder.

{
  "target": { "externalIds": ["user_123", "user_456"] },
  "content": {
    "tr": {
      "title": "Siparişin yola çıktı",
      "body": "#48213 bugün kargoda. Uygulamadan takip et.",
      "url": "acme://orders/48213",
      "image": "https://cdn.acme.example/orders/48213.jpg",
      "actions": [{ "id": "track", "title": "Takip et" }, { "id": "help", "title": "Yardım", "url": "acme://support" }]
    },
    "en": { "title": "Your order is on its way", "body": "Order #48213 ships today." },
    "_default": "tr"
  },
  "data": { "screen": "order", "id": "48213" },
  "ttl": 86400,
  "collapseId": "order-48213",
  "priority": "high",
  "presentation": { "sound": "default", "badge": 1, "threadId": "orders", "icon": "https://cdn.acme.example/icon.png" },
  "bypass": { "quietHours": true }
}

target — tam olarak bir seçici

Seçici	Tip	Sınır
externalIds	string[]	1–1000
userIds	ObjectId[]	1–1000
subscriptionIds	ObjectId[]	1–1000
segment	segment düğümü	—
segmentId	bir kayıtlı segmentin ObjectId'si	—
all	true	—

Kullanıcılar bildirime açık, geçersiz olmayan tüm cihazlarına çözülür.

Diğer alanlar

Alan	Tip	Varsayılan	Notlar
content	içerik haritası	content / templateId / silent'ten biri	İçerik. Yer tutucu serbest.
templateId	ObjectId	—	Metin ve varsayılanlar bir şablondan; istekteki alanlar ezer
silent	boolean	false	Arka plan push'u, alert yok; content isteğe bağlı; web atlanır. Sessiz push
data	Record<string,string>	—	anahtar ≤ 64, değer ≤ 1024 karakter
ttl	int saniye	259200	0 – 2 419 200 (4 hafta)
collapseId	string ≤ 64	—
priority	"high" | "normal"	"high"	teslimat aciliyeti (APNs 10/5, FCM high/normal)
presentation	nesne	—	sound, badge (0–99999), threadId, icon, interruptionLevel (passive|active|time-sensitive|critical), relevanceScore (0–1), channelId
bypass	{ frequencyCap?, quietHours? }	—	Teslimat kuralları

Yanıt 202 Accepted

{ "id": "66f3…", "status": "sending" }

id bir kampanya kimliğidir (transactional: true). Sonuç için GET /v1/campaigns/:id/stats'ı yoklayın ya da webhook'lara abone olun.

Hatalar

Durum	Kod	Neden
401	unauthorized	eksik/geçersiz anahtar
403	forbidden	public anahtar ya da notifications:send eksik
422	invalid_body	details[]'e bakın — en sık target (sıfır ya da iki seçici) ya da content._default
429	rate_limited	anahtar başına sınır
409 / 422	idempotency_in_progress / idempotency_key_reused	Idempotency
503	database_unavailable	Mongo kapalı

Örnekler

Herkese, sessiz rozet yenileme (yalnızca rozet, ses yok):

{ "target": { "all": true }, "content": { "tr": { "title": "Senkron", "body": "Yenileniyor" }, "_default": "tr" },
  "presentation": { "sound": "none", "badge": 0 }, "priority": "normal", "bypass": { "frequencyCap": true, "quietHours": true } }

Bir segment:

{ "target": { "segment": { "and": [ { "field": "tags.plan", "op": "eq", "value": "trial" }, { "field": "createdAt", "op": "lt", "value": "-13d" } ] } },
  "content": { "tr": { "title": "Deneme süren yarın bitiyor", "body": "Serini koru — bugün yükselt.", "url": "acme://upgrade" }, "_default": "tr" } }