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”| Endpoint | Scope | Answers |
|---|---|---|
…/ep/code-redeems ⭐ | tenant | ”Which codes were redeemed in the tenant, by whom, when?” |
…/ep/webhook/awards | tenant | ”What did I award via the webhook?” |
…/ep/wallet-transactions | one user | ”What is the full EP statement of that user?” |
Base URL
Section titled “Base URL”https://<host>/voting/api| Environment | Host |
|---|---|
| Staging | provided to you separately |
| Production | provided to you separately |
The full URL is https://<host>/voting/api/v1/partner/ep/code-redeems.
Authentication (summary)
Section titled “Authentication (summary)”Every request carries three headers:
| Header | Value |
|---|---|
X-Api-Key | Your apiKeyId. |
X-Timestamp | Current time in Unix epoch milliseconds, within ±5 minutes of server time. |
X-Signature | hex( 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 sentX-Signature = hex( HMAC_SHA256( secret, X-Timestamp + "." + queryString ) )Request
Section titled “Request”Returns redeemed codes in a tenant, newest redeem first, paginated by page number.
| Param | Required | Type | Default | Description |
|---|---|---|---|---|
tenantId | yes | string | — | Tenant to read. Must be in your allowed tenants. |
batchId | no | string | — | Only codes minted in this batch. |
email | no | string | — | Only codes redeemed by this user (exact; normalized to lowercase). |
from | no | string | — | ISO-8601 datetime. Include rows with redeemedAt >= from (inclusive). |
to | no | string | — | ISO-8601 datetime. Include rows with redeemedAt <= to (inclusive). Must be >= from. |
limit | no | number | 20 | Page size. Max 100. |
page | no | number | 1 | 1-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.
Example
Section titled “Example”# 1) Build the EXACT query string you will sendQS="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}"Response — 200 OK
Section titled “Response — 200 OK”{ "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}items[]
Section titled “items[]”Newest redeem first.
| Field | Type | Description |
|---|---|---|
code | string | The redeemed code. |
points | number | EP credited to the user by this code. |
brandId | string | null | Brand that issued the code (the feed spans all brands in the tenant). |
batchId | string | null | Batch the code was minted in. |
batchName | string | null | Human-readable batch name. |
userEmail | string | Who redeemed it (normalized email). |
redeemedAt | string | ISO-8601 redeem time. Items are sorted by this, newest first. |
Top level
Section titled “Top level”| Field | Type | Description |
|---|---|---|
tenantId | string | Echoes the request. |
page | number | Current page (echoes the request, 1-based). |
limit | number | Page size (echoes the request, after clamping). |
totalItems | number | Total rows matching the filter, across all pages. |
totalPages | number | ceil(totalItems / limit). A page past the end returns an empty items. |
Errors
Section titled “Errors”Authentication / authorization
Section titled “Authentication / authorization”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" }| HTTP | code | Cause | What to do |
|---|---|---|---|
| 401 | INVALID_SIGNATURE | Missing/invalid signature, or unknown X-Api-Key. | Verify you signed the exact query string you sent (order + URL-encoding). |
| 401 | TIMESTAMP_OUT_OF_RANGE | X-Timestamp not within ±5 minutes of server time. | Sync your clock (NTP), resend with a fresh timestamp. |
| 403 | PARTNER_SUSPENDED | Your partner account is suspended. | Contact Eventista. |
| 403 | TENANT_NOT_ALLOWED | The requested tenantId is not in your allowed tenants. | Check tenantId; contact Eventista to enable it. |
| 503 | UNAVAILABLE | The backing read store is temporarily unavailable. | Retry with backoff. |
Retry only 503 UNAVAILABLE and network errors — the 4xx codes above will not fix
themselves.
Validation
Section titled “Validation”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" } ] }}Reference implementations
Section titled “Reference implementations”Node.js
Section titled “Node.js”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;}Python
Section titled “Python”import hashlib, hmac, timefrom urllib.parse import urlencodeimport 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}))Postman
Section titled “Postman”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 sentconst 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.
Checklist
Section titled “Checklist”- Build the query string yourself; sign that exact string; send it verbatim.
-
X-Timestampis epoch milliseconds, regenerated per request (±5 min window). -
X-Signatureis lowercase hex of HMAC-SHA256 over"{timestamp}.{queryString}". -
tenantIdis one of your allowed tenants; keep thesecretserver-side only. - Page with
page = 1 … totalPages; for exact reconciliation, pin afrom/towindow first. - Treat
4xx(code) and200with a non-zeroerrorCodeboth 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.