# Creative

Feed creative cung cấp cho hệ thống marketing của bạn một bản ghi dữ liệu lâu dài cho mỗi ad creative mà tổ chức của bạn đã duyệt trên Wandura. Mỗi bản ghi cho biết creative là gì: phim, các tập và cảnh được dùng, định dạng và thời lượng, hook, formula dùng để dựng, và thời điểm quyền sử dụng phim của bạn kết thúc. Hệ thống của bạn lưu các bản ghi này và tự quyết định dùng creative nào, dùng thế nào.

## Feed chứa gì

Feed trả về các creative thuộc tổ chức của bạn có status `approved` hoặc `pushed` (đã giao). Creative ở status khác, ví dụ bản nháp, không được đưa vào. Creative của tổ chức khác không bao giờ hiện ra.

Bản ghi không bao giờ chứa URL media. Feed mô tả creative; file video hoàn chỉnh không được giao qua API này. Hãy hỏi Wandura file hoàn chỉnh đến hệ thống của bạn bằng cách nào.

`final.ready` cho biết bản render hoàn chỉnh của creative đã có chưa.

## Endpoint

| Endpoint | Dùng để |
|---|---|
| [`GET /api/delivery/v1/creatives`](https://docs.wandura.ai/vi/developers/reference/creatives-list) | Đồng bộ mọi bản ghi, theo kiểu incremental. |
| [`GET /api/delivery/v1/creatives/{id}`](https://docs.wandura.ai/vi/developers/reference/creatives-get) | Lấy hoặc kiểm tra lại một bản ghi. |

Cả hai đều cần key có scope `creatives:export`, bạn tự tạo được trên trang **Developers** của partner portal. Xem [Xác thực](https://docs.wandura.ai/vi/developers/authentication).

## Envelope của response

Khác với endpoint catalog và playback, endpoint creatives bọc mọi response trong một envelope:

```json
{
  "code": 0,
  "message": "ok",
  "data": { "items": [], "next_cursor": null },
  "server_time": 1790679032
}
```

`code` là `0` khi thành công và là mã lỗi bốn chữ số trong trường hợp khác. Timestamp trong feed này, kể cả `server_time`, tính bằng giây Unix epoch. Xem [Lỗi](https://docs.wandura.ai/vi/developers/concepts/errors).

## Đồng bộ incremental
Bản ghi được trả về theo thứ tự cập nhật cũ nhất trước, sắp theo `updated_at` rồi theo ID, nên cập nhật mới không bao giờ làm xê dịch các trang bạn đã đọc.

1. **Lần đồng bộ đầu.** Gọi `GET /creatives?limit=100` không kèm `updated_since`. Chừng nào `data.next_cursor` chưa là `null`, gọi lại với `cursor=<next_cursor>`.
2. **Lưu checkpoint.** Giữ lại `updated_at` lớn nhất bạn nhận được.
3. **Các lần đồng bộ sau.** Gọi với `updated_since=<checkpoint>` và lại phân trang bằng `cursor`. Chỉ các bản ghi được cập nhật sau hẳn giây đó (`>`) được trả về.

```bash
curl -s "https://www.wandura.ai/api/delivery/v1/creatives?updated_since=1790600000&limit=100" \
  -H "Authorization: Bearer $WANDURA_API_KEY"
```

`updated_at` được làm tròn xuống theo giây, nên một bản ghi có thể xuất hiện lại ở lần đồng bộ sau. Hãy lưu bản ghi theo khoá `creative_id` và ghi đè khi trùng.

Coi giá trị `cursor` là opaque. Truyền lại đúng y như khi nhận.

### Creative rời khỏi feed

Feed không có sự kiện xoá. Nếu một creative không còn được duyệt, nó đơn giản là không xuất hiện nữa. Để xác nhận một creative đã lưu vẫn còn dùng được, gọi `GET /creatives/{id}`: endpoint trả `404` (`code` `4040`) cho creative không còn trong feed.

## Bản ghi

Các trường chính của một bản ghi được liệt kê bên dưới. Danh sách đầy đủ, kèm kiểu dữ liệu, nằm trong [tài liệu tham chiếu liệt kê creative](https://docs.wandura.ai/vi/developers/reference/creatives-list#the-creative-record).

| Trường | Cho bạn biết |
|---|---|
| `creative_id` | ID ổn định của creative. Dùng làm primary key. |
| `creative_code` | Mã đọc được của creative, không đổi. Coi nó là chuỗi opaque. |
| `film` | Mã phim, tên phim, ngôn ngữ và thể loại. |
| `episodes` | Số thứ tự các tập creative sử dụng. |
| `scenes` | Từng clip được dùng: số tập, điểm bắt đầu và kết thúc tính bằng mili giây, nhãn hành động và câu thoại. |
| `hook` | Nhãn hành động và câu thoại của cảnh mở đầu. |
| `placement`, `aspect` | Vị trí quảng cáo (`reels_9x16`, `feed_4x5` hoặc `square_1x1`) và tỉ lệ khung hình tương ứng. |
| `duration_ms` | Tổng độ dài các clip được dùng. |
| `formula` | Formula dùng để dựng creative, nếu có. |
| `rights.ends_at` | Ngày cuối cùng của quyền export phim (00:00 UTC của ngày đó), hoặc `null`. |
| `lineage.parent_creative_id` | Creative gốc mà creative này được phái sinh từ đó, nếu có. |
| `final.ready` | Bản render hoàn chỉnh đã có hay chưa. |

`rights.ends_at` là 00:00 UTC của ngày cuối cùng trong quyền export phim. Ngày đó vẫn được dùng: ngừng dùng creative sau khi ngày UTC đó kết thúc, tức tại `ends_at + 86400`.

## Phiên bản

Mỗi bản ghi mang `schema_version`, hiện là `1`. Trường mới có thể được thêm vào mà không đổi giá trị này, nên hãy bỏ qua các trường bạn không nhận ra.

## Rate limit

Hai endpoint creatives dùng chung một bộ đếm rate limit, tách riêng khỏi catalog. Đồng bộ vài lần mỗi giờ vẫn còn cách xa ngưỡng này. Xem [Rate limit](https://docs.wandura.ai/vi/developers/concepts/rate-limits).