17. API Redeem Voucher

This API is served by the Background Service via the API Ring router.

---

Endpoint

• Base Path: {API_PREFIX}/history-coupon-code

• Method: GET

• Headers: apikey: <your-api-key>

---

Query Parameters

Param	Description
code(optional)	Exact coupon code to search.
coupon(optional)	Coupon program ID (coupon._id).
createdAtRangeFrom(optional)	Inclusive start time in epoch milliseconds.
createdAtRangeTo(optional)	Inclusive end time in epoch milliseconds.

If no date range is provided, the API returns all history records for the organization.

---

Response

Returns a list of history entries belonging to the caller's organization. All relational fields are populated.

Response Fields

Field	Description
id	History entry ID
code	Coupon code string
coupon	Populated coupon document (id, name, …)
contact	Populated contact document
createdBy	Populated user who sent the coupon
createdAt	Timestamp in milliseconds
coupon_code	Reference to the coupon code document
phoneSend	Phone number used to send the coupon
org	Organization ID

---

Example Request

GET /history-coupon-code?code=ABC123&createdAtRangeFrom=1709251200000&createdAtRangeTo=1711929599000
Authorization: Bearer <token>

Example Response

[
  {
    "id": "65f7c9f1e56c1c0012abcd34",
    "code": "ABC123",
    "coupon": { "id": "65f7c8aa...", "name": "Spring sale" },
    "contact": { "id": "64ff...", "name": "Nguyen Van A" },
    "createdBy": { "id": "63aa...", "firstname": "Sender" },
    "createdAt": 1710316800000,
    "phoneSend": "[phone]"
  }
]

---

Notes

• Requires a valid API Ring token; results are scoped to the org from apiRingSetting.

• Use pagination at the HTTP gateway if needed; the route currently returns all matched records.

---

---

GET /coupons

Endpoint

• Method: GET

• URL: /coupons

• Headers: apikey: <your-api-key>

---

Query Parameters

Param	Type	Required	Description
text	string	No	Search by name (supports regex + Vietnamese normalization).
dateNow	number	No	Filter coupons whose endTime is in the future or not set.
status	string	No	Time-based status filter: NOT_STARTED, IN_PROGRESS, ENDED.

status Rules

• NOT_STARTED → startTime not reached or not set

• IN_PROGRESS → active period (startTime ≤ now and endTime not passed)

• ENDED → endTime has passed

---

Example Response

[
  {
    "id": "64f0e9e4d3f8e71c12345678",
    "name": "Summer Sale",
    "normalize": "summer sale",
    "description": "20% off for summer campaign",
    "active": true,
    "createdBy": "63d1c93e1a2f9b0011223344",
    "createdAt": 1717113600000,
    "updatedAt": 1717200000000,
    "org": "62cbe6c0b23d890012345678",
    "startTime": 1717113600000,
    "endTime": 1719792000000,
    "permit": {
      "status": 2,
      "group": null,
      "users": []
    },
    "template": "Coupon template content",
    "typeDiscount": 1,
    "discount": 20,
    "maxDiscount": 500000
  }
]

---

---

GET /coupon-codes

Returns the list of actual coupon codes under a specific coupon program.

---

🔗 Endpoint

• Method: GET

• URL: /coupon-codes

• Headers: apikey: <your-api-key>

---

Query Parameters

Param	Type	Required	Description
coupon	string	Yes	Coupon program ID.
status	number	No	Filter by voucher status:
			0 – unused
			1 – used but still valid
			2 – exceeded limit / invalid

---

Example Response

[
  {
    "id": "64f0eb5ed3f8e71c22334455",
    "code": "SUMMER-ABC123",
    "org": "62cbe6c0b23d890012345678",
    "createdAt": 1717200000000,
    "limit": 3,
    "coupon": "64f0e9e4d3f8e71c12345678",
    "description": "Summer code batch",
    "status": 0,
    "countUsed": 0
  }
]