Geliştiriciler için

Ino Loyalty üzerine geliştirin

Kasanız, mağazanız ve uygulamalarınız için gerçek zamanlı bir API, olan her şey için imzalı webhook'lar ve eksiksiz bir OpenAPI referansı. Herkese açık belgelenmiş.

Üç adımda ilk isteğiniz

  1. 1

    Kimlik bilgilerinizi alın

    Kurulumda API adresinizi ve bir kanal kodu (örneğin MODERN_ECOM) alırsınız. BT yöneticiniz API anahtarını ve gizli anahtarı Ino Loyalty'nin Developers konsolunda oluşturur.

  2. 2

    İsteği imzalayın

    Her çağrı X-Api-Key, X-Timestamp (Unix saniye, 5 dakika içinde) ve X-Signature taşır: gizli anahtarla "{timestamp}.{ham gövde}" üzerinden HMAC-SHA256, küçük harf hex. Tam olarak gönderdiğiniz baytları imzalayın.

  3. 3

    Bir alışveriş kaydedin

    Sipariş ve liste fiyatlarıyla transaction.create çağırın. Ino Loyalty kampanyaları değerlendirir, puan kazandırır ya da harcatır ve sonucu döner.

import crypto from 'node:crypto';

const body = JSON.stringify({
  requestId: crypto.randomUUID(),
  orderNumber: 'ORD-10482',
  customerId: '6f0c2b1e-8a54-4d2e-9b9e-2f1d7c3a4b10',
  cart: {
    currentTotal: '119.00', originalTotal: '119.00', totalDiscount: '0',
    lineItems: [{lineNumber: 1, sku: 'MR-DJ-001', qty: 1, unitPrice: '89.00', originalUnitPrice: '89.00'}],
  },
  payments: [{type: 'CREDIT_CARD', amount: '119.00'}],
});
const timestamp = Math.floor(Date.now() / 1000).toString();
const signature = crypto
  .createHmac('sha256', process.env.INO_HMAC_SECRET)
  .update(`${timestamp}.${body}`)
  .digest('hex');

const res = await fetch(`https://${host}/api/v1/MODERN_ECOM/transaction.create`, {
  method: 'POST',
  headers: {
    'Content-Type': 'application/json',
    'X-Api-Key': process.env.INO_API_KEY,
    'X-Timestamp': timestamp,
    'X-Signature': signature,
  },
  body,
});

Bilmeniz gerekenler

Kanallar ve işlemler

Kanal başına tek uç: POST /api/v1/{channelCode}/{operation}; örneğin transaction.create, campaign.inquiry ya da voucher.redeem.

Kimlik doğrulama

HMAC imzalı API anahtarı ya da OAuth2 client-credentials bearer token. Kanal bazında seçilir.

İdempotent istekler

requestId tekrar anahtarınızdır: 24 saat içinde aynı istek ilk yanıtı döner; tekrar gönderim asla iki kez puan kazandırmaz.

Hatalar

HTTP durumu, makinenin okuyacağı bir kod ve yeniden denemenin güvenli olup olmadığıyla standart hata kataloğu.

İstek sınırı

Varsayılan olarak kanal başına dakikada 600 istek. Sınırı aşınca Retry-After ile 429 alırsınız.

Sürümleme

v1 yalnız ekleme yoluyla değişir. Uyumu bozan bir değişiklik v2 olarak gelir; v1 için kapanış takvimi verilir.

İzleme

Bir çağrıyı kendi kayıtlarınıza bağlamak için X-Correlation-Id gönderin; her yanıtta geri döner.

Ödeme güvenliği

Sorgularda kısa bir zaman aşımı kullanın ve ödemeyi asla engellemeyin: hata olursa liste fiyatlarını gösterin, işlemi sonra aynı requestId ile yeniden deneyin.

Webhook'lar

Sadakat olaylarını imzalı HTTP POST olarak alın. Ino Loyalty Standard Webhooks belirtimini izler; resmi kütüphaneler isteklerimizi tek çağrıyla doğrular.

webhook-id
Gönderim kimliği; her yeniden denemede aynıdır. Tekrarları ayıklamak için kullanın.
webhook-timestamp
İsteğin imzalandığı Unix saniye. 5 dakikadan eski olanları reddedin.
webhook-signature
"{id}.{timestamp}.{ham gövde}" üzerinden v1,<base64 HMAC-SHA256>. Gizli anahtar yenilenirken iki imza gelir; herhangi birini kabul edin.
  • En az bir kez teslim; abonelik içinde sıralı (elden geldiğince)
  • 10 saniyelik zaman aşımı; yalnız 2xx başarı sayılır
  • Yaklaşık altı buçuk gün boyunca, en çok 20 deneme
  • Durdurulan ya da askıya alınan abonelikler olayları biriktirmeye devam eder
  • Kısa bir kesintide değil, ancak 24 saat boyunca hata alınırsa askıya alınır
verify-webhook.js
import {Webhook} from 'standardwebhooks'; // npm i standardwebhooks (also for Python, .NET, Go, Java…)

const wh = new Webhook(process.env.INO_WEBHOOK_SECRET); // whsec_…

app.post('/ino-webhook', express.raw({type: 'application/json'}), (req, res) => {
  // Throws if the signature does not match or the timestamp is older than 5 minutes.
  const event = wh.verify(req.body, req.headers);
  // event.type, e.g. "points.earned"; deduplicate with req.headers['webhook-id']
  res.sendStatus(204);
});

Olay kataloğu

Her olay, sürümlü bir veri içeriğine sahip bir CloudEvents 1.0 zarfıdır. Örnek içerikler API referansında.

transaction

  • transaction.completedPurchase completed
  • transaction.returnedReturn processed

points

  • points.earnedPoints earned
  • points.adjustedPoints adjusted
  • points.expiringPoints about to expire
  • points.releasedPending points released
  • points.expiredPoints expired

voucher

  • voucher.issuedVoucher issued
  • voucher.redeemedVoucher used
  • voucher.redemption_reversedVoucher use reversed
  • voucher.cancelledVoucher cancelled
  • voucher.expiredVoucher expired

member

  • member.registeredMember joined
  • member.updatedMember profile updated

consent

  • consent.changedContact permission changed

tier

  • tier.changedTier changed
  • tier.downgrade_scheduledTier downgrade scheduled
  • tier.downgrade_cancelledTier downgrade cancelled

segment

  • segment.membership_changedSegment membership changed

campaign

  • campaign.changedCampaign changed

job

  • job.completedBulk job completed
  • job.failedBulk job failed

Bağlanmanın diğer yolları

Olay akışı

Webhook yerine sorgulamayı tercih ederseniz olayları bir imleçle çekin.

Asenkron işler

Toplu işlemler iş olarak çalışır; durumu sorgulayın, satır hatalarıyla sonucu indirin.

Dosyayla toplu aktarım

Eski kasalar ve gün sonu işlemleri için işlem ya da puan düzeltmesi CSV'leri bırakın.

Çevrimdışı kasa

Biriktir ve gönder: gerçek satış zamanını gönderin, bağlantı gelince mutabakat yapın.

Apache Kafka

Olayları kendi sunucunuzda alın ya da işlemleri onun üzerinden gönderin.

Veri aktarımı

Veri gölünüz için alışveriş ve müşteri verisinin artımlı Parquet aktarımı.

Test ortamı ya da yardım mı lazım?

Ekibiniz için bir test kanalı kuruyor, entegrasyon sorularınızı yanıtlıyoruz.

[email protected] adresine yazın

Anonim ziyaretçi

Ziyaretçi

Siteyi gezin, kısa bir oyun oynayın, XP ve puan kazanın. Kaşif seviyesine ulaşınca şirketiniz için ücretsiz 30 günlük Ino Loyalty POC'si açılır.

Puan Yağmuru oyna

Profiliniz bu tarayıcıda saklanır. Analiz çerezlerine izin verirseniz burada olanları adınız olmadan, anonim olarak sayarız.