# 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 đã ký. Đồng bộ dần bằng `updated_since` và cursor. `final.file_url` của mỗi bản ghi là link chia sẻ công khai tới video cuối: không cần API key, nên đưa thẳng cho video upload của Meta được.

## 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; có rồi thì [tải về](https://docs.wandura.ai/vi/developers/concepts/creatives#downloading-the-final-file) từ `final.file_url`.

## 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, từng phần một. |
| [`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. |
| [`GET /api/delivery/v1/creatives/{id}/file`](https://docs.wandura.ai/vi/developers/reference/creatives-file) | Tải video cuối bằng API key, thay cho link chia sẻ trong `final.file_url`. |

Cả ba cần key có `creatives:export` ([Xác thực](https://docs.wandura.ai/vi/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/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/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. |
| `created_by` | Ai đã làm creative: `email`, và `name` (hoặc `null` khi người đó chưa đặt tên). `null` khi không xác định được người tạo, ví dụ creative do hệ thống tạo. |
| `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. |
| `final.file_url` | Link tải công khai, bền (không cần API key), thu hồi được trên portal; mỗi lần mở chuyển hướng tới link tải mới dùng được 15 phút. Đưa thẳng cho video upload của Meta được. `null` cho tới khi `final.ready` là `true`, và `null` khi admin của tổ chức bạn đã thu hồi link. File là bản cuối sạch, có brand mark của công ty bạn nếu tổ chức bạn có. |

Mọi trường: [Liệt kê creative](https://docs.wandura.ai/vi/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.

## Tải file cuối
Khi `final.ready` là `true`, `final.file_url` là [link chia sẻ](https://docs.wandura.ai/vi/partners/creatives#share-link) của creative, ví dụ `https://www.wandura.ai/api/c/Q3vh0xAbCdEfGhIjKlMnOpQrStUvWx9f.mp4`. Link không cần API key. Mỗi lần mở trả `302` kèm link tải mới dùng được 15 phút, nên công cụ tải file bằng URL, như video upload của Meta (`file_url`), dùng thẳng được, dù khâu lên chiến dịch của bạn kéo dài bao lâu:

```bash
curl -sL -o final.mp4 "$FILE_URL"
```

- Lưu `final.file_url`, đừng lưu link tải mà nó chuyển tới: link tải hết hạn sau 15 phút, link chia sẻ thì không.
- Ai cầm link chia sẻ cũng tải được file. Giữ nó như mật khẩu: đừng công bố.
- Mỗi lần mở đều kiểm lại creative còn được duyệt và quyền xuất phim của bạn còn hiệu lực; không thì trả `410`. Admin của tổ chức bạn thu hồi được link trên portal, và link trả `410` ngay.
- Sau khi thu hồi, `final.file_url` của bản ghi là `null`. Thu hồi không đổi `updated_at`, nên đồng bộ dần không thấy thay đổi này: khi một link đã lưu trả `410`, gọi [Lấy một creative](https://docs.wandura.ai/vi/developers/reference/creatives-get) để lấy link hiện tại. Vẫn `null`? Hỏi admin của bạn, hoặc tạo link chia sẻ mới trên portal.
- Mỗi link mở được 120 lần mỗi phút; quá mức đó trả `429` kèm `Retry-After`.
- File là MP4, 1080 × 1920: bản cuối sạch, có brand mark của công ty bạn nếu tổ chức bạn có.

### Tải bằng API key
[`GET /api/delivery/v1/creatives/{id}/file`](https://docs.wandura.ai/vi/developers/reference/creatives-file) tải cùng file đó bằng API key thay cho link chia sẻ. Nó trả `302` kèm link tải dùng được 15 phút; phần lớn HTTP client tự đi theo:

```bash
curl -sL -o final.mp4 "https://www.wandura.ai/api/delivery/v1/creatives/$CREATIVE_ID/file" -H "Authorization: Bearer $WANDURA_API_KEY"
```

- `409` với `code` `4090` nghĩa là bản cuối chưa sẵn sàng. Sau khi quyền xuất của bạn hết, endpoint trả `403` với `code` `4032`.
- Mỗi lần tải đều được ghi nhật ký theo API key của bạn. Lộ key thì thu hồi ngay: tới lúc đó, key tải được mọi bản cuối của tổ chức bạn.

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