API'ye genel bakış

Public REST API https://<api>/v1/… altındadır; sözleşme openapi.yaml (OpenAPI 3.1, 169 işlem) dosyasıdır ve kırıcı değişiklik yapılmaz (ekleme serbest, kırıcı değişiklik yeni sürüm). Tüm işlemlerin listesi: işlem listesi. Çalışan API, etkileşimli belgeleri /docs ve JSON sözleşmeyi /openapi.json adreslerinde de sunar; dashboard'daki Geliştirici → API Explorer aynı sözleşmeyle istek dener.

Kimlik doğrulamaBağlantıyı kopyala

Authorization: Bearer hs_live_…

API anahtarları Organizasyon → API anahtarları ekranından ya da POST /v1/apps/{app_id}/api-keys ile oluşturulur; ham anahtar yalnızca oluşturma ve rotate yanıtında görünür. Anahtar app'e bağlı (yalnızca o app) ya da org geneli (tüm app'ler; GET /v1/apps, POST /v1/apps, GET /v1/organization* için gerekir) olabilir. Ortam live / test; IP izin listesi ve bitiş tarihi verilebilir. Anahtar reddedildiğinde 401 HS_UNAUTHENTICATED, kapsam yetmediğinde 403 HS_FORBIDDEN.

İstemci SDK uçları (/sdk/v1/apps/{app_id}/…) API anahtarı kullanmaz; sahiplik kanıtı token_hash (kayıtlı token'ın SHA-256'sı) ve identity verification zorunluysa identity_hash = HMAC-SHA256(sdk_secret, external_id) ile sağlanır.

İstek ve yanıt kurallarıBağlantıyı kopyala

• Gövdeler JSON (Content-Type: application/json); import multipart/form-data. Alan adları snake_case, zamanlar ISO 8601 UTC.
• Kimlikler ön ekli ULID: app_, usr_, sub_, msg_, dlv_, seg_, tpl_, cmp_, jrn_, whe_…
• Her yanıt x-request-id taşır; hata zarfındaki request_id ile aynıdır ve dashboard Loglar ekranında aranabilir.
• Çok dilli metinler nesne olarak verilir: { "tr": "…", "en": "…" }; alıcının dili yoksa en, o da yoksa ilk dil kullanılır.

Hata zarfıBağlantıyı kopyala

{
  "error": {
    "code": "HS_VALIDATION_ERROR",
    "message": "İstek doğrulanamadı.",
    "details": { "issues": [{ "path": "contents", "message": "Required" }] },
    "request_id": "req_01…",
    "doc_url": "https://docs.pushizo.com/errors#HS_VALIDATION_ERROR"
  }
}

Kodlar ve ne yapılacağı: hata kataloğu. Hata kodu ayrıca x-hs-error-code başlığında döner.

IdempotencyBağlantıyı kopyala

POST /v1/notifications için Idempotency-Key başlığı ya da gövdede idempotency_key: aynı anahtar + aynı gövde aynı yanıtı döndürür; farklı gövde 409 HS_IDEMPOTENCY_CONFLICT, işlem sürüyorsa 409 HS_IDEMPOTENCY_IN_PROGRESS. Sunucu SDK'ları autoIdempotencyKey ile otomatik UUID üretir ve yeniden denemelerde aynı anahtarı kullanır.

Hız sınırı ve kotaBağlantıyı kopyala

Plan bazlı istek sınırı (api_rps); yanıt başlıkları X-RateLimit-Limit, X-RateLimit-Remaining, X-RateLimit-Reset. Aşımda 429 HS_RATE_LIMITED + Retry-After; plan kotası aşımında 429 HS_QUOTA_EXCEEDED (details.metric, limit, used). Özellik planda yoksa 403 HS_PLAN_FEATURE_REQUIRED. Ayrıntı: Faturalama ve kota.

SayfalamaBağlantıyı kopyala

Liste uçları limit ve cursor alır; yanıt data[], next_cursor, has_more döner. Sonraki sayfa için cursor=next_cursor. Sunucu SDK'larında paginate / list_all / ListAll yardımcıları tüm sayfaları dolaşır.

Bildirim göndermeBağlantıyı kopyala

POST /v1/notifications
{
  "app_id": "app_…",
  "idempotency_key": "order-1001",
  "target": { "include_external_ids": ["user_42"], "channels": ["ios_push", "android_push", "web_push"] },
  "headings": { "tr": "Siparişiniz yola çıktı" },
  "contents": { "tr": "Takip bağlantısı içeride" },
  "url": "https://example.com/orders/1001",
  "data": { "order_id": "1001" },
  "send_after": "2026-10-14T09:00:00Z",
  "delayed_option": "timezone",
  "delivery_time_of_day": "09:00"
}

Hedef (target): all, include_subscription_ids, include_external_ids, include_aliases, included_segments / excluded_segments, filters (segment AST), channels, test_devices_only, email_to, include_phone_numbers. Yanıt 202 { id, status, recipients_estimate, external_id_missing }; teslimat asenkrondur. Gönderim yapmadan alıcı sayısı için POST /v1/notifications/estimate. Kanal bazlı içerik alanları (ios_*, android_*, chrome_web_*, email_*, sms_*, add_to_inbox) için Mesajlaşma ve iOS alanları için critical alert rehberi.

Sunucu SDK'larıBağlantıyı kopyala

Tüm işlemler Node (@pushizo/node), PHP (pushizo/pushizo-php) ve OpenAPI'den üretilen Python, Go, Java, .NET, Ruby SDK'larında kaynak × metot olarak bulunur (hs.notifications.create, hs.users.upsert, hs.segments.list…). Rehberler: SDK'lar.

SürümlemeBağlantıyı kopyala

Yol /v1; yeni alanlar ve uçlar geriye dönük uyumlu eklenir. Kırıcı değişiklikler /v2 altında yayımlanır ve /v1 en az 12 ay desteklenir. OpenAPI dosyası depoda api/openapi.yaml olarak sürümlenir; CI'da sözleşme kırılması (npm run ci:local) denetlenir.