Uygulama geliştir

Uygulamalar, bir restoranın hesabını kapsamlı, iptal edilebilir OAuth erişimi aracılığıyla genişletir. Kodunuz kendi sunucularınızda çalışır; platform kayıt defterini, kurulum defterini ve faturalandırma raylarını tutar. Bu kılavuz sizi sıfırdan kurulmuş, ölçülen bir uygulamaya götürür.

1. Uygulamanızı kaydedin

Şurada bir uygulama oluşturun: iş ortağı panosu: ad, kategori, ihtiyacınız olan kapsamlar, isteğe bağlı bir webhook URL'si ve faturalandırma modeliniz. Göndermek bir OAuth istemcisi oluşturur (istemci kimliği + gizli anahtar) ve uygulamayı incelemeye alır. Bir yönetici onayladıktan sonra App Store'da görünür ve kurulabilir.

2. Kurulun

Bir restoran sahibi uygulamanızı App Store ayrıntı sayfasından kurar ve istediğiniz kapsamları verir. Kurulum bir şey oluşturur: AppInstallation ve (ücretli uygulamalar için) ilk dönemi cüzdanlarından tahsil eder.

3. API'yi çağırın

Kurulum yapan hesap için bir OAuth belirteci alışverişi yapın, ardından şunu çağırın: REST API onunla. Kullanımı raporlayın, webhook'lar alın veya panolarına bir sayfa gömün — aşağıda ele alınmıştır.

OAuth ve belirteçler

Uygulamalar OAuth 2.0 (Laravel Passport) ile kimlik doğrular. İstemci bilgileriniz iş ortağı panosundan gelir. Standart yetkilendirme kodu akışını kullanın; verilen belirteç sahibin kurulumda onayladığı kapsamları taşır.

# Exchange an authorization code for an access token
curl -X POST https://www.menubarcode.comoauth/token \
  -d grant_type=authorization_code \
  -d client_id=YOUR_CLIENT_ID \
  -d client_secret=YOUR_CLIENT_SECRET \
  -d redirect_uri=YOUR_REDIRECT \
  -d code=AUTH_CODE

# Call the API with the returned bearer token
curl https://www.menubarcode.com/api/v1/restaurants \
  -H "Authorization: Bearer ACCESS_TOKEN" \
  -H "Accept: application/json"

Belirteçler kapsamlıdır: şuna ihtiyaç duyan bir çağrı: orders:read sahip onu vermediği sürece başarısız olur. Minimum seti isteyin — inceleyenler bunu kontrol eder.

Oturum belirteçleri

Kısa ömürlü, sunucudan gömülüye çağrılar için aktif bir kurulumdan bir oturum belirteci oluşturun. Belirteçler şu sürenin ardından sona erer: 60 saniye.

GET https://www.menubarcode.comapps/{appId}/session-token
# → { "token": "…", "expires_in": 60 }

Gömülü uygulamalar

Uygulamanız bir şey bildirirse: embed_url, platform onu sahibin panosunun içinde bir iframe'de barındırır: /apps/{appId}/embed. Gömülü sayfanın kimliğini tam bir OAuth gidiş-dönüşü olmadan doğrulamak için onu bir oturum belirteciyle (yukarıda) eşleştirin.

Webhook'lar

Uygulamanızın şurasındaki olaylara abone olun: webhook_url. Teslimatlar kuyruğa alınır, yeniden denenir ve şununla imzalanır: Standard Webhooks şeması, uygulamanızın imzalama gizli anahtarını kullanarak. Uç noktanız herkese açık bir HTTPS URL'si olmalıdır (özel/geri döngü/meta veri ana bilgisayarları yok) ve şunu döndürmelidir: 2xx hızlıca.

# A delivery your endpoint receives
POST https://your-app.com/webhooks
webhook-id: msg_...
webhook-timestamp: 1710000000
webhook-signature: v1,BASE64_HMAC
Content-Type: application/json

{ "type": "order.paid", "data": { "order_id": 123, ... } }

Bir yüke güvenmeden önce imzayı gizli anahtarınıza göre doğrulayın. Bkz. olay listesi.

Kullanım faturalandırması

Kullanıma göre faturalandırılan uygulamalar tüketimi birimler raporlayarak ölçer. Her rapor birim başına fiyatınızla sahibin cüzdanından tahsil edilir. Benzersiz bir şey geçirin: ref bir raporu etkisiz (idempotent) yapmak için (aynı ref ile bir tekrar yok sayılır).

curl -X POST https://www.menubarcode.com/api/app/usage \
  -H "Authorization: Bearer ACCESS_TOKEN" \
  -H "Accept: application/json" \
  -d quantity=1 \
  -d ref=unique-key-per-event

Uç nokta şunu döndürür: 403 belirteç kayıtlı bir uygulamaya ait değilse veya uygulama hesap için kurulu değilse.

Nasıl yapılır kılavuzları

Bir faturalandırma türü seçin

• Ücretsiz — kurulumda ücret yok.
• Yinelenen — her faturalandırma döneminde (varsayılan 30 gün) sahibin cüzdanından tahsil edilen sabit bir fiyat.
• Kullanıma dayalı — kullanımı raporladıkça faturalandırılan birim başına bir fiyat.

Kapsamları sorumlu bir şekilde isteyin

Yalnızca uygulamanızın kullandığı kapsamları isteyin. Canlı bir listelemede kapsamları değiştirmek uygulamayı incelemeye geri gönderir. Şuna bakın: kapsamlar referansı.

Kaldırmada temizleyin

Bir sahip kaldırdığında, platform uygulamanın belirteçlerini iptal eder ve bir şey tetikler: app/uninstalled olayı. Onu aldığınızda o hesap için arka plan işlerini durdurun ve saklanan verileri silin.

kapsamlar referansı

Platformun OAuth kapsam kayıt defterinden yansıtılmıştır.

Webhook olayları

Bugün abone olabileceğiniz olaylar:

Listeleme ve inceleme gereksinimleri

Bir yönetici uygulamanızı onaylamadan önce şunları yapmalıdır:

• Yalnızca kullandığı kapsamları isteyin, her biri açıklamada gerekçelendirilmiş.
• Olaylara abone oluyorsa çalışan bir webhook uç noktası sağlayın (herkese açık HTTPS).
• Doğru fiyatlandırma bildirin — ayrıntı sayfanızdaki fiyatlandırma tablosu bundan oluşturulur.
• Net bir slogan, açıklama, kategori ve en az bir ekran görüntüsü ekleyin.
• Kaldırmayı temiz bir şekilde ele alın (erişimi iptal edin, faturalandırmayı durdurun, hesap verilerini silin).

Meta veri düzenlemeleri (slogan, açıklama, ekran görüntüleri, bağlantılar) hemen yayına girer; fiyat veya kapsam değişiklikleri incelemeyi yeniden kuyruğa alır.