Postman API — automate Postman bằng Postman — API Testing with Postman Advanced

Mở đầu — vì sao bài này quan trọng

Cho đến bài này, bạn đã dùng Postman như một công cụ: mở ứng dụng, click vào collection, gửi request, xem kết quả. Nhưng có một sự thật ít người để ý: bản thân Postman cũng là một sản phẩm được vận hành bằng API. Mọi thứ bạn thấy trên giao diện — workspace, collection, environment, mock server, monitor — đều là những "tài nguyên" (resource) mà bạn có thể tạo, đọc, sửa, xóa qua HTTP request. Đó chính là Postman API.

Nghe qua thì có vẻ hơi "xoắn não": dùng Postman để tự động hóa chính Postman. Nhưng đây lại là một trong những kỹ năng phân biệt một API tester bình thường với một người làm việc ở tầm hệ thống. Khi đội của bạn có 40 collection, 12 environment, và mỗi tuần có người sửa tay một biến nào đó rồi quên commit, bạn sẽ hiểu vì sao việc quản lý các tài sản testing bằng code lại quan trọng đến thế. Postman API cho phép bạn: đồng bộ collection từ Git vào Postman tự động, backup toàn bộ workspace mỗi đêm, tạo mock server hàng loạt cho từng nhánh feature, hay kiểm tra xem có ai vô tình sửa environment production hay không.

Trong bài này, chúng ta sẽ đi từ việc lấy API key, hiểu cấu trúc endpoint, cho tới những kịch bản tự động hóa thực tế mà các đội QA ở Việt Nam đang áp dụng. Hãy nhớ: đây không phải là chuyện gửi request tới API của bạn để test sản phẩm — mà là gửi request tới API của Postman để quản lý chính hạ tầng testing của bạn.

Khái niệm cốt lõi

Postman API là gì

Postman API là một REST API công khai do Postman cung cấp, đặt tại base URL https://api.getpostman.com. Thông qua nó, bạn thao tác với các tài nguyên chính:

Collections — tạo, đọc, cập nhật, xóa collection; import/export dưới dạng JSON theo chuẩn Collection Format v2.1.
Environments — quản lý các bộ biến môi trường (dev/staging/production).
Workspaces — tạo và quản lý không gian làm việc, phân quyền team.
Mock servers — tạo mock server gắn với một collection.
Monitors — tạo và điều khiển monitor chạy collection theo lịch.
APIs — quản lý các API definition (OpenAPI) trong Postman.
User — kiểm tra thông tin tài khoản, đặc biệt là GET /me để xác thực key.

Điểm cần khắc cốt ghi tâm: mỗi tài nguyên có một UID (unique identifier) dạng 12345678-abcd-..., khác với id nội bộ. Khi gọi API, bạn dùng UID, không phải tên collection.

Lấy API key

Trước khi làm bất cứ điều gì, bạn cần một API key để xác thực. Đường đi: mở Postman → click avatar/Settings → chọn API Keys (hoặc truy cập trực tiếp trang quản lý key trong tài khoản Postman) → Generate API Key → đặt tên gợi nhớ (ví dụ ci-newman-key hay nightly-backup) → copy ngay lập tức vì key chỉ hiện một lần.

Key này được gửi trong header của mỗi request:

X-Api-Key: PMAK-xxxxxxxxxxxxxxxxxxxx-xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx

Lưu ý key luôn bắt đầu bằng tiền tố PMAK-. Đây là dấu hiệu để các công cụ quét bí mật (secret scanner) như GitGuardian phát hiện nếu bạn lỡ commit key lên Git — và tin tôi đi, chuyện đó xảy ra thường xuyên hơn bạn nghĩ.

Endpoint và cấu trúc request

Một vài endpoint bạn sẽ dùng nhiều nhất:

GET    /me                          # thông tin tài khoản hiện tại
GET    /collections                 # liệt kê tất cả collection
GET    /collections/{uid}           # lấy chi tiết một collection
POST   /collections                 # tạo collection mới
PUT    /collections/{uid}           # cập nhật toàn bộ collection
DELETE /collections/{uid}           # xóa collection
GET    /environments                # liệt kê environment
GET    /environments/{uid}          # chi tiết environment
POST   /mocks                       # tạo mock server
GET    /monitors                    # liệt kê monitor
POST   /monitors/{uid}/run          # chạy monitor ngay lập tức

Body của các request tạo/sửa collection tuân theo cấu trúc { "collection": { ... } }, trong đó phần collection chính là JSON export chuẩn của Postman. Điều này rất đẹp: bạn có thể export collection ra file, chỉnh sửa, rồi PUT ngược lại.

Rate limit và version

Postman API áp dụng rate limit. Với tài khoản thông thường, giới hạn khoảng vài trăm request mỗi phút (con số cụ thể phụ thuộc gói tài khoản của bạn — hãy kiểm tra header X-RateLimit-Limit, X-RateLimit-Remaining trong response để biết chính xác). Khi vượt ngưỡng, bạn nhận HTTP 429 Too Many Requests. Với các tác vụ hàng loạt (như tạo 50 mock server), bạn phải thêm delay giữa các lần gọi, nếu không script sẽ chết giữa chừng.

Tình huống thực tế

Ví dụ 1 — Tiki: backup collection tự động mỗi đêm

Một đội QA ở một công ty thương mại điện tử lớn tại TP.HCM (giả định tương tự mô hình Tiki) quản lý khoảng 35 collection cho các hệ thống order, payment, inventory. Vấn đề: mọi người sửa collection trực tiếp trên workspace chung, và một lần một bạn junior vô tình xóa nhầm 8 request trong collection "Order Service", không ai có bản backup.

Sau sự cố, họ viết một script Node.js chạy bằng cron lúc 2 giờ sáng: gọi GET /collections để lấy danh sách UID, sau đó lặp qua từng UID gọi GET /collections/{uid} và ghi JSON ra thư mục backups/2026-06-27/, rồi commit lên một repo Git riêng. Mỗi đêm là một snapshot. Khi cần khôi phục, họ chỉ việc lấy file JSON của ngày mong muốn và PUT ngược lại.

Bài học rút ra: collection là tài sản testing quý giá, và Postman API biến chúng thành thứ có thể version-control được như code. Việc backup mất chưa tới 30 dòng script nhưng cứu cả đội khỏi những đêm mất ngủ.

Ví dụ 2 — Fintech ở Hà Nội: đồng bộ environment từ nguồn sự thật duy nhất

Một startup fintech xử lý ví điện tử có ba môi trường: dev, staging, production. Trước đây mỗi tester tự tạo environment trong Postman cá nhân, dẫn tới thảm họa: base URL của staging bị lệch giữa các máy, có người vẫn trỏ về endpoint cũ đã deprecated, một bạn vô tình để token sandbox VNPay của staging vào environment production.

Giải pháp: họ đặt "nguồn sự thật duy nhất" (single source of truth) là các file env-dev.json, env-staging.json trong repo. Mỗi khi merge vào nhánh chính, GitHub Actions chạy một job gọi Postman API: GET /environments để tìm UID của environment tương ứng theo tên, rồi PUT /environments/{uid} với nội dung mới từ file. Toàn bộ đội luôn dùng chung một cấu hình, và mọi thay đổi environment đều phải đi qua pull request để review.

Đặc biệt, họ không bao giờ đưa secret thật (như API key MoMo production) vào file JSON commit lên Git. File chỉ chứa placeholder, còn giá trị thật được inject lúc runtime từ GitHub Secrets. Đây là nguyên tắc kết hợp giữa Postman API và quản lý secret mà bạn sẽ thấy lặp lại nhiều lần trong nghề.

Bài học rút ra: khi environment là code có thể review được, bạn loại bỏ được cả một lớp lỗi "cấu hình lệch giữa các máy" — loại lỗi khó chịu nhất vì nó không phải bug của sản phẩm mà là bug của quy trình.

Ví dụ 3 — Agency outsourcing: tạo mock server hàng loạt cho từng khách hàng

Một agency ở Đà Nẵng nhận làm QA cho nhiều dự án cùng lúc. Mỗi khi khởi động dự án mới, họ cần dựng nhanh một mock server để team frontend có endpoint làm việc trong khi backend chưa sẵn sàng. Làm tay thì mỗi mock mất 10 phút click chuột, và với 6 dự án chạy song song, đó là công việc lặp đi lặp lại nhàm chán.

Họ viết một script nhận vào tên dự án và một collection template, tự động: POST /collections để clone collection mẫu, rồi POST /mocks để tạo mock server gắn với collection vừa tạo, đặt tên theo quy ước mock-{project}-{date}. Kết quả trả về chứa mockUrl mà họ paste thẳng vào Slack cho team frontend. Toàn bộ quá trình từ 10 phút click tay rút xuống còn 15 giây chạy lệnh.

Lưu ý quan trọng họ học được: khi tạo hàng loạt, phải thêm await sleep(500) giữa các lần gọi để tránh dính rate limit 429. Lần đầu chạy không có delay, script tạo được 3 mock rồi chết.

Bài học rút ra: Postman API tỏa sáng nhất ở những tác vụ lặp lại theo pattern. Bất cứ khi nào bạn thấy mình click cùng một chuỗi thao tác nhiều lần, đó là tín hiệu để tự động hóa.

Hướng dẫn từng bước

Hãy cùng làm một quy trình hoàn chỉnh: liệt kê tất cả collection và backup collection đầu tiên, dùng chính Postman để gọi Postman API.

Bước 1 — Lấy API key. Vào Settings → API Keys → Generate. Đặt tên learning-key. Copy giá trị PMAK-....

Bước 2 — Lưu key an toàn trong Postman. Đừng dán key trực tiếp vào request. Tạo một environment tên Postman API, thêm biến postman_api_key kiểu secret, dán key vào. Như vậy key không lộ ra khi bạn share collection.

Bước 3 — Tạo request kiểm tra key. Tạo request GET https://api.getpostman.com/me, thêm header:

X-Api-Key: {{postman_api_key}}

Gửi đi. Nếu nhận 200 OK với JSON chứa thông tin user, key hoạt động. Nếu nhận 401, key sai hoặc chưa gán header.

Bước 4 — Liệt kê collection. Tạo request GET https://api.getpostman.com/collections với cùng header. Response trả về mảng collections, mỗi phần tử có id (chính là UID), name, uid. Trong tab Tests, lưu UID đầu tiên để dùng ở bước sau:

const data = pm.response.json();
pm.test("Có ít nhất 1 collection", function () {
    pm.expect(data.collections.length).to.be.above(0);
});
pm.environment.set("first_collection_uid", data.collections[0].uid);

Bước 5 — Lấy chi tiết một collection. Tạo request GET https://api.getpostman.com/collections/{{first_collection_uid}}. Response chính là JSON đầy đủ của collection đó — đây là thứ bạn sẽ lưu làm backup.

Bước 6 — Tự động hóa bằng Newman/Node (tùy chọn). Ngoài Postman, bạn có thể gọi API bằng bất cứ ngôn ngữ nào. Ví dụ script Node backup toàn bộ:

const https = require("https");
const fs = require("fs");
const KEY = process.env.POSTMAN_API_KEY;
function get(path) {
  return new Promise((resolve, reject) => {
    https.get(https://api.getpostman.com${path},
      { headers: { "X-Api-Key": KEY } }, (res) => {
        let body = "";
        res.on("data", (c) => (body += c));
        res.on("end", () => resolve(JSON.parse(body)));
      }).on("error", reject);
  });
}(async () => {
  const { collections } = await get("/collections");
  fs.mkdirSync("backups", { recursive: true });
  for (const c of collections) {
    const full = await get(/collections/${c.uid});
    fs.writeFileSync(backups/${c.name}.json, JSON.stringify(full.collection, null, 2));
    await new Promise((r) => setTimeout(r, 500)); // tránh rate limit
  }
  console.log(Đã backup ${collections.length} collection);
})();

Chạy POSTMAN_API_KEY=PMAK-... node backup.js. Bạn vừa biến toàn bộ workspace thành file có thể commit.

Lỗi thường gặp & mẹo

Lộ API key lên Git. Đây là lỗi nghiêm trọng nhất. Key PMAK-... cho phép ai có nó thao tác toàn bộ tài nguyên Postman của bạn. Không bao giờ hardcode key trong script hay commit vào repo. Luôn đọc key từ biến môi trường (process.env) hoặc secret manager. Nếu lỡ lộ, vào Settings → API Keys → Revoke ngay và tạo key mới.

Nhầm giữa UID và id. Nhiều người copy id (dạng số nội bộ hoặc guid ngắn) thay vì uid (dạng userId-guid). Endpoint chỉ nhận UID. Nếu nhận 404 Not Found dù chắc chắn collection tồn tại, kiểm tra lại xem bạn đang truyền đúng trường uid chưa.

Dính rate limit 429. Khi chạy vòng lặp tạo/đọc hàng loạt, luôn thêm delay (300–500ms) giữa các request. Đọc header X-RateLimit-Remaining để biết còn bao nhiêu lượt. Với tác vụ lớn, thiết kế cơ chế retry với exponential backoff khi gặp 429.

Quên bọc body trong { "collection": {...} }. Khi PUT/POST collection, body phải có key bao ngoài đúng tên (collection, environment, mock...). Truyền thẳng JSON export vào sẽ bị 400 Bad Request. Đây là lỗi hay gặp khi khôi phục backup.

Nhầm lẫn Postman API với API của sản phẩm. Nhắc lại lần nữa vì rất quan trọng: bài này nói về việc quản lý Postman, không phải dùng Postman để test API sản phẩm của bạn. Đừng vô tình gọi api.getpostman.com khi ý bạn là gọi API của công ty mình.

Mẹo — dùng collection Postman API có sẵn. Postman phát hành sẵn một collection chính thức mô tả toàn bộ endpoint của Postman API trong workspace công khai của họ. Fork về, bạn có ngay bộ request mẫu đầy đủ, không cần tự gõ từng URL.

Mẹo — phân quyền key theo mục đích. Tạo nhiều key riêng cho từng việc (ci-key, backup-key, local-dev-key). Khi một key bị lộ hoặc không cần nữa, bạn revoke đúng key đó mà không ảnh hưởng các quy trình khác.

Bài tập thực hành

Xác thực key: Lấy một API key, lưu vào environment dạng secret, và gọi GET /me thành công. Viết một test trong tab Tests kiểm tra pm.response.code === 200 và log ra username của bạn.

Kiểm kê tài nguyên: Gọi lần lượt GET /collections, GET /environments, GET /workspaces. Đếm số lượng mỗi loại và in ra console một bản tóm tắt kiểu "Bạn có X collection, Y environment, Z workspace".

Backup mini: Viết script Node (hoặc dùng Runner của Postman) lưu 3 collection đầu tiên ra file JSON, có thêm delay 500ms giữa các lần gọi. Kiểm tra file lưu ra có đúng cấu trúc collection không.

Nâng cao — đồng bộ environment: Tạo một file env-staging.json với vài biến, viết script tìm environment tên "Staging" qua GET /environments, lấy UID, rồi PUT /environments/{uid} cập nhật giá trị mới. Xác nhận thay đổi hiển thị trên giao diện Postman.

Tư duy hệ thống: Viết ra giấy quy trình bạn sẽ dùng Postman API để giải quyết trong dự án của mình (backup? đồng bộ? tạo mock hàng loạt?), kèm cách bạn quản lý API key an toàn.

Tóm tắt

Postman không chỉ là công cụ để click — nó là một sản phẩm có API công khai tại https://api.getpostman.com, cho phép bạn quản lý collection, environment, workspace, mock server và monitor bằng code. Bạn xác thực bằng API key PMAK-... gửi qua header X-Api-Key, thao tác với từng tài nguyên qua UID của nó, và luôn để mắt tới rate limit.

Sức mạnh thật sự của Postman API nằm ở tự động hóa những việc lặp lại: backup collection mỗi đêm, đồng bộ environment từ nguồn sự thật duy nhất trong Git, tạo hàng loạt mock server cho các dự án song song. Ba tình huống ở Tiki, fintech Hà Nội và agency Đà Nẵng cho thấy cùng một bài học: khi tài sản testing trở thành thứ có thể version-control và tự động hóa, bạn loại bỏ được cả một lớp lỗi do thao tác tay và cấu hình lệch.

Nguyên tắc vàng cần mang theo: bảo vệ API key như bảo vệ mật khẩu — không hardcode, không commit, revoke ngay khi lộ. Khi bạn thành thạo việc dùng Postman để tự động hóa chính Postman, bạn đã bước một chân vào tư duy của một SDET thực thụ: coi mọi thứ, kể cả hạ tầng testing, đều là code.

Học xong bài này rồi? Tạo tài khoản miễn phí để lưu lại — lần sau vào là biết ngay đang dở ở đâu, và học hết khóa thì có chứng chỉ. Lưu tiến độ của tôi