Hướng dẫn đầy đủ cách gửi yêu cầu POST bằng curl

Hiện nay, ước tính có khoảng hai mươi tỷ lượt cài đặt curl đang hoạt động ở đâu đó trên thế giới. Con số này đến từ người tạo ra công cụ này, Daniel Stenberg, người gần như duy trì nó một mình. Curl được tích hợp trong bộ định tuyến, ô tô, vệ tinh, TV thông minh, các máy chủ Linux hỗ trợ phần lớn mạng internet công cộng và mọi môi trường chạy LLM chính. Trong tất cả các động từ HTTP mà các cài đặt này sử dụng, POST đảm nhiệm phần lớn công việc. Một yêu cầu curl POST là cách hầu hết các nhà phát triển kiểm tra, gỡ lỗi hoặc tích hợp với API lần đầu tiên.

Báo cáo Tình trạng API năm 2025 của Postman cho thấy tỷ lệ sử dụng REST đạt 93%. 82% các tổ chức hiện đang vận hành ít nhất một phần theo mô hình API-first. POST là động từ bạn sử dụng mỗi khi tạo, gửi hoặc truyền dữ liệu đến máy chủ. Khối lượng công việc AI đã thúc đẩy xu hướng này hơn nữa. Lưu lượng API liên quan đến việc sử dụng AI đã tăng 73% trong năm 2024 (Postman, 2024), và tài liệu của mọi nhà cung cấp LLM hiện nay đều bắt đầu bằng một đoạn mã curl POST như là "lệnh gọi đầu tiên" chuẩn mực.

Tài liệu tham khảo này hướng dẫn chi tiết mọi hình thức của yêu cầu POST sử dụng curl, từ yêu cầu tối thiểu một dòng đến một lệnh gọi hoạt động thực tế tới API thanh toán tiền điện tử. Mục tiêu: cung cấp tài liệu có thể sao chép, chứ không chỉ để đọc. Cho dù bạn gửi dữ liệu đến máy chủ lần đầu tiên hay xây dựng lại trình xử lý webhook lúc 2 giờ sáng, các mẫu dưới đây đều bao gồm những gì bạn thực sự cần.

Bảng dưới đây là phiên bản ngắn gọn. Bảng tóm tắt các tùy chọn dòng lệnh curl được sử dụng thường xuyên nhất khi gửi yêu cầu POST. Mỗi tùy chọn được giải thích chi tiết trong các phần tiếp theo.

Hiểu về yêu cầu POST và phương thức HTTP của curl

Một yêu cầu POST của curl là một yêu cầu HTTP POST, được gửi đi bằng phương thức POST, được thực thi từ dòng lệnh. Bản thân công cụ curl mô tả công việc của nó là "truyền dữ liệu" qua hơn hai chục giao thức, trong đó HTTP chỉ là một. POST có nghĩa là: đây là một số dữ liệu, hãy làm điều gì đó với nó. Dữ liệu được lưu trữ trong phần thân yêu cầu, không bao giờ trong URL. Thuộc tính đó là lý do tại sao POST xử lý việc tạo tài nguyên, gửi biểu mẫu và bất cứ thứ gì mang theo thông tin xác thực. GET lưu trữ dữ liệu trong chuỗi truy vấn, hiển thị cho mọi máy chủ proxy và mọi lịch sử trình duyệt. POST thì không.

Hầu hết các hướng dẫn đều bỏ qua một chi tiết nhỏ nhưng hữu ích. Truyền tham số `-d` và curl sẽ tự động chuyển sang phương thức POST. Tham số `-X POST` được chỉ định rõ ràng, là tùy chọn. Nhiều ví dụ vẫn bao gồm nó vì việc đọc `-X POST` bên cạnh dữ liệu gửi đi sẽ giúp người dùng hiểu rõ mục đích ngay từ cái nhìn đầu tiên.

PUT và POST thường bị nhầm lẫn với nhau, vì vậy cần làm rõ sự khác biệt. PUT thay thế một tài nguyên tại một vị trí đã biết. POST tạo một tài nguyên mới hoặc gửi dữ liệu để được xử lý tại một điểm cuối chung.

Cú pháp cơ bản của lệnh curl POST và cờ -d trong thực tế.

Bài đăng tối thiểu về chủ đề curl chỉ gồm một dòng:

```

curl -d "username=arya&age=16" https://api.example.com/users

```

Vậy thôi. Yêu cầu POST, phần thân được mã hóa URL dạng form, không phức tạp. `-d` thực hiện ba nhiệm vụ: nó nhét dữ liệu vào phần thân yêu cầu, chuyển phương thức yêu cầu thành POST, và thêm `Content-Type: application/x-www-form-urlencoded` làm tiêu đề mặc định. Tôi thường dán dạng chi tiết hơn một chút, vì mục đích của POST dễ đọc hơn trong quá trình xem xét mã:

```

curl -X POST -d "username=arya&age=16" https://api.example.com/users

```

Cùng một byte trên đường truyền. Cùng một tham số yêu cầu. Hãy sử dụng phương pháp nào mà nhóm của bạn thấy dễ quét hơn. Cờ `-d` là công cụ chủ lực được sử dụng để gửi dữ liệu đến máy chủ từ dòng lệnh, và nó xử lý chín mươi phần trăm những gì mà một nhà phát triển backend thường đưa vào curl: các lệnh gọi shell, kiểm thử webhook, mục tiêu Makefile, các bước GitHub Actions.

Ba tùy chọn gần giống với `-d`. `--data-binary` giữ nguyên dữ liệu nhị phân; `-d` thông thường sẽ loại bỏ các ký tự xuống dòng và làm biến dạng dữ liệu nhị phân. `--data-urlencode` tự động mã hóa phần trăm: `--data-urlencode "name=I am Daniel"` sẽ được trả về dưới dạng `name=I%20am%20Daniel`. `--data-raw` là giải pháp thay thế khi giá trị bắt đầu bằng `@` và curl không nên đọc tệp. Nhiều cờ `-d` được kết hợp bằng `&`. Phù hợp với biểu mẫu. Tuyệt đối không dùng cho JSON.

Một điểm cần lưu ý cuối cùng: dấu ngoặc kép. Dấu ngoặc đơn xung quanh dữ liệu gửi đi sẽ ngăn shell hiểu ký tự `$` hoặc dấu gạch chéo ngược. Nếu quên chúng, bạn sẽ mất đến 2 giờ sáng để tự hỏi tại sao một nửa dữ liệu POST của mình bị thiếu.

Những chi tiết này rất quan trọng vì bản thân curl là một trong những trình khách HTTP được kiểm thử nhiều nhất trên thế giới. Bản đánh giá của Stenberg vào tháng 12 năm 2025 đã thống kê tám bản phát hành trong năm đó. Chín lỗ hổng CVE, tất cả đều được xếp hạng thấp hoặc trung bình. 2.179 trường hợp kiểm thử đang hoạt động, nhiều hơn 232 trường hợp so với mười hai tháng trước đó. Bản phát hành 8.11.1, tháng 12 năm 2024, đã vá lỗi CVE-2024-11053 (lỗ hổng rò rỉ thông tin đăng nhập netrc và chuyển hướng). Phiên bản ổn định hiện tại tính đến cuối tháng 4 năm 2026 là curl 8.20.0. Bất kỳ ai vẫn đang sử dụng phiên bản dưới 7.82.0 vẫn không có cờ `--json` và sẽ quay lại mẫu ba cờ cũ hơn.

Gửi dữ liệu JSON bằng curl sử dụng tùy chọn --json hoặc -H

JSON sẽ là ngôn ngữ chung của các API REST vào năm 2026. Có hai cách để gửi dữ liệu bằng curl. Cách nào nên sử dụng hoàn toàn phụ thuộc vào phiên bản curl đang có trên máy.

Mô hình ba cờ cổ điển, hoạt động trên mọi hệ điều hành từ CentOS 6 trở đi:

```

curl -X POST \

-H "Content-Type: application/json" \

-d '{"title":"Tea","quantity":2}' \

https://api.example.com/orders

```

Hệ thống tốc ký hiện đại, có sẵn từ phiên bản curl 7.82.0 (tháng 3 năm 2022):

```

curl --json '{"title":"Tea","quantity":2}' https://api.example.com/orders

```

Cờ `--json` thực hiện ba việc. Thiết lập `Content-Type: application/json`. Thiết lập `Accept: application/json`. Gửi phần thân yêu cầu. Nó cũng kết hợp các yêu cầu: truyền `--json` nhiều hơn một lần, các phần thân yêu cầu sẽ được nối lại với nhau. Hữu ích khi truyền các đoạn JSON vào một điểm cuối xử lý dữ liệu trực tuyến.

Đối với dữ liệu JSON được lưu trữ trong tệp, hãy thêm tiền tố `@` vào đường dẫn tệp. Việc đăng dữ liệu từ tệp trở thành mẫu chuẩn khi đối tượng JSON quá lớn để dán trực tiếp, hoặc khi nó nằm trong hệ thống kiểm soát phiên bản, hoặc khi một tập lệnh khác tạo ra nó:

```

curl -X POST -H "Content-Type: application/json" -d @order.json https://api.example.com/orders

curl --json @order.json https://api.example.com/orders

```

Mẫu thứ hai đọc dữ liệu từ một tệp có tên `order.json` và gửi nó với tất cả các tiêu đề phù hợp. Đối với nội dung JSON lớn hoặc có khả năng là nhị phân, `--data-binary @file.json` là tùy chọn an toàn hơn. Nó không loại bỏ các ký tự xuống dòng, không diễn giải các ký tự đặc biệt và gửi dữ liệu nhị phân thô đến một điểm cuối mong đợi các byte chứ không phải các trường biểu mẫu. Mẫu thứ ba đọc dữ liệu từ stdin thông qua `-d @-`. Tiện dụng khi chuyển tiếp đầu ra từ một lệnh khác trực tiếp vào yêu cầu POST của curl.

Bảng dưới đây thể hiện sự tương ứng giữa bốn dạng JSON phổ biến với một điểm cuối duy nhất:

Điều này quan trọng hơn trước đây. Mọi nhà cung cấp LLM lớn — OpenAI, Anthropic, Mistral, Google — đều mở đầu tài liệu API của họ bằng một ví dụ về lệnh curl POST sử dụng chính xác cấu trúc này. Lưu lượng truy cập do AI điều khiển đã tăng 73% tổng số lượng cuộc gọi API trong năm 2024 (Postman). curl hiện là tài liệu tham khảo chuẩn cho câu hỏi "làm thế nào để gọi điểm cuối này?".

Content-Type, tiêu đề và những giả định mà curl đưa ra.

Hầu hết các phản hồi "415 Unsupported Media Type" đều do thiếu một tiêu đề. Với `-d`, curl sẽ tự động thêm yêu cầu của bạn `Content-Type: application/x-www-form-urlencoded`. Nếu bạn gửi nội dung JSON mà không có `-H "Content-Type: application/json"` hoặc `--json`, bạn sẽ nhận được lỗi 415. Không có cảnh báo nào, chỉ là thông báo từ chối.

Các siêu dữ liệu khác cũng được lưu kèm theo phần thân yêu cầu: Content-Length, tiêu đề Authorization, X-Request-Id để theo dõi. Việc đảm bảo các siêu dữ liệu này chính xác là một nửa của bất kỳ quá trình tích hợp API nào. Bản thân đối tượng JSON là phần dễ hơn.

Tùy chọn `-H` thêm các tiêu đề tùy chỉnh. Lặp lại thao tác này nếu cần. Tên tiêu đề không phân biệt chữ hoa chữ thường; giá trị thì có. Cách nhanh nhất để gỡ lỗi một yêu cầu POST cấu hình sai: chạy nó với `-v` một lần, đọc dòng yêu cầu, so sánh với tài liệu API. Tám trong mười trường hợp, lỗi sẽ xuất hiện trong vài giây.

Thêm hai lưu ý nữa. Thuộc tính Content-Length được curl tự động thiết lập dựa trên kích thước phần thân; bạn hiếm khi cần ghi đè lên nó. Tham số `Accept: application/json` cho máy chủ biết cần phản hồi bằng JSON thay vì HTML. Thêm một tham số `-H` nữa cho việc này, hoặc sử dụng `--json`, tham số này sẽ thiết lập cả Content-Type và Accept cùng nhau.

Tải dữ liệu biểu mẫu và tệp lên bằng lệnh curl POST -F

Đối với dữ liệu biểu mẫu kiểu HTML có tệp, cờ thích hợp là `-F`. Nó tạo ra yêu cầu `multipart/form-data`. Kiểu nội dung khác với kiểu form-urlencoded mà `-d` mặc định sử dụng. Mô hình tư duy khác nhau. Các hướng dẫn ngắn gọn thường nhầm lẫn hai khái niệm này đến mức gây ra lỗi thực sự.

`-F` một lần cho mỗi trường. Trường dạng văn bản thông thường:

```

curl -F "name=Arya" https://api.example.com/submit

```

Tải lên tập tin:

```

curl -F "file=@/path/to/image.png" https://api.example.com/upload

```

Tiền tố `@` cho curl biết cần đọc tệp từ ổ đĩa và bao gồm nội dung của tệp trong phần thân yêu cầu. Curl tự động phát hiện loại MIME từ tên tệp; hãy ghi đè rõ ràng khi cần thiết:

```

curl -F "[email protected];type=image/png" https://api.example.com/upload

```

Sử dụng nhiều cờ `-F` để đóng gói nhiều trường hoặc tệp vào một yêu cầu duy nhất:

```

curl -F "title=Holiday" -F "[email protected]" -F "[email protected]" https://api.example.com/album

```

Đối với nội dung tệp thô không có trình bao bọc multipart, một nhu cầu phổ biến khi gửi tệp JSON hoặc blob nhị phân đến điểm cuối truyền phát, hãy sử dụng `--data-binary @file.bin` thay thế. Thao tác này sẽ gửi các byte của tệp dưới dạng phần thân yêu cầu nguyên văn, với bất kỳ Content-Type nào bạn đã thiết lập rõ ràng.

Xác thực trong yêu cầu POST của curl: xác thực cơ bản, xác thực bearer, khóa API

Ba hình thức xác thực sẽ bao phủ hầu hết mọi API REST vào năm 2026. Xác thực cơ bản (tên người dùng cộng với mật khẩu, được mã hóa base64 vào tiêu đề):

```

curl -u "myuser:mypass" -X POST -d "..." https://api.example.com/login

```

Các mã thông báo Bearer, được sử dụng bởi hầu hết các API hiện đại bao gồm mọi thông tin xác thực được cấp bởi OAuth, dựa trên tiêu đề Authorization tùy chỉnh:

```

curl -H "Authorization: Bearer $TOKEN" --json '{"q":"hello"}' https://api.example.com/query

```

Khóa API thường nằm trong phần tiêu đề dành riêng cho dịch vụ:

```

curl -H "X-API-Key: $PLISIO_KEY" --json @invoice.json https://api.plisio.net/api/v1/invoices/new

```

Thông tin xác thực từ biến môi trường hoặc trình quản lý bí mật không bao giờ được nhập trực tiếp. Tại sao? Báo cáo Tình trạng rò rỉ bí mật năm 2025 của GitGuardian đã thống kê được 23,8 triệu bí mật mới bị rò rỉ lên GitHub công khai trong năm 2024. Tăng 25% so với năm 2023. Hơn 90% trong số đó vẫn còn hiệu lực năm ngày sau khi bị lộ. Thông tin xác thực được nhập trực tiếp trong các tập lệnh curl là một trong những nguồn rò rỉ hàng đầu. Phần bảo mật bên dưới sẽ trình bày quy trình làm việc.

Ví dụ thực tế về phương thức POST của curl: API thanh toán Plisio

Tài liệu tham khảo mà không có ví dụ thực tế chỉ là lý thuyết. Câu lệnh curl POST bên dưới tạo ra hóa đơn thanh toán tiền điện tử thông qua API REST của Plisio. Plisio tính phí cố định 0,5%; các nhà xử lý thẻ thường tính phí từ 2-4%. Plisio hỗ trợ hơn ba mươi loại tiền điện tử và tích hợp với mười chín nền tảng thương mại điện tử.

Tại sao API tiền điện tử lại hữu ích như mục tiêu thực hành? Stablecoin đã tạo ra doanh thu thực tế khoảng 28 nghìn tỷ đô la trong năm 2025. Chainalysis ước tính tốc độ tăng trưởng kép hàng năm (CAGR) là 133% kể từ năm 2023. Thị trường cổng thanh toán tiền điện tử đạt gần 2 tỷ đô la vào năm 2025, và đang trên đà đạt 2,39 tỷ đô la vào năm 2026 (theo The Business Research Company). BitPay, Coinbase Commerce, Plisio: bạn có thể chọn bất kỳ cổng nào. Bước tích hợp đầu tiên với bất kỳ cổng thanh toán hiện đại nào hầu như luôn là yêu cầu POST bằng lệnh curl.

Lệnh gọi tối thiểu để tạo hóa đơn mới:

```

curl -X POST https://api.plisio.net/api/v1/invoices/new \

-H "Content-Type: application/json" \

-H "Xác thực: Người mang $PLISIO_API_KEY" \

-d '{

"source_currency": "USD",

"source_amount": 49.99,

"order_number": "INV-1042",

"currency": "BTC",

"email": "[email protected]",

"order_name": "Annual subscription"

}'

```

Một cuộc gọi thành công sẽ trả về mã HTTP 201. Phần thân phản hồi là một đối tượng JSON: ID hóa đơn được tạo, URL hóa đơn mà khách hàng thanh toán, địa chỉ ví đích và thời gian hết hạn. Sử dụng hàm `jq` để trích xuất bất kỳ trường nào bạn cần tiếp theo:

```

... | jq '.data.invoice_url'

```

Đó là toàn bộ quy tắc. Thay đổi điểm cuối, thay đổi dữ liệu gửi đi, và cấu trúc sẽ được giữ nguyên cho giao dịch BitPay, thanh toán Coinbase Commerce hoặc giao dịch thanh toán Stripe. Các cờ (flags) không thay đổi; chỉ có JSON thay đổi.

Gỡ lỗi yêu cầu POST của curl: -v, --trace, errors

Lỗi POST là một bài toán gỡ lỗi khó nhằn. Thử lại một cách mù quáng là nước đi tồi tệ nhất. Bốn tùy chọn trên dòng lệnh bao gồm hầu hết những gì bạn cần.

`-v` in ra dòng yêu cầu, tất cả các tiêu đề yêu cầu và trạng thái phản hồi. Đó là cờ đầu tiên bạn nên sử dụng. `--trace-ascii -` là công cụ mạnh mẽ hơn: nó xuất toàn bộ cuộc hội thoại, bao gồm cả phần thân của yêu cầu POST, ra đầu ra chuẩn. Sử dụng `curl -i` để chèn các tiêu đề phản hồi lên trên phần thân. Và `-w "%{http_code}\n"` chỉ ghi mã trạng thái HTTP, hữu ích khi viết kịch bản kiểm tra CI đối với API.

Về các mã trạng thái bạn sẽ thấy thường xuyên nhất: 400: máy chủ đã phân tích yêu cầu của bạn nhưng từ chối dữ liệu. 401: thiếu hoặc tiêu đề xác thực không hợp lệ. 415: Content-Type sai. 500: máy chủ bị sập khi xử lý dữ liệu đầu vào của bạn. Mỗi mã loại trừ một lớp cụ thể, điều này giải thích một nửa giá trị của việc chạy lệnh `-v` khi gặp lỗi đầu tiên.

Bảo mật yêu cầu POST của curl: Khóa API, bí mật và rò rỉ thông tin

Mọi tài liệu tham khảo đều bỏ qua phần này. Mọi báo cáo phân tích sự cố đều đề cập đến nó. Tháng 12 năm 2024: vụ rò rỉ dữ liệu của Bộ Tài chính Hoa Kỳ được truy vết nguồn gốc từ khóa API BeyondTrust bị rò rỉ. Chính xác là loại thông tin xác thực nằm trong tiêu đề `-H "Authorization: Bearer ..."` trong các tập lệnh sản xuất.

Phương pháp phòng thủ này không hào nhoáng. Đọc mã thông báo từ các biến môi trường. Lưu trữ chúng trong trình quản lý bí mật như AWS Secrets Manager, HashiCorp Vault hoặc 1Password CLI. Giữ một hook trước khi commit chạy `gitleaks` hoặc `trufflehog`. Xoay vòng bất kỳ mã thông báo nào đã từng tồn tại trong lịch sử shell. Không có gì thú vị trong số này. Nhưng tất cả đều hiệu quả. Áp dụng nó cho mọi yêu cầu POST curl mà bạn gửi đi là thói quen quan trọng nhất mà một nhà phát triển backend có thể xây dựng trong năm 2026.

Simon Chartan

A journalist with a strong technical background and a passion for decentralized finance. With degrees in MBA and Master of Engineering in Data Science, the author combines analytical expertise with a clear, engaging writing style. At Plisio, they cover topics such as cryptocurrency, blockchain, DeFi, and digital finance—helping readers make sense of a rapidly evolving fintech landscape.