# Creative

> **TL;DR** — Creatives feed đưa cho hệ thống marketing của bạn một bản ghi dữ liệu cho mỗi creative quảng cáo mà tổ chức của bạn đã duyệt trên Wandura: phim, các tập và cảnh được dùng, định dạng, thời lượng, hook, formula và ngày hết quyền của bạn. Bản ghi không bao giờ chứa URL media. Đồng bộ dần bằng `updated_since` và cursor.

## Feed chứa gì
Các creative của tổ chức bạn có trạng thái `approved` hoặc `pushed` (đã giao). Bản nháp và creative của tổ chức khác không bao giờ xuất hiện. `final.ready` cho biết bản dựng cuối đã có chưa. File video cuối không được giao qua API này: hãy hỏi Wandura cách chúng tới hệ thống của bạn.

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

Cả hai cần key có `creatives:export` ([Xác thực](https://docs.wandura.ai/vi/v1/developers/authentication#scopes)) và dùng chung một bộ đếm rate limit.

## Envelope của response
Response thành công được bọc trong một envelope:

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

Lỗi dùng cùng envelope nhưng **không có** `data` (khi đó `code` là mã lỗi bốn chữ số), trừ `429` và `400` `unsupported_version`, hai lỗi này dùng định dạng phẳng. 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/v1/developers/concepts/errors#creatives-envelope).

## Đồng bộ
Bản ghi tới theo thứ tự cập nhật cũ nhất trước (theo `updated_at`, rồi theo ID), nên các cập nhật xảy ra trong lúc đồng bộ sẽ nằm sau các trang bạn đã đọc. Giữ một checkpoint (`updated_at` lớn nhất của lần chạy trọn vẹn gần nhất), gửi nó làm `updated_since`, lật trang bằng `cursor`, và ghi đè bản ghi theo `creative_id`: một bản ghi có thể tới hai lần. Quy trình đầy đủ và code: [Đồng bộ creative](https://docs.wandura.ai/vi/v1/developers/guides/creatives-sync).

### Creative rời khỏi feed
Không có sự kiện xoá. Creative không còn được duyệt thì thôi xuất hiện. Để kiểm tra một creative bạn đã lưu, gọi `GET /creatives/{id}`: `404` với `code` `4040` nghĩa là nó đã không còn.

## Bản ghi
| Trường | Cho bạn biết gì |
|---|---|
| `creative_id` | ID ổn định. Khoá chính của bạn. |
| `creative_code` | Mã cho người đọc, không bao giờ đổi; coi nó là chuỗi opaque. |
| `film`, `episodes`, `scenes` | Creative được làm từ gì: phim, số tập, từng clip với điểm đầu, điểm cuối, hành động và lời thoại. |
| `hook` | Hành động và lời thoại của cảnh mở đầu. |
| `placement`, `aspect` | `reels_9x16`, `feed_4x5` hoặc `square_1x1`, và tỉ lệ khung hình. |
| `duration_ms` | Tổng thời lượng các clip được dùng. |
| `formula` | Formula được dùng để dựng, nếu có. |
| `rights.ends_at` | 00:00 UTC của **ngày cuối cùng** bạn có quyền xuất, hoặc `null`. Ngày đó vẫn được tính: ngừng dùng creative từ `ends_at + 86400`. |
| `final.ready` | Bản dựng cuối đã có chưa. |

Mọi trường: [Liệt kê creative](https://docs.wandura.ai/vi/v1/developers/reference/creatives-list#the-creative-record). Mỗi bản ghi mang `schema_version` (hiện là `1`); trường mới được thêm mà không đổi số này, nên hãy bỏ qua các trường bạn không nhận ra.

## Liên quan
- [Đồng bộ creative](https://docs.wandura.ai/vi/v1/developers/guides/creatives-sync)
- [Khi quyền kết thúc](https://docs.wandura.ai/vi/v1/developers/production/rights-end)