Sinyal gönderme

ERP’niz, e-ticaret siteniz ya da tablo eşitlemeniz ürün ve kampanya olaylarını KolayMarketing’e gönderir. KolayMarketing bunlardan içerik fırsatları (sinyal) çıkarır: SKT’si yaklaşan ürün, stoğu biten ürün, başlayan kampanya gibi. Bu çağrı hiçbir şey yazmaz ya da yayınlamaz; sinyalleri ekibiniz Sinyaller ekranında görür ve kullanıp kullanmamaya karar verir.

POST https://api.kolaymarketing.com/v1/signals/ingest
Authorization: Bearer km_pk_…
Content-Type: application/json

Anahtarın signals_ingest yetkisi olmalı.
Sinyaller hesabınızda açık olmalı; kapalıysa 403 forbidden döner.
Başarılı istek 202 döner.

Gövde

{
  "events": [
    {
      "id": "erp-2026-11-09-000123",
      "kind": "product.updated",
      "occurred_at": "2026-11-09T08:30:00Z",
      "product": {
        "sku": "KAM-4K-01",
        "name": "4K Dış Mekân Kamerası",
        "qty": 12,
        "expiry_date": null,
        "price": 2499.9,
        "sales_30d": 41,
        "image_url": "https://cdn.firma.com/kam-4k-01.jpg"
      }
    },
    {
      "id": "kampanya-kis-2026",
      "kind": "campaign.updated",
      "occurred_at": "2026-11-09T08:30:00Z",
      "campaign": { "id": "kis-2026", "name": "Kış İndirimi", "starts_on": "2026-12-01", "ends_on": "2026-12-31" }
    }
  ]
}

Bir istekte 1-200 olay gönderilebilir. Olaylardan biri geçersizse hiçbiri kaydedilmez: yanıt 400 invalid_events döner ve mesaj hatalı olayların sırasını (#0, #3 …) ve nedenini söyler.

Ortak alanlar

Alan	Kural
`id`	kaynağınızın olay kimliği, 1-200 karakter, boşluksuz. Aynı `id` ikinci kez gelirse yinelenen sayılır
`kind`	`product.updated` ya da `campaign.updated`
`occurred_at`	ISO 8601 tarih-saat

`product.updated`

Alan	Kural
`sku`	zorunlu, 1-100 karakter, boşluksuz
`name`	zorunlu, en fazla 200 karakter
`qty`	stok adedi: 0 ya da pozitif tam sayı; bilinmiyorsa `null`
`expiry_date`	son kullanma tarihi `YYYY-AA-GG`; yoksa `null`
`price`	birim fiyat, 0’dan büyük; bilinmiyorsa `null`. `0` gönderilirse reddedilir
`sales_30d`	son 30 gün satış adedi; ölçülmediyse `null`
`image_url`	`https` adresi ya da `null` (isteğe bağlı)

`campaign.updated`

Alan	Kural
`id`	kampanya kimliği, 1-100 karakter, boşluksuz
`name`	zorunlu, en fazla 200 karakter
`starts_on`	zorunlu, `YYYY-AA-GG`
`ends_on`	`YYYY-AA-GG` ya da `null`; başlangıçtan önce olamaz

Bilinmeyen değer null’dır, 0 değil. Stok adedini bilmiyorsanız qty: null gönderin; 0 “stok bitti” demektir ve buna göre sinyal üretilir.

Yukarıda olmayan alanlar (müşteri adı, telefon …) kaydedilmeden atılır.

Yanıt

{ "accepted": 2, "duplicates": 0, "stale": 0, "signals": 1 }

Alan	Anlamı
`accepted`	kaydedilen olay sayısı
`duplicates`	daha önce aynı `id` ile gelmiş, atlanan olaylar
`stale`	kayıtlı durumdan daha eski olaylar; saklanır ama uygulanmaz
`signals`	bu istekle oluşan yeni sinyal sayısı

Ağ hatasında aynı gövdeyi yeniden gönderebilirsiniz: aynı id’ler yinelenen sayılır, iki kez işlenmez.

Hatalar

HTTP	`code`	Anlamı
400	`invalid_body`	`events` boş ya da dizi değil
400	`too_many_events`	200’den fazla olay
400	`invalid_events`	en az bir olay geçersiz; hiçbiri kaydedilmedi
401	`unauthorized`	anahtar geçersiz ya da iptal edilmiş
403	`forbidden`	`signals_ingest` yetkisi yok ya da Sinyaller kapalı
409	`source_inactive`	bu veri kaynağı ekibiniz tarafından durdurulmuş
429	`rate_limited`	dakikada 20 istek sınırı aşıldı

Hata biçimi Partner API ile aynıdır.