NarPOS entegrasyonu
NarPOS kataloğu ve satış açıklığını merkezi REST API'ye gönderir. Platform sipariş olaylarını ortam başına tek HTTPS adresine yollar. NarPOS kesinleşen siparişi API'den okur ve kasa işlemlerinin sonucunu aynı API'ye bildirir.
OpenAPI 3.1 · Postman koleksiyonu · Örnek katalog
Sandbox APK ile ilk test
Sandbox API adresi https://bxvwuasaytgdqnsiinni.supabase.co/functions/v1/narpos/v1. Postman koleksiyonu bu adresi varsayılan olarak kullanır. Telefondaki NarPOS Sandbox APK’sının Android paket kimliği com.justforpizza.just_for_pizza.narpossandbox.
- APK’yı yükleyin ve
narpos-mobile-test@example.comtest hesabıyla giriş yapın. Test parolası ve mobil test şubesininbranch_keydeğeri güvenli kanaldan ayrı paylaşılır. - NarPOS Mobil Test (
sandbox-mobile) şubesini seçin. Pizza → Büyük seçeneğini sepete ekleyin. Ekstra seçmeden devam ederseniz tutar 290,00 TL. Gel al → Kasada nakit ile siparişi onaylayın. - Postman’da mobil test şubesinin
branch_keydeğerini girin.GET /eventsakışındaorder.createdolayını bulun, sipariş kimliğiyleGET /orders/{order_id}çağırın.fulfillmentdeğerinipickup,payment.methoddeğerinicash,payment.due_minordeğerini29000olarak kontrol edin. - Önce ACK gönderin. Son yanıtta dönen
versionile sırasıylapreparing,readyvedelivereddurumlarını yazın. Son istekte örnekteki gibi aynı tutarlacashtahsilatı ve benzersiz bir kasa referansı gönderin. Test tahsilatı sandbox’a yazılır. Kart veya banka sağlayıcısına çağrı yoktur.
Webhook alıcı adresi hazır olana kadar olayları GET /events üzerinden test edebilirsiniz. Mobil test şubesinin kataloğu hazır. İlk bağlantıyı, katalog değişikliklerini ve satış kapatmayı denemek için ayrı bir sandbox şubesi kullanabilirsiniz.
Hızlı başlangıç
- Restoran yöneticisi Entegrasyonlar → NarPOS ekranında
7K3M-9X2Cbiçiminde sekiz karakterli aktivasyon kodunu üretir. Kod 30 dakika geçerlidir. NarPOS büyük/küçük harf farkı olmadan, tireli veya tiresiz girilen kodu bir kez kullanır. Dönen şube API anahtarını kendi sunucusunda saklar. Yeni kod kullanıldığında mevcut API anahtarı yenilenir. - NarPOS şube anahtarıyla tam kataloğu gönderir. Restoran önizlemeden mevcut kalemleri eşleştirir, ürünleri onaylar ve NarPOS'u aktif POS olarak seçer.
- NarPOS olay geldiğinde imzayı doğrulayıp olayı kalıcı olarak kaydeder, ardından
2xxdöner. Sipariş verisini API'den okuyup kasa kaydı oluşturduğundaackgönderir. - NarPOS kasa durumunu ve gerekiyorsa kasa tahsilatını
updatesile bildirir.
Aşağıdaki değişkenleri kendi ortamınızla doldurun. API değerinin sonu /functions/v1/narpos/v1 olmalı.
curl --fail-with-body -sS "$API/connections/redeem" \
-H "Authorization: Bearer $PARTNER_SECRET" -H 'Content-Type: application/json' \
-d "{\"code\":\"$CONNECTION_CODE\"}"
curl --fail-with-body -sS -X PUT "$API/catalog/revisions/1/parts/1" \
-H "Authorization: Bearer $BRANCH_KEY" -H 'Content-Type: application/json' \
--data-binary @catalog.json
curl --fail-with-body -sS "$API/catalog/revisions/1/commit" \
-H "Authorization: Bearer $BRANCH_KEY" -H 'Content-Type: application/json' -d '{"part_count":1}'
curl --fail-with-body -sS "$API/orders/$ORDER_ID" -H "Authorization: Bearer $BRANCH_KEY"
curl --fail-with-body -sS -X PUT "$API/orders/$ORDER_ID/ack" \
-H "Authorization: Bearer $BRANCH_KEY" -H 'Content-Type: application/json' \
-H "Idempotency-Key: $ACK_KEY" -d "{\"version\":$ORDER_VERSION,\"external_id\":\"$POS_ORDER_ID\"}"
Katalog ve satış durumu
- Her şube için
revisionvesource_revisionaynı artan sayacı kullanır. Değerler JSON'da ondalık metindir. Katalog parçalarının her biri aynı tam katalog sürümüne aittir. Parçalar 1'den başlayarak boşluksuz numaralanır. En çok 100 parça, parça başına 500 kalem ve 256 KiB, sürüm başına 10.000 kalem kabul edilir. - Kimlikler şube ve kalem türü içinde kalıcıdır. Ürün
category_idile kategoriyi, grupproduct_idile ürünü, varyasyon ve seçenekgroup_idile grubu gösterir. Bir varyasyon grubu tek seçimli, zorunlu veprice_mode: setolmalıdır. Seçeneğinprice_mode: addgrubu sadece fiyat farkını ekler.free_counther ürün birimi için ücretsiz seçim adedidir. pricestam sayı kuruştur.defaulttutarı servis tipi için özel fiyat verilmediğinde kullanılır. Diğer anahtarlarpickup,deliveryvedine_indeğerleridir. Varyasyon fiyatı ürünün taban fiyatının yerini alır. Ek seçenekler taban fiyata eklenir.- Tam sürüm onaylanınca katalogdan çıkarılan kalem satıştan kalkar. Satışı hızlı kapatmak için ayrı katalog yazma çağrısını kullanın. Eski bir tam sürüm, daha yeni bir kapanışı geri alamaz. Restoranın özel uygulama fiyatı ve yereldeki kapatma tercihi saklanır.
curl --fail-with-body -sS "$API/catalog/availability" \
-H "Authorization: Bearer $BRANCH_KEY" -H 'Content-Type: application/json' \
-d '{"kind":"product","id":"pizza","available":false,"source_revision":"2"}'
Webhook ve toparlanma
Platform yöneticisi alıcı adresini Superadmin → Bildirim kanalları → NarPOS sipariş webhook’u ekranında kaydeder. Her ortamın tek alıcı adresi vardır. Alan boş kaydedilirse bekleyen olaylar kuyrukta kalır. Gönderim, adres kaydedildikten sonraki işçi çalışmasında devam eder.
Her istekte X-NarPOS-Timestamp Unix saniyesi ve X-NarPOS-Signature başlığında v1=<hex> bulunur. Doğrulanan mesaj, UTF-8 olarak <timestamp>.<ham HTTP gövdesi> dizisidir. Ortamın ortak webhook sırrıyla HMAC-SHA256 hesaplanır. İmzayı sabit süreli karşılaştırın ve beş dakikadan eski zamanları reddedin. Tekrar denemede imza zamanı yenilenir, event_id aynı kalır.
- Olay türleri
order.created,order.status_changed,order.cancelledveorder.payment_changed. Olayda şube, bağlantı, sipariş ve sürüm kimliği bulunur. Tam sipariş API'den okunur. Yinelenen olaylarevent_idile ayıklanabilir. Siparişin en son sürümü işlenir. - Platform, ağ hatası veya
429/5xxiçin artan aralıklarla en çok sekiz kez deneyecek. İşlem sonucu panelde görünür. Alıcı adresi boşken olaylar kuyrukta bekler ve deneme sayıları artmaz. NarPOS'un kendi durum yazması için yankı olayı gönderilmez. Bunun ardından platformda gerçekleşen iade kendi olayını üretir. GET /events?after=<cursor>son 30 günün olaylarını verir.next_cursordeğerini kalıcı kaydedin.410 cursor_expiredalınırsaGET /ordersilk sayfasındakievent_cursordeğerini kaydedin,next_cursorile sipariş sayfalarını tamamlayın ve olay akışına ilk sayfadaki olay kursorundan dönün.
Sipariş ve ödeme
NarPOS kasaya kesinleşen sipariş tutarını yazar. Tutarların tamamı TRY kuruştur. Etkin uygulama fiyatları, ücretsiz seçenek adetleri, teslimat, kampanya, kupon ve puan indirimi siparişle birlikte dondurulur. selections[].qty ürün birimi başına adettir. charged_minor bir ürün birimindeki o seçimin ücretlendirilen toplamıdır. Varyasyonun tutarı base_minor içindedir.
Durum akışı received → preparing → ready → delivered. Teslim öncesi iptal, varsa platform iade işlemini tetikler. Kasa tahsilatı yapılmış bir siparişin iptali operasyon incelemesine alınır. payment.due_minor POS'un tahsil edeceği tutardır. Cüzdan, online kart ve sıfır toplamda bu alan sıfırdır. Kapıda veya kasada nakit/kart ödeme için teslimden önce veya teslim isteğiyle birlikte kasa referansı, yöntem ve tam tutar verilir.
curl --fail-with-body -sS "$API/orders/$ORDER_ID/updates" \
-H "Authorization: Bearer $BRANCH_KEY" -H 'Content-Type: application/json' \
-H "Idempotency-Key: $DELIVERY_KEY" \
-d "{\"version\":$ORDER_VERSION,\"status\":\"delivered\",\"collection\":{\"method\":\"cash\",\"amount_minor\":29000,\"reference\":\"TILL-42\"}}"
Yazma istekleri sipariş sürümü ve Idempotency-Key gerektirir. ACK ve her durum/tahsilat yanıtındaki version değerini sonraki yazmada kullanın. Postman koleksiyonu bu değeri order_version değişkenine kaydeder. Yanıt alınamazsa aynı anahtar ve gövdeyle tekrar edin. Sürüm uyuşmazlığında siparişi yeniden okuyun. Farklı bir işlem için yeni anahtar kullanın.
| Durum | Örnek neden |
|---|---|
400 |
Geçersiz alan veya JSON |
401 |
Süresi dolmuş kod, hatalı anahtar veya erişim iptali |
403 |
Kurulum aşaması, bekleyen siparişleri tamamlama modunda katalogya yazma |
404 |
İlgili bağlantıda kayıt yok |
409 |
Eksik/eski sürüm, farklı yinelenen istek, sipariş sürümü ya da tahsilat uyuşmazlığı |
410 |
Olay kursoru süresi doldu |
413 |
İstek gövdesi 256 KiB üzerinde |
422 |
Katalog öğelerinin ilişkisi geçersiz |
Bağlantı durumları
| Durum | Davranış |
|---|---|
active |
Yeni ve atanmış mevcut siparişleri işler. |
draining |
Yalnızca kendi bağlantı kimliğine atanmış siparişleri işler. |
revoked |
API erişimi ve POS gönderimi kapanır. Bekleyen işler operasyona düşer. |
Siparişin bağlantı kimliği oluşturulduğunda sabitlenir. Eski bağlantı draining iken gelen online ödeme sonucu o bağlantının siparişini kuyruğa alır. revoked bağlantıda ödeme sonucu platformda kaydedilir ve sipariş müdahale bekler.