# 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
  }
]
```


---

# Agent Instructions: Querying This Documentation

If you need additional information that is not directly available in this page, you can query the documentation dynamically by asking a question.

Perform an HTTP GET request on the current page URL with the `ask` query parameter:

```
GET https://docs.antbuddy.com/huong-dan-tich-hop-api-team-technical-api-integration-guide-technical-team/antcrm/17.-api-redeem-voucher.md?ask=<question>
```

The question should be specific, self-contained, and written in natural language.
The response will contain a direct answer to the question and relevant excerpts and sources from the documentation.

Use this mechanism when the answer is not explicitly present in the current page, you need clarification or additional context, or you want to retrieve related documentation sections.