MAXXLATeknik Görüşme

Teknik Entegrasyon

Maxxla ile POS ve kasa entegrasyonu nasıl yapılır?

Bu sayfa, POS/kasa sistemi teknik ekibinin Maxxla’ya bağlanırken hangi verileri göndereceğini, hangi olayları dinleyeceğini ve testte neyi doğrulayacağını açıklar.

Sandbox Bilgisi İsteWhatsApp Teknik Görüşme

En kısa doğru özet

ÜrünlerPOS → Maxxla
SiparişlerMaxxla → POS, POS → Maxxla durum güncelleme
MaxxParaKazanım ve kullanım tekil işlem olarak loglanır
GüvenlikAPI anahtarı, imza ve idempotency zorunludur

Akış

Entegrasyonun çalışma modeli

Entegrasyonun amacı POS/kasa sistemini Maxxla’nın müşteri, web menü, sipariş ve MaxxPara akışlarıyla tutarlı hale getirmektir.

1. İşletme eşleştirme

Maxxla tarafındaki business_id ile POS/kasa tarafındaki mağaza veya şube kodu bire bir eşleştirilir.

2. Ürün ve fiyat aktarımı

POS sistemi ürün adı, kategori, fiyat, aktiflik ve stok/satış durumu bilgisini Maxxla’ya düzenli gönderir.

3. Sipariş oluşturma

Maxxla, web menü veya uygulama siparişini POS sistemine açar; POS sisteminden durum güncellemeleri geri alınır.

4. MaxxPara işlemi

Satış tamamlandığında kazanım veya kullanım bilgisi kuruş hassasiyetinde Maxxla’ya iletilir.

5. Mutabakat ve log

Her işlem tekil external_order_id ile izlenir; tekrar gönderimler idempotent kabul edilir.

Zorunlu Alanlar

Her entegrasyonda ortak veri sözlüğü

POS tarafı bu alanları doğru gönderirse sipariş, mutabakat ve MaxxPara süreçleri izlenebilir olur.

business_id

Maxxla işletme/şube ID’si.

external_store_id

POS/kasa tarafındaki mağaza veya şube kodu.

external_product_id

Ürün için POS tarafındaki tekil ID.

external_order_id

Sipariş veya fiş için POS tarafındaki tekil ID.

total_amount

İndirimlerden önce/sonra net satış tutarı; kuruş hassasiyetinde.

used_maxx_para

Müşterinin kullandığı MaxxPara tutarı. Yoksa 0.00 gönderilir.

earned_maxx_para

Satıştan kazanılan MaxxPara tutarı. Maxxla kural motoru hesaplıyorsa boş bırakılır.

status

Sipariş durumu: pending, confirmed, preparing, ready, out_for_delivery, delivered, cancelled.

API Örnekleri

POS ekibinin uygulayacağı temel istekler

Endpoint isimleri işletmeye verilen sandbox dokümanında netleştirilir. Aşağıdaki payload yapısı entegrasyonda beklenen veri mantığını gösterir.

Ürün/fiyat senkronizasyonu

POST /pos/products/sync
Authorization: Bearer <api_key>
Idempotency-Key: product-sync-2026-04-30-001

{
  "business_id": "maxxla-business-id",
  "external_store_id": "SUBE-001",
  "products": [
    {
      "external_product_id": "SKU-1001",
      "name": "Et Tantuni",
      "category": "Tantuni",
      "price": 270.00,
      "currency": "TRY",
      "is_active": true,
      "is_available": true,
      "barcode": "8690000000001"
    }
  ]
}

Sipariş durum güncelleme

POST /pos/orders/status
Authorization: Bearer <api_key>
Idempotency-Key: order-status-ORD-123-ready

{
  "business_id": "maxxla-business-id",
  "external_order_id": "POS-FIS-123",
  "maxxla_order_id": "maxxla-order-id",
  "status": "ready",
  "updated_at": "2026-04-30T14:30:00+03:00"
}

MaxxPara kazanım bildirimi

POST /pos/maxx-para/earn
Authorization: Bearer <api_key>
Idempotency-Key: earn-POS-FIS-123

{
  "business_id": "maxxla-business-id",
  "external_order_id": "POS-FIS-123",
  "customer_phone": "05XXXXXXXXX",
  "total_amount": 245.00,
  "earned_maxx_para": 12.25,
  "description": "Sipariş #POS-FIS-123 ile kazanıldı"
}

MaxxPara kullanım bildirimi

POST /pos/maxx-para/redeem
Authorization: Bearer <api_key>
Idempotency-Key: redeem-POS-FIS-124

{
  "business_id": "maxxla-business-id",
  "external_order_id": "POS-FIS-124",
  "customer_id": "maxxla-customer-id",
  "gross_total": 200.00,
  "used_maxx_para": 60.00,
  "grand_total": 140.00
}

Güvenlik

Teknik kurallar

Canlı entegrasyonda API anahtarı, imza ve idempotency olmadan işlem alınmaz.

  • API anahtarı sunucu tarafında saklanır; mobil istemciye veya tarayıcıya gömülmez.
  • Her write isteğinde `Idempotency-Key` gönderilir.
  • Tutarlar `12.25` formatında ve TRY para birimiyle gönderilir.
  • İptal/iade işlemleri ayrı ters kayıt olarak gönderilir; geçmiş kayıt silinmez.
  • Maxxla, MaxxPara kazanma ve kullanma kayıtlarını platform logu olarak saklar; ticari sorumluluk işletme ile müşteri arasındaki alışveriştedir.

Webhook imza kontrolü

X-Maxxla-Signature: sha256=<hex_digest>
X-Maxxla-Timestamp: 1777520000

signature = HMAC_SHA256(
  secret,
  timestamp + "." + raw_request_body
)

Test Planı

Canlıya çıkmadan önce geçilecek checklist

Bu liste tamamlanmadan entegrasyonu canlı işletmeye açmayız. Böylece kasa, sipariş ve MaxxPara kayıtları kuruşu kuruşuna tutar.

✓

Test işletmesi ve test API anahtarı alınır.

✓

Ürün listesi en az bir kategori ve bir aktif ürünle senkronize edilir.

✓

Paket servis, gel-al ve masaya servis siparişi ayrı ayrı test edilir.

✓

Tamamı kart/nakit, kısmi MaxxPara ve tamamı MaxxPara kullanım senaryoları denenir.

✓

Aynı external_order_id iki kez gönderildiğinde çift kayıt oluşmadığı doğrulanır.

✓

İptal ve iade durumunda MaxxPara kazanım/kullanım ters kayıtları kontrol edilir.

✓

Canlıya geçmeden önce son 20 test işlemi Maxxla ekibiyle mutabık kalınır.

Teknik ekibinizle 30 dakikalık başlangıç görüşmesi yapalım.

İşletme tipinizi, POS/kasa altyapınızı ve sipariş akışınızı birlikte netleştirip sandbox bilgilerini paylaşalım.

destek@maxxla.com.trWhatsApp’tan Yaz