Lịch sử thay đổi
Mọi lần sửa trang này, mới nhất ở trên. Mở từng mục để xem đã đổi gì.
- 02/10/2026 · +28 −53 dòng
Xem thay đổi
# 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. + > **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. - 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. + ## Feed chứa gì {#what-the-feed-contains} - `final.ready` cho biết bản render hoàn chỉnh của creative đã có chưa. + 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 {#endpoints} | Endpoint | Dùng để | |---|---| - | [`GET /api/delivery/v1/creatives`](../reference/creatives-list.md) | Đồng bộ mọi bản ghi, theo kiểu incremental. | + | [`GET /api/delivery/v1/creatives`](../reference/creatives-list.md) | Đồng bộ mọi bản ghi, từng phần một. | | [`GET /api/delivery/v1/creatives/{id}`](../reference/creatives-get.md) | 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](../authentication.md). + Cả hai cần key có `creatives:export` ([Xác thực](../authentication.md#scopes)) và dùng chung một bộ đếm rate limit. - ## Envelope của response + ## Envelope của response {#response-envelope} - Khác với endpoint catalog và playback, endpoint creatives bọc mọi response trong một envelope: + Response thành công được bọc trong một envelope: ```json ⋯ ``` - `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](errors.md). - - ## Đồng bộ incremental {#syncing-incrementally} - - 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. + 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](errors.md#creatives-envelope). - Coi giá trị `cursor` là opaque. Truyền lại đúng y như khi nhận. + ## Đồng bộ {#syncing-incrementally} - ### Creative rời khỏi feed + 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](../guides/creatives-sync.md). - 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. + ### Creative rời khỏi feed {#creatives-that-leave-the-feed} - ## Bản ghi + 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. - 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](../reference/creatives-list.md#the-creative-record). + ## Bản ghi {#the-record} - | Trường | Cho bạn biết | + | Trường | Cho bạn biết gì | |---|---| - | `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 + | `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 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. + Mọi trường: [Liệt kê creative](../reference/creatives-list.md#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. - ## Rate limit + ## Liên quan {#related} - 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](rate-limits.md). + - [Đồng bộ creative](../guides/creatives-sync.md) + - [Khi quyền kết thúc](../production/rights-end.md)
- 01/10/2026 · +1 −1 dòng
Xem thay đổi
⋯ ## Rate limit - Endpoint creatives dùng chung một bộ đếm rate limit với endpoint catalog. Đồng bộ vài lần mỗi giờ vẫn còn cách xa ngưỡng này. Xem [Rate limit](rate-limits.md). + 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](rate-limits.md).
- 01/10/2026 · +3 −3 dòng
Xem thay đổi
⋯ 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 thời điểm đó được trả về. + 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 ⋯ | `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` | Thời điểm quyền export phim của bạn kết thúc, hoặc `null`. | + | `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` đánh dấu ngày cuối cùng của quyền export phim. Hãy ngừng dùng creative khi ngày đó đã qua. + `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 ⋯
- 01/10/2026 · +1 −1 dòng
Xem thay đổi
⋯ 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 đầu mối đối tác Wandura của bạn file hoàn chỉnh đến hệ thống của bạn bằng cách nào. + 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. ⋯
- 29/09/2026 · Tạo trang