# Tham chiếu Render API

Endpoint, header xác thực và các trường dữ liệu của Render API.

## Authentication
Dùng header `ApiKey` với key thuộc project có scope `template:render`. Đây không phải session của web app.

## POST /v1/pdf/render
| Trường JSON | Ý nghĩa |
| --- | --- |
| `template_id` | Bắt buộc, UUID của template; không thay bằng slug |
| `version` | Số version; khi không chỉ rõ, dùng current version của template |
| `variant` | Tên variant nếu muốn chọn |
| `parameters` | Object dữ liệu theo khai báo template |

Version được chọn phải published. Render thật dùng nội dung đã commit của version, không dùng các thay đổi chưa lưu trên trình duyệt.

Thành công tiếp nhận: HTTP 202 và `render_id`, `status: queued`, `status_url`. Response này không chứa bytes PDF. Request được nhận không bảo đảm render cuối cùng thành công.

## GET /v1/renders/{render_id}
Dùng cùng header key. Response có `render_id`, `status` và các thông tin kết quả có thể có như `error_message`, `duration_ms`, `download_url`. Trạng thái xử lý là `pending`; terminal states là `success`, `failed`, `quota_exceeded`.

Ngay sau response 202, endpoint status có thể trả **404 tạm thời** trong lúc workflow tạo bản ghi lịch sử. Đợi ngắn rồi hỏi lại đúng render ID vừa được nhận, với giới hạn thời gian. Nếu 404 kéo dài, ID không đúng hoặc key khác project, cần kiểm tra lại; không gửi lại POST chỉ vì lần hỏi status đầu trả 404.

## GET /v1/renders/{render_id}/download
Dùng cùng header key và project phù hợp. Khi output tồn tại, nhận nội dung PDF. Không gọi đây là public permanent URL; output còn chịu quyền và retention.

## Lỗi và retry
Lỗi xác thực, sai project, template/version không tồn tại hoặc chưa publish có thể được trả trước khi nhận job. Lỗi xử lý sau tiếp nhận cần đọc qua status. Không retry mọi 4xx; sửa request/quyền trước. Không giả định POST render có idempotency key công khai.

## Response lỗi
Lỗi dùng `code`, `description` và `details` khi có. Đọc code để chọn cách xử lý. Job đã được nhận vẫn có thể lỗi sau đó, với `error_message` qua endpoint status.

```json
{"code":"PDF_TEMPLATE_VERSION_NOT_PUBLISHED","description":"template version is not published","details":[]}
```

Ví dụ status thành công:

```json
{"render_id":"<render-uuid>","status":"success","duration_ms":1200,"download_url":"/v1/renders/<render-uuid>/download"}
```

Lỗi trong quá trình xử lý là một kết quả status, ví dụ:

```json
{"render_id":"<render-uuid>","status":"failed","error_message":"Failed to compile template"}
```

## Phạm vi tài liệu
Reference này dành cho ba endpoint render public, không công bố mọi API session quản lý mà web app sử dụng. Khi triển khai polling, đặt khoảng nghỉ và deadline; giữ render ID sau khi yêu cầu được nhận.