KolayMarketing Geliştiricikolaymarketing.com

KolayMarketing Partner API

Bu belge, kendi panelinde bir “Sosyal Medya” modülü gösterecek proje ekipleri içindir. API üzerinden bir workspace’in içeriklerini, takvimini, onaylarını ve yayın arşivini gösterebilir, bir üye adına işlem yapabilirsiniz.

Temel adres: https://api.kolaymarketing.com/v1

Bu API ile yapılamayanlar: yayınlama, “şimdi yayınla”, kanal bağlama, yayın kapısını açma. Yayını KolayMarketing yapar; siz yalnız saat verirsiniz.

Kimlik doğrulama

Her istekte:

Authorization: Bearer km_pk_…

Anahtarı KolayMarketing yöneticisi üretir ve bir kez gösterir. Anahtarı yalnız sunucu tarafında saklayın; tarayıcıya ya da mobil uygulamaya koymayın.

Bir anahtar tek bir workspace’e bağlıdır ve bu sonradan değişmez. Tenant ve workspace her zaman anahtardan gelir; istek gövdesine yazılan kimlikler okunmaz. Başka bir workspace için yeni anahtar gerekir.

Yetkiler (scope)

Hiçbir yetki diğerini içermez. Yalnız ihtiyacınız olanları isteyin.

Scope İzin
content_read içerik, takvim, yayın kayıtları, medya okuma
content_write içerik açma, metin yazdırma
content_review bir üye adına metin/medya onayı ve ret
schedule saat verme, saati kaldırma
partner workspace özeti, bilgi formu, fikir bırakma (v1 yüzeyi)
signals_ingest sinyal gönderme (Sinyal gönderme)

Sekmelerinizi açmadan önce GET /partner/capabilities ile anahtarın neye yetkili olduğunu sorun.

actorEmail: kimin adına

Onay, ret, saat verme ve saat kaldırma bir kişi adına yapılır. actorEmail, o kişinin KolayMarketing’deki üye e-postasıdır. Kimlik doğrulamaz: kullanıcıyı sizin sisteminiz doğrular, biz yalnız üyeliği ve rolü denetleriz.

İşlem Gereken rol
onay, ret owner, admin, reviewer
saat verme, kaldırma owner, admin, editor
içerik açma, yazdırma owner, admin, editor; actorEmail verilmezse işlem tenant sahibi adına kaydedilir

E-posta bulunamazsa, üye pasifse, rol yetmiyorsa ya da aynı e-postayla birden çok üye varsa yanıt aynıdır: 403 actor_not_allowed. Yanlış e-posta hiçbir zaman sessizce sahibe düşmez. Her işlem içerik zaman çizelgesine anahtar kimliği, actorEmail ve istek kimliğiyle yazılır.

Uç noktalar

Okuma

Uç nokta Scope Not
GET /partner/capabilities herhangi biri anahtarın yetkileri, tenant özellikleri, açık uçlar
GET /partner/content?status=&from=&to=&cursor= content_read sayfa başına 50 kayıt, en son değişen önce
GET /partner/content/:id content_read publishBlocker dahil
GET /partner/calendar?from=&to= content_read ikisi zorunlu, en çok 62 gün
GET /partner/published?from=&to=&cursor= content_read yayınlanmış gönderiler ve metrikleri
GET /partner/media?contentId= content_read süreli indirme bağlantıları

publishBlocker, içeriğin neden henüz çıkamayacağını sade Türkçe söyler; null ise engel yoktur. Sayfalamada yanıttaki nextCursor değerini cursor olarak gönderin; null ise son sayfadır.

Metrikler: ölçülmemiş bir metrik 0 değildir. value: null gelir, source nedenini söyler (UNMEASURED: henüz ölçülmedi, NOT_CONFIGURED: ölçüm bağlı değil). Bunu ekranda sıfır olarak göstermeyin.

{ "key": "clicks", "value": null, "source": "UNMEASURED", "measuredAt": null }

Medya bağlantıları 15 dakika geçerlidir (urlExpiresInSeconds: 900). Saklamayın; gerektiğinde yeniden isteyin. Bağlantı üretilemeyen varlıkta url: null döner.

Yazma

Hepsi Idempotency-Key ister.

Uç nokta Scope Gövde
POST /partner/content content_write { topic, brief, sourceUrl?, channelIds?, actorEmail? }
POST /partner/content/:id/write content_write { actorEmail? }
POST /partner/content/:id/approve content_review { stage: "text" | "media", actorEmail }
POST /partner/content/:id/reject content_review { stage, reason, note?, actorEmail }
POST /partner/content/:id/schedule schedule { slotAt, actorEmail }
POST /partner/content/:id/unschedule schedule { actorEmail }

Saat vermek yayını garantilemez. Yayın anında metin ve görsel onayı, revizyon ve yayın kapıları yeniden denetlenir. Metin onaydan sonra değiştiyse içerik yayınlanmaz, incelemeye geri döner. Yayın kapısı kapalıysa içerik scheduled durumunda bekler.

Örnek akış

# 1. Anahtar neye yetkili?
curl https://api.kolaymarketing.com/v1/partner/capabilities \
  -H "Authorization: Bearer km_pk_…"

# 2. İçerik aç
curl -X POST https://api.kolaymarketing.com/v1/partner/content \
  -H "Authorization: Bearer km_pk_…" \
  -H "Content-Type: application/json" \
  -H "Idempotency-Key: 7f3c1e0a-new-post" \
  -d '{"topic":"Yeni kamera serisi","brief":"Depo güvenliği odaklı","actorEmail":"editor@firma.com"}'

# 3. Metni onayla
curl -X POST https://api.kolaymarketing.com/v1/partner/content/<id>/approve \
  -H "Authorization: Bearer km_pk_…" \
  -H "Content-Type: application/json" \
  -H "Idempotency-Key: 7f3c1e0a-approve-text" \
  -d '{"stage":"text","actorEmail":"onay@firma.com"}'

Idempotency

Tüm yazma isteklerinde Idempotency-Key başlığı zorunludur: 8-128 karakter, harf, rakam, _ ve -. Kapsamı anahtar + uç nokta + bu değerdir; 24 saat saklanır.

Durum Yanıt
Aynı değer, aynı gövde ilk yanıt tekrar döner; işlem tekrar yapılmaz
Aynı değer, farklı gövde 409 idempotency_mismatch
İlk istek hâlâ sürüyor 409 idempotency_in_progress; kısa süre sonra tekrar deneyin
İlk istek hata aldı değer serbest kalır, düzeltip aynı değerle yeniden deneyebilirsiniz

Ağ hatasında aynı değerle yeniden deneyin. Yeni bir işlem için yeni değer üretin.

Hatalar

Tüm hatalar aynı biçimdedir:

{ "error": { "code": "publish_blocked", "message": "Metin onayı bekleniyor." } }

message son kullanıcıya gösterilebilecek sade Türkçedir. Kodunuzu code üzerine kurun.

HTTP code Anlamı
400 invalid_body gövde ya da parametre geçersiz
400 idempotency_key_required başlık eksik ya da biçimi yanlış
401 unauthorized anahtar geçersiz ya da iptal edilmiş
403 forbidden scope eksik ya da bu hesapta API kapalı
403 actor_not_allowed actorEmail bu işlem için kullanılamıyor
404 not_found kayıt yok ya da başka bir workspace’e ait; ikisi ayırt edilmez
409 invalid_transition içerik bu durumdayken bu işlem yapılamaz
409 publish_blocked onaylar tamamlanmadı
409 brief_missing, vendor_not_configured workspace henüz hazır değil
409 no_owner tenant’ın aktif sahibi yok
409 idempotency_mismatch, idempotency_in_progress yukarıya bakın
402 quota_exceeded aylık kota doldu
429 rate_limited istek sınırı aşıldı; bekleyip tekrar deneyin
502 write_failed, storage_failed geçici; yeniden deneyin
503 secrets_unavailable geçici; yeniden deneyin

İstek sınırları

İzleme

X-Request-Id gönderirseniz (1-128 karakter, harf, rakam, ., _, -) aynısı yanıtta döner; göndermezseniz biz üretiriz. Destek talebinde bu değeri paylaşın. Anahtarı hiçbir zaman paylaşmayın.