NarPOS Partner API

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.

  1. APK’yı yükleyin ve narpos-mobile-test@example.com test hesabıyla giriş yapın. Test parolası ve mobil test şubesinin branch_key değeri güvenli kanaldan ayrı paylaşılır.
  2. 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.
  3. Postman’da mobil test şubesinin branch_key değerini girin. GET /events akışında order.created olayını bulun, sipariş kimliğiyle GET /orders/{order_id} çağırın. fulfillment değerini pickup, payment.method değerini cash, payment.due_minor değerini 29000 olarak kontrol edin.
  4. Önce ACK gönderin. Son yanıtta dönen version ile sırasıyla preparing, ready ve delivered durumlarını yazın. Son istekte örnekteki gibi aynı tutarla cash tahsilatı 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ıç

  1. Restoran yöneticisi Entegrasyonlar → NarPOS ekranında 7K3M-9X2C biç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.
  2. 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.
  3. NarPOS olay geldiğinde imzayı doğrulayıp olayı kalıcı olarak kaydeder, ardından 2xx döner. Sipariş verisini API'den okuyup kasa kaydı oluşturduğunda ack gönderir.
  4. NarPOS kasa durumunu ve gerekiyorsa kasa tahsilatını updates ile 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

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.

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.