Skip to content

Partner API — Code redeem history

Read the code redeem history (lịch sử nhập mã) of one tenant: every redeemed (USED) code across all brands, newest redeem first — which code, how many EP it credited, who redeemed it, and when. Use it to reconcile code campaigns against your own records. This is a read-only Partner API, authenticated with a per-request HMAC-SHA256 signature — no JWT, no cookies.

GET /voting/api/v1/partner/ep/code-redeems

How this differs from the other partner reads

Section titled “How this differs from the other partner reads”
EndpointScopeAnswers
…/ep/code-redeems ⭐tenant”Which codes were redeemed in the tenant, by whom, when?”
…/ep/webhook/awardstenant”What did I award via the webhook?”
…/ep/wallet-transactionsone user”What is the full EP statement of that user?”
https://<host>/voting/api
EnvironmentHost
Stagingprovided to you separately
Productionprovided to you separately

The full URL is https://<host>/voting/api/v1/partner/ep/code-redeems.

Every request carries three headers:

HeaderValue
X-Api-KeyYour apiKeyId.
X-TimestampCurrent time in Unix epoch milliseconds, within ±5 minutes of server time.
X-Signaturehex( HMAC_SHA256( secret, "{X-Timestamp}.{queryString}" ) ).

{queryString} is the exact query string you send (everything after ?, already URL-encoded, in the same order). The signature binds every query parameter — unlike the award history endpoint, which signs only tenantId:

queryString = "tenantId=OQAGl0&limit=50&email=user%40example.com" // exactly as sent
X-Signature = hex( HMAC_SHA256( secret, X-Timestamp + "." + queryString ) )

Returns redeemed codes in a tenant, newest redeem first, paginated by page number.

ParamRequiredTypeDefaultDescription
tenantIdyesstring—Tenant to read. Must be in your allowed tenants.
batchIdnostring—Only codes minted in this batch.
emailnostring—Only codes redeemed by this user (exact; normalized to lowercase).
fromnostring—ISO-8601 datetime. Include rows with redeemedAt >= from (inclusive).
tonostring—ISO-8601 datetime. Include rows with redeemedAt <= to (inclusive). Must be >= from.
limitnonumber20Page size. Max 100.
pagenonumber11-based page index.

A date-only value (e.g. 2026-07-01) is read as that instant at UTC midnight — pass a full datetime to bound within a day.

Terminal window
# 1) Build the EXACT query string you will send
QS="tenantId=OQAGl0&limit=20&page=1"
# 2) Fresh timestamp (epoch ms) + signature over "${TS}.${QS}"
SECRET="<your-secret>"
TS=$(($(date +%s)*1000))
SIG=$(printf "%s.%s" "$TS" "$QS" | openssl dgst -sha256 -hmac "$SECRET" | awk '{print $NF}')
# 3) Send it — pass ?$QS verbatim (do NOT use -G/--data-urlencode)
curl "https://<host>/voting/api/v1/partner/ep/code-redeems?${QS}" \
-H "X-Api-Key: <your-api-key-id>" \
-H "X-Timestamp: ${TS}" \
-H "X-Signature: ${SIG}"
{
"tenantId": "OQAGl0",
"items": [
{
"code": "TPB040F14MAU9X",
"points": 2,
"brandId": "BRAND_X4UIEwj2",
"batchId": "BATCH_oKyTcse4",
"batchName": "Chiến dịch tháng 7",
"userEmail": "user@example.com",
"redeemedAt": "2026-07-14T02:22:47.720Z"
}
],
"page": 1,
"limit": 20,
"totalItems": 1951,
"totalPages": 98
}

Newest redeem first.

FieldTypeDescription
codestringThe redeemed code.
pointsnumberEP credited to the user by this code.
brandIdstring | nullBrand that issued the code (the feed spans all brands in the tenant).
batchIdstring | nullBatch the code was minted in.
batchNamestring | nullHuman-readable batch name.
userEmailstringWho redeemed it (normalized email).
redeemedAtstringISO-8601 redeem time. Items are sorted by this, newest first.
FieldTypeDescription
tenantIdstringEchoes the request.
pagenumberCurrent page (echoes the request, 1-based).
limitnumberPage size (echoes the request, after clamping).
totalItemsnumberTotal rows matching the filter, across all pages.
totalPagesnumberceil(totalItems / limit). A page past the end returns an empty items.

Returned with a real HTTP status and a stable string code. Branch on code, not on message (the message is human-readable Vietnamese and may change):

{ "code": "TENANT_NOT_ALLOWED", "message": "Tenant không được phép" }
HTTPcodeCauseWhat to do
401INVALID_SIGNATUREMissing/invalid signature, or unknown X-Api-Key.Verify you signed the exact query string you sent (order + URL-encoding).
401TIMESTAMP_OUT_OF_RANGEX-Timestamp not within ±5 minutes of server time.Sync your clock (NTP), resend with a fresh timestamp.
403PARTNER_SUSPENDEDYour partner account is suspended.Contact Eventista.
403TENANT_NOT_ALLOWEDThe requested tenantId is not in your allowed tenants.Check tenantId; contact Eventista to enable it.
503UNAVAILABLEThe backing read store is temporarily unavailable.Retry with backoff.

Retry only 503 UNAVAILABLE and network errors — the 4xx codes above will not fix themselves.

Invalid/missing query parameters (e.g. missing tenantId, from > to, a non-ISO date) return HTTP 200 with a non-zero errorCode — this differs from the auth errors above:

{
"errorCode": 100400,
"message": "Dữ liệu không hợp lệ",
"data": { "params": [ { "path": "tenantId", "message": "tenantId bắt buộc" } ] }
}
const crypto = require("crypto");
const BASE_URL = "https://<host>/voting/api";
const API_KEY_ID = "<your-api-key-id>";
const SECRET = "<your-secret>";
async function listCodeRedeems(params) {
const queryString = new URLSearchParams(params).toString(); // exact string to sign + send
const timestamp = Date.now().toString();
const signature = crypto
.createHmac("sha256", SECRET)
.update(`${timestamp}.${queryString}`)
.digest("hex");
const res = await fetch(
`${BASE_URL}/v1/partner/ep/code-redeems?${queryString}`,
{
headers: {
"X-Api-Key": API_KEY_ID,
"X-Timestamp": timestamp,
"X-Signature": signature,
},
},
);
const data = await res.json();
if (!res.ok || data.errorCode) {
throw new Error(`code-redeems failed [${res.status}] ${data.code ?? data.errorCode}: ${data.message}`);
}
return data; // { tenantId, items, page, limit, totalItems, totalPages }
}
// Page through everything redeemed in July.
async function redeemsInJuly(tenantId) {
const all = [];
let page = 1;
let totalPages = 1;
do {
const res = await listCodeRedeems({
tenantId,
from: "2026-07-01T00:00:00Z",
to: "2026-07-31T23:59:59Z",
limit: "100",
page: String(page),
});
all.push(...res.items);
totalPages = res.totalPages;
page += 1;
} while (page <= totalPages);
return all;
}
import hashlib, hmac, time
from urllib.parse import urlencode
import requests
BASE_URL = "https://<host>/voting/api"
API_KEY_ID = "<your-api-key-id>"
SECRET = "<your-secret>"
def list_code_redeems(params: dict):
query_string = urlencode(params) # exact string to sign + send
timestamp = str(int(time.time() * 1000))
signature = hmac.new(
SECRET.encode(), f"{timestamp}.{query_string}".encode(), hashlib.sha256
).hexdigest()
# Append the pre-built query string to the URL (do NOT pass params= here).
url = f"{BASE_URL}/v1/partner/ep/code-redeems?{query_string}"
resp = requests.get(
url,
headers={
"X-Api-Key": API_KEY_ID,
"X-Timestamp": timestamp,
"X-Signature": signature,
},
)
data = resp.json()
if not resp.ok or data.get("errorCode"):
raise RuntimeError(f"code-redeems failed [{resp.status_code}]: {data}")
return data # { tenantId, items, page, limit, totalItems, totalPages }
print(list_code_redeems({"tenantId": "OQAGl0", "limit": 100, "page": 1}))

Add this as a Pre-request Script (request or collection level). It recomputes the timestamp and signature from the request’s actual query string on every Send, so you can change page/limit/filters freely in the Params tab:

const SECRET = pm.environment.get("EP_PARTNER_SECRET"); // keep the secret in an environment
const qs = pm.request.url.getQueryString(); // the exact string that will be sent
const ts = Date.now().toString();
const sig = CryptoJS.HmacSHA256(`${ts}.${qs}`, SECRET).toString(CryptoJS.enc.Hex);
pm.request.headers.upsert({ key: "X-Timestamp", value: ts });
pm.request.headers.upsert({ key: "X-Signature", value: sig });

Set X-Api-Key as a normal header. Values with special characters (e.g. email) must be URL-encoded in the Params tab (a@b.com → a%40b.com) — getQueryString() returns the string exactly as sent, so the signature always matches.

  • Build the query string yourself; sign that exact string; send it verbatim.
  • X-Timestamp is epoch milliseconds, regenerated per request (±5 min window).
  • X-Signature is lowercase hex of HMAC-SHA256 over "{timestamp}.{queryString}".
  • tenantId is one of your allowed tenants; keep the secret server-side only.
  • Page with page = 1 … totalPages; for exact reconciliation, pin a from/to window first.
  • Treat 4xx (code) and 200 with a non-zero errorCode both as failures.
  • Retry only 503 UNAVAILABLE / network errors, with backoff.
  • Remember the feed lags real time by a few seconds — don’t alarm on a just-redeemed code missing.