Comvo API

Davet oluşturun, yanıtları ve metrikleri okuyun, organizasyonu eşitleyin, olayları webhook ile alın.

Hızlı başlangıç

Panelde Ayarlar > API Anahtarları'ndan bir anahtar oluşturun. Önce sk_test_ anahtarıyla deneyin: test anahtarıyla oluşan davet ve yanıtlar canlı veriden ayrı tutulur, raporlara girmez.
Anahtarı doğrulayın:

curl https://my.comvo.com.tr/api/v1/me \
  -H "Authorization: Bearer sk_test_..."

Bir işlem (sipariş, servis kaydı) için kişiye özel anket bağlantısı alın:

curl -X POST https://my.comvo.com.tr/api/v1/invitations \
  -H "Authorization: Bearer sk_test_..." \
  -H "Content-Type: application/json" \
  -H "Idempotency-Key: siparis-98123" \
  -d '{
    "survey": "srv_...",
    "org_unit": "IST-034",
    "transaction_ref": "98123",
    "contact": { "external_id": "C-5521", "name": "Ayşe Yılmaz", "email": "[email protected]" }
  }'
# 201 { "id": "inv_...", "url": "https://my.comvo.com.tr/s/...", ... }

url kişiye gönderilecek tek kullanımlık bağlantıdır; yalnız bu yanıtta döner. Bağlamdaki her alan (birim, işlem no, müşteri no, iletişim bilgisi, özel alanlar) markanın yürürlükteki aydınlatma metninde yer almalıdır; yoksa istek privacy_notice_not_covering hatasıyla reddedilir.

Kurallar

Kimlik: Authorization: Bearer sk_live_.... Anahtar yalnız seçilen kapsamları kullanabilir; birime kısıtlı anahtar yalnız o birim ve altını görür.
Idempotency: yazma isteklerinde Idempotency-Key gönderin. Aynı anahtarla 24 saat içinde gelen aynı istek yeniden işlenmez, ilk yanıt Idempotent-Replayed: true başlığıyla döner. Aynı anahtar farklı gövdeyle gelirse 422.
Sayfalama: listeler imleçlidir. Yanıttaki next_cursor değerini ?cursor= ile gönderin; has_more false olunca bitti. limit en fazla 100.
Hız sınırı: anahtar başına dakikada 600 istek, toplu uçlar 30. RateLimit-Limit, RateLimit-Remaining, RateLimit-Reset başlıklarına bakın; 429 gelirse Retry-After kadar bekleyin.
Zamanlar ISO 8601 UTC. Kimlikler önekli: srv_, inv_, rsp_, org_.
Kişisel veri: yanıtlarda ad, e-posta, telefon yalnız responses:pii kapsamıyla gelir; kişi anonim kalmayı seçtiyse hiç gelmez.

Webhook'lar

Olayları almak için panelde Ayarlar > Webhook'lar'dan ya da /webhook-endpoints ile adres ekleyin. Her istek Webhook-Signature: t=<zaman>,v1=<HMAC-SHA256(anahtar, "zaman.gövde")> ile imzalıdır; panelde her webhook'un "Teknik Rehber" sekmesinde PHP, Node.js ve Python doğrulama kodu ve örnek yük var. 10 saniye içinde 2xx dönün; olmazsa webhook'un hata politikasına göre tekrar denenir.

Hatalar

Hatalar RFC 9457 application/problem+json biçimindedir. code alanına göre davranın; detail insan içindir.

{ "type": "https://my.comvo.com.tr/developers#errors-validation_failed", "title": "Doğrulama hatası", "status": 422,
  "code": "validation_failed", "detail": "...", "errors": { "survey": ["Anket bulunamadı."] } }

code	Durum	Anlamı ve ne yapılmalı
`unauthenticated`	401	Authorization başlığı yok ya da biçimi yanlış.
`invalid_key`	401	Anahtar bulunamadı, iptal edildi ya da süresi doldu. Panelden yeni anahtar oluşturun.
`insufficient_scope`	403	Anahtarda bu işlem için kapsam yok (required_scope alanında). Anahtarı yeni kapsamla oluşturun.
`outside_scope`	403	Birime kısıtlı anahtar bu kayda ya da kiracı geneli bir işleme erişemez.
`forbidden`	403	İşleme izin verilmiyor.
`not_found`	404	Kayıt yok ya da anahtarın erişim alanı (birim, canlı/test modu) dışında.
`method_not_allowed`	405	Bu adres bu HTTP yöntemini desteklemiyor.
`invitation_completed`	409	Yanıtlanmış davet iptal edilemez.
`idempotency_in_progress`	409	Aynı Idempotency-Key ile ilk istek hâlâ işleniyor; biraz sonra tekrar deneyin.
`invalid_idempotency_key`	400	Idempotency-Key boş ya da 255 karakterden uzun.
`idempotency_mismatch`	422	Aynı Idempotency-Key başka bir gövdeyle kullanıldı.
`validation_failed`	422	Gönderilen veride hata var; alan bazında ayrıntı errors içinde.
`survey_not_live`	422	Anket yayında değil; davet açılamaz.
`unknown_context_field`	422	Bağlamdaki alan panelde (KVKK ve Veri > Alanlar) tanımlı değil (fields).
`privacy_notice_not_covering`	422	Alanlar markanın yürürlükteki aydınlatma metninde yok (fields). Metne ekleyip yayınlayın.
`invalid_assignee`	422	Atanacak üye yok ya da bu yanıtı yönetme yetkisi yok.
`invalid_level`	422	Seviye adı bulunamadı ya da üst birimin altında seviye tanımlı değil.
`range_too_long`	422	Metrik aralığı en fazla 366 gün.
`rate_limited`	429	Hız sınırı aşıldı; Retry-After kadar bekleyin.
`server_error`	500	Beklenmeyen hata. Idempotency-Key ile güvenle tekrar deneyebilirsiniz.