# 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**

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

#### Example Response

```json
[
  {
    "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": "+84123456789"
  }
]
```

***

### **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**

```json
[
  {
    "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**

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