Tài liệu API

Sinh khuôn bế bao bì tham số bằng HTTP: chọn mẫu, gửi ba số đo, nhận lại hình học đầy đủ — đường cắt, đường cấn, hệ kích thước, bình khuôn và file sản xuất. Cùng engine mà ứng dụng web đang dùng, không phải bản rút gọn.

Tổng quan

Mọi endpoint nhận và trả JSON UTF-8. Thân yêu cầu tối đa 256 KB. Đường dẫn công khai bắt đầu bằng /api/v1/.

Có ba nhóm quyền, phân biệt rõ ở từng endpoint bên dưới:

Chạy trong 3 phút

1. Lấy khoá — đăng nhập rồi tạo ở mục Khoá của tôi ngay trên trang này. Khoá hiện đúng một lần.
2. Sinh khuôn — gọi POST /api/v1/designs, nhận designId + bản xem trước.
3. Xuất file — đưa designId sang POST /api/v1/exports để lấy liên kết tải file sạch.

# Đặt khoá vào biến môi trường, đừng viết thẳng vào mã nguồn
export DIELINE_API_KEY="dlk_..."

curl -s __DL_GOC__/api/v1/designs \
  -H "Authorization: Bearer $DIELINE_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"templateId":"CORRUGATED-RSC","lengthMm":200,"widthMm":150,"heightMm":100,"flute":"C"}'

Xác thực

Gửi khoá ở header Authorization, dạng Bearer:

Authorization: Bearer dlk_xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx

Quy tắc về khoá

• Khoá bắt đầu bằng dlk_ — tiền tố cố định để nếu lỡ lọt vào log hay ảnh chụp màn hình thì còn nhận ra mà thu hồi.
• Máy chủ không lưu khoá gốc, chỉ lưu bản băm. Mất khoá thì không ai lấy lại được — kể cả chúng tôi. Hãy thu hồi và tạo khoá mới.
• Mỗi tài khoản giữ tối đa 10 khoá còn hiệu lực. Nên tách khoá theo từng hệ thống để thu hồi lẻ khi cần.
• Thu hồi có hiệu lực ngay lập tức, không có độ trễ cache.
• Tài khoản bị khoá thì mọi khoá của nó chết theo, không cần thu hồi từng cái.
• Gói hết hạn thì khoá tự rơi về quyền free — đi qua đúng một đường tính quyền với trình duyệt, không có ngoại lệ.

Khoá của tôi

Hạn mức & tính phí

Mỗi lời gọi có đo đếm trừ một lượt vào hạn mức ngày của tài khoản (theo giờ Việt Nam, GMT+7). Hạn mức dùng chung cho mọi khoá của cùng tài khoản; bộ đếm riêng từng khoá vẫn được ghi để bạn đối soát xem hệ thống nào tiêu bao nhiêu.

Bảng trên đọc thẳng từ cấu hình gói của máy chủ; xem giá tại trang Bảng giá.

Cái gì bị trừ lượt, cái gì không

• Bị trừ: mỗi lần POST /api/v1/designs hoặc POST /api/v1/imposition trả về 200.
• Không bị trừ: tham số sai (400), engine lỗi (5xx) — hỏng việc thì không thu tiền.
• Vẫn bị trừ: kết quả lấy từ bộ nhớ đệm. Bạn nhận đủ dữ liệu, nên vẫn tính một lượt.
• Tính riêng: POST /api/v1/exports trừ vào lượt xuất file, không trừ thêm lượt API — một việc không thu tiền hai lần.

Giới hạn tần suất

Danh sách endpoint

{ "ok": true, "service": "dieline-gateway", "version": "0.9.131" }

{ "templates": [
  { "id": "ECMA-A2020-0101",
    "family": "HOP_GIAY",
    "nameVi": "Hộp nắp cài hai đầu — hai nắp CÙNG mặt (ECMA A20.20.01.01)",
    "formulaId": "ecma-a20-workbook",
    "defaultDimensions": { "lengthMm": 100, "widthMm": 60, "heightMm": 150 } } ] }

Tham số theo họ mẫu

Tham số dùng chung

• showAdvancedDimensions — hiện đầy đủ tham số kỹ thuật lên bản vẽ, thay vì chỉ dài × rộng × cao.
• dimensionGroup — chỉ hiện một nhóm kích thước (thân, nắp trên, tai bụi, tai dán, đáy) cho đỡ rối.
• detailViews — thêm bản trích phóng to cho chi tiết nhỏ.
• advancedOverrides — ghi đè biến công thức, danh sách cho phép riêng theo từng mẫu.

Đọc kết quả trả về

Xuất file sạch

Ba bước, mỗi bước một lời gọi:

API=__DL_GOC__
AUTH="Authorization: Bearer $DIELINE_API_KEY"

# 1 — sinh khuôn, lấy designId
DESIGN=$(curl -s "$API/api/v1/designs" -H "$AUTH" -H "Content-Type: application/json" \
  -d '{"templateId":"CORRUGATED-RSC","lengthMm":200,"widthMm":150,"heightMm":100,"flute":"C"}' \
  | jq -r .designId)

# 2 — đổi lấy liên kết tải (hạn 60 giây, dùng một lần)
URL=$(curl -s "$API/api/v1/exports" -H "$AUTH" -H "Content-Type: application/json" \
  -d "{\"designId\":\"$DESIGN\",\"format\":\"PDF\"}" | jq -r .downloadUrl)

# 3 — tải NGAY, đừng để dành
curl -s "$API$URL" -o khuon.pdf

Mã lỗi

Mọi lỗi cùng một khuôn:

{ "error": { "code": "API_QUOTA_EXCEEDED",
            "messageVi": "Hết hạn mức gọi API hôm nay — nâng gói hoặc quay lại ngày mai." } }

Bẫy thường gặp

1. Tham số không tồn tại bị bỏ qua âm thầm

Chỉ những tham số có tên đúng mới có tác dụng. Gửi materialId — một tên nghe rất hợp lý nhưng không có trong hợp đồng API — thì máy chủ vẫn trả 200 và lặng lẽ dùng vật liệu mặc định. Với carton sóng, tên đúng là flute.

Cách tự vệ: luôn đọc lại materialSelection trong phản hồi và so với thứ bạn định đặt. Nếu lệch thì tên tham số của bạn sai.

2. designId không sống mãi

Nó nằm trong bộ nhớ máy chủ. Sau khi máy chủ khởi động lại hoặc bộ nhớ đệm đầy, mã cũ trả 404. Đừng lưu designId vào cơ sở dữ liệu để dùng ngày hôm sau — hãy lưu bộ tham số và dựng lại khi cần.

3. /api/generate không phải API công khai

Bạn có thể thấy ứng dụng web gọi /api/generate. Đó là đường nội bộ của trang, không đo đếm và từ chối lời gọi từ máy chủ khác. Hãy dùng /api/v1/designs.

4. Số đo lấy nhầm chỗ

Đọc số từ document.dimensionSystems (chính xác), đừng đo lại từ chuỗi svg (đã làm tròn 0,5 mm).

Ví dụ đầy đủ

JavaScript (Node.js)

const API = "__DL_GOC__";
const KEY = process.env.DIELINE_API_KEY;

async function goi(duongDan, than) {
  const res = await fetch(API + duongDan, {
    method: "POST",
    headers: { "Authorization": `Bearer ${KEY}`, "Content-Type": "application/json" },
    body: JSON.stringify(than),
  });
  const data = await res.json();
  if (!res.ok) throw new Error(`${data.error?.code}: ${data.error?.messageVi}`);
  return data;
}

const khuon = await goi("/api/v1/designs", {
  templateId: "CORRUGATED-RSC", lengthMm: 200, widthMm: 150, heightMm: 100, flute: "C",
});
console.log("Khổ phôi:", khuon.document.stockEnvelope);
console.log("Lọt lòng:", khuon.document.dimensionSystems.inner);

const xuat = await goi("/api/v1/exports", { designId: khuon.designId, format: "PDF" });
const file = await fetch(API + xuat.downloadUrl);   // tải NGAY: hạn 60 giây
await require("node:fs/promises").writeFile(xuat.filename, Buffer.from(await file.arrayBuffer()));

Python

import os, requests

API = "__DL_GOC__"
S = requests.Session()
S.headers.update({"Authorization": f"Bearer {os.environ['DIELINE_API_KEY']}"})

def goi(duong_dan, than):
    r = S.post(API + duong_dan, json=than, timeout=60)
    if r.status_code == 402:
        raise SystemExit("Hết hạn mức — thử lại cũng vô ích, nâng gói hoặc chờ sang ngày.")
    r.raise_for_status()
    return r.json()

khuon = goi("/api/v1/designs", {
    "templateId": "ECMA-A2020-0101", "lengthMm": 100, "widthMm": 60,
    "heightMm": 150, "paperGrade": "ivory", "grammageGsm": 350,
})
print("Khổ phôi:", khuon["document"]["stockEnvelope"])

xuat = goi("/api/v1/exports", {"designId": khuon["designId"], "format": "PDF"})
open(xuat["filename"], "wb").write(S.get(API + xuat["downloadUrl"]).content)