Apolyont
API v2

API Dokümantasyonu

Apolyont platformuyla REST API, WebSocket, webhook ve MQTT üzerinden entegrasyon kurabilirsiniz. Bu sayfa, harici geliştiricilerin API ile nasıl etkileşime geçeceğini açıklar.

1. Temel Bilgiler

Tüm API uçları /api/v2 öneki altında sunulur: 

Base URL:  https://apolyont.com/api/v2
  • Tüm istek ve yanıtlar application/json formatındadır.
  • Etkileşimli API şeması (Swagger UI): apolyont.com/docs
  • Makine okunabilir şema: https://apolyont.com/openapi.json
  • Sağlık kontrolü: GET /health ve GET /health/detailed (veritabanı + Redis durumu).

2. Kimlik Doğrulama

Korumalı uçlar JWT Bearer token ile doğrulanır. Token, HS256 ile imzalanır ve Authorization başlığında gönderilir: 

Authorization: Bearer <access_token>

2.1 Telefon + Şifre ile Giriş

POST /api/v2/auth/login 

curl -X POST https://apolyont.com/api/v2/auth/login \
  -H "Content-Type: application/json" \
  -d '{"phone": "5XXXXXXXXX", "password": "sifreniz"}'

# Yanıt
{"access_token": "eyJhbGciOi..."}

2.2 SMS Kodu (OTP) ile Giriş

Önce telefon numarasına 4 haneli SMS kodu gönderilir:

POST /api/v2/auth/send-otp 

curl -X POST https://apolyont.com/api/v2/auth/send-otp \
  -H "Content-Type: application/json" \
  -d '{"phone_number": "5XXXXXXXXX"}'

Ardından kod ile token alınır:

POST /api/v2/auth/login-with-otp 

curl -X POST https://apolyont.com/api/v2/auth/login-with-otp \
  -H "Content-Type: application/json" \
  -d '{"phone_number": "5XXXXXXXXX", "otp_code": "1234"}'
  • OTP kodları 5 dakika geçerlidir.
  • OTP isteği hız sınırlıdır: telefon başına 5 dakikada en fazla 3 deneme (aşılırsa 429).

2.3 Çoklu Firma: X-Firm-ID Başlığı

Birden fazla firmaya erişimi olan kullanıcılar, /api/v2/* isteklerinde isteğe bağlı X-Firm-ID: <firma_id> başlığı gönderebilir. Başlıktaki firma, token'daki kullanıcıyla eşleşmezse istek 403 ile reddedilir. /auth, /webhook ve /payment/webhook yolları bu doğrulamadan muaftır.

3. Herkese Açık Uçlar

Aşağıdaki uçlar kimlik doğrulama gerektirmez:

3.1 Sipariş Takibi

GET /api/v2/track/{takip_kodu}

Müşterilere iletilen takip kodu ile siparişin anlık durumunu döndürür.

curl https://apolyont.com/api/v2/track/ABC123

3.2 QR Menü

GET /api/v2/qr-menu/{firma_id}

Bir restoranın aktif kategori ve ürünlerini döndürür (fiyatlar kuruş cinsindendir).

curl https://apolyont.com/api/v2/qr-menu/1

4. Webhook'lar (Platform Entegrasyonları)

Sipariş platformları ve POS sistemleri, yeni siparişleri ve iptalleri Apolyont'a webhook ile iletir.

POST /api/v2/webhook/{platform}/new-order
POST /api/v2/webhook/{platform}/cancel-order

Desteklenen platformlar:

  • getir / getir-yemek, yemeksepeti, trendyol, migros
  • adisyo, sepettakip, poscube, roogo, whatsapp
  • Başarılı alımlar 202 Accepted döner ve kuyruğa alınarak asenkron işlenir.
  • Mükerrer siparişler 409 + DUPLICATE_ORDER, iptal edilemeyen siparişler 409 + ORDER_NOT_CANCELLABLE döner.
  • Sunucuda WEBHOOK_SHARED_SECRET tanımlıysa, çağrılar X-Apolyont-Webhook-Secret başlığıyla aynı gizli değeri göndermelidir; aksi halde 401 döner.

4.1 Adisyo POS İmzası

POST /api/v2/webhook/adisyo

Adisyo webhook'ları, gövdenin HMAC (SHA-256/SHA-512) imzasını x-adisyo-signature başlığında taşır. İmza doğrulanamayan istekler işlenmez.

5. WebSocket (Gerçek Zamanlı Olaylar)

WS /api/v2/ws/firm/{firma_id}?token=<jwt>

  • JWT, header yerine token sorgu parametresiyle gönderilir.
  • Geçersiz token: bağlantı 4001 koduyla, firmaya ait olmayan kullanıcı: 4003 koduyla kapatılır.
  • Bağlantıyı canlı tutmak için {"type":"ping"} gönderin; sunucu {"type":"pong"} ile yanıtlar.
  • Sunucu, firma olaylarını {"event": "...", "data": {...}} formatında iter.
const ws = new WebSocket(
  `wss://apolyont.com/api/v2/ws/firm/1?token=${accessToken}`
);
ws.onmessage = (e) => console.log(JSON.parse(e.data));

6. MQTT (Telemetri / Konum)

Cihaz ve kurye telemetrisi için MQTT broker üzerinden bağlanabilirsiniz:

  • MQTT (TCP): 1883 portu
  • MQTT over WebSocket: 9001 portu

7. Hata Formatı

Hatalar tutarlı bir JSON yapısıyla döner:

{
  "message": "Geçersiz kimlik bilgileri",
  "code": "INVALID_CREDENTIALS"
}

Doğrulama hataları 422 durum kodu ve alan bazlı detaylarla döner:

{
  "message": "Validation failed",
  "code": "VALIDATION_ERROR",
  "errors": [ ... ]
}

8. Test ve Deneme

API'yi canlı olarak denemek için Test Bed sayfasındaki etkileşimli konsolu kullanabilirsiniz. Kimlik doğrulamalı uçlar için demo hesap talebinde bulunmak üzere başvuru formunu doldurun veya [email protected] adresine yazın.