Kanallar ve işlemler
Kanal başına tek uç: POST /api/v1/{channelCode}/{operation}; örneğin transaction.create, campaign.inquiry ya da voucher.redeem.
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ş.
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.
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.
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,
});import hashlib, hmac, json, os, time, uuid
import requests
body = json.dumps({
"requestId": str(uuid.uuid4()),
"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"}],
}, separators=(",", ":"))
timestamp = str(int(time.time()))
signature = hmac.new(os.environ["INO_HMAC_SECRET"].encode(),
f"{timestamp}.{body}".encode(), hashlib.sha256).hexdigest()
res = requests.post(f"https://{host}/api/v1/MODERN_ECOM/transaction.create", data=body, headers={
"Content-Type": "application/json",
"X-Api-Key": os.environ["INO_API_KEY"],
"X-Timestamp": timestamp,
"X-Signature": signature,
})using System.Security.Cryptography;
using System.Text;
using System.Text.Json;
var body = JsonSerializer.Serialize(new {
requestId = Guid.NewGuid(),
orderNumber = "ORD-10482",
customerId = "6f0c2b1e-8a54-4d2e-9b9e-2f1d7c3a4b10",
cart = new {
currentTotal = "119.00", originalTotal = "119.00", totalDiscount = "0",
lineItems = new[] { new { lineNumber = 1, sku = "MR-DJ-001", qty = 1, unitPrice = "89.00", originalUnitPrice = "89.00" } },
},
payments = new[] { new { type = "CREDIT_CARD", amount = "119.00" } },
});
var timestamp = DateTimeOffset.UtcNow.ToUnixTimeSeconds().ToString();
using var hmac = new HMACSHA256(Encoding.UTF8.GetBytes(secret));
var signature = Convert.ToHexString(hmac.ComputeHash(Encoding.UTF8.GetBytes($"{timestamp}.{body}"))).ToLowerInvariant();
var request = new HttpRequestMessage(HttpMethod.Post, $"https://{host}/api/v1/MODERN_ECOM/transaction.create") {
Content = new StringContent(body, Encoding.UTF8, "application/json"),
};
request.Headers.Add("X-Api-Key", apiKey);
request.Headers.Add("X-Timestamp", timestamp);
request.Headers.Add("X-Signature", signature);Kanal başına tek uç: POST /api/v1/{channelCode}/{operation}; örneğin transaction.create, campaign.inquiry ya da voucher.redeem.
HMAC imzalı API anahtarı ya da OAuth2 client-credentials bearer token. Kanal bazında seçilir.
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.
HTTP durumu, makinenin okuyacağı bir kod ve yeniden denemenin güvenli olup olmadığıyla standart hata kataloğu.
Varsayılan olarak kanal başına dakikada 600 istek. Sınırı aşınca Retry-After ile 429 alırsınız.
v1 yalnız ekleme yoluyla değişir. Uyumu bozan bir değişiklik v2 olarak gelir; v1 için kapanış takvimi verilir.
Bir çağrıyı kendi kayıtlarınıza bağlamak için X-Correlation-Id gönderin; her yanıtta geri döner.
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.
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-idwebhook-timestampwebhook-signatureimport {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);
});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 completedtransaction.returnedReturn processedpoints
points.earnedPoints earnedpoints.adjustedPoints adjustedpoints.expiringPoints about to expirepoints.releasedPending points releasedpoints.expiredPoints expiredvoucher
voucher.issuedVoucher issuedvoucher.redeemedVoucher usedvoucher.redemption_reversedVoucher use reversedvoucher.cancelledVoucher cancelledvoucher.expiredVoucher expiredmember
member.registeredMember joinedmember.updatedMember profile updatedconsent
consent.changedContact permission changedtier
tier.changedTier changedtier.downgrade_scheduledTier downgrade scheduledtier.downgrade_cancelledTier downgrade cancelledsegment
segment.membership_changedSegment membership changedcampaign
campaign.changedCampaign changedjob
job.completedBulk job completedjob.failedBulk job failedWebhook yerine sorgulamayı tercih ederseniz olayları bir imleçle çekin.
Toplu işlemler iş olarak çalışır; durumu sorgulayın, satır hatalarıyla sonucu indirin.
Eski kasalar ve gün sonu işlemleri için işlem ya da puan düzeltmesi CSV'leri bırakın.
Biriktir ve gönder: gerçek satış zamanını gönderin, bağlantı gelince mutabakat yapın.
Olayları kendi sunucunuzda alın ya da işlemleri onun üzerinden gönderin.
Veri gölünüz için alışveriş ve müşteri verisinin artımlı Parquet aktarımı.
Ekibiniz için bir test kanalı kuruyor, entegrasyon sorularınızı yanıtlıyoruz.