Chọn cách kết nối Pabbly Connect phù hợp với hợp đồng API
Các bước HTTP trong hướng dẫn này gọi GenderAPI.io V2 tại https://api.genderapi.io/api/v2/gender. Phần thân JSON gửi type và value. Kết quả ước tính nằm trong data, còn thông tin về yêu cầu và tính phí nằm trong meta. Trình kết nối gốc có hợp đồng riêng, được mô tả bên dưới.
Danh mục công khai của Pabbly có một ứng dụng tên là Gender API, nhưng mục đã rà soát không nêu tên miền của đơn vị phát hành, phiên bản endpoint hay lược đồ phản hồi đầy đủ. Chỉ riêng cái tên không đủ để khẳng định đó là GenderAPI.io. Hãy xác minh đơn vị phát hành và các trường thực tế trước khi chọn hành động gốc.
Để dùng rõ ràng endpoint V2, hãy dùng tính năng yêu cầu API tùy chỉnh của API by Pabbly. Cấu hình này mô tả yêu cầu HTTP đó; nó không khẳng định rằng trình kết nối gốc đã được chuyển sang V2.
Chuẩn bị tài khoản và bản ghi nguồn
Ví dụ này bổ sung dữ liệu cho bản ghi Shopify dựa trên tên. Bạn cần quyền truy cập vào ứng dụng nguồn và ứng dụng đích, một khóa từ tài khoản GenderAPI.io và tính năng của nền tảng dùng cho hành động HTTP. Hướng dẫn này không kèm thông tin xác thực hợp lệ hay tài khoản đã kết nối.
V1 và V2 dùng chung khóa của tài khoản và cùng một số dư. Trước khi thiết lập một yêu cầu có tính phí, hãy xác minh khóa qua GET /api/v2/usage và kiểm tra rằng meta.access.mode là api_key trong phản hồi của endpoint này. Khóa bị thiếu hoặc không được nhận diện có thể chuyển sang chế độ dùng thử theo IP dùng chung; một quy trình tự động trong môi trường production không nên âm thầm phụ thuộc vào chế độ này.
Hãy tắt quy trình làm việc trong khi cấu hình. Một lần gửi ước tính để kiểm thử vẫn tiêu tốn tín dụng như bình thường. Các hướng dẫn này đã được đối chiếu với tài liệu công khai và đặc tả V2; chưa có quy trình nào được xác thực và chạy từ đầu đến cuối trên bất kỳ nền tảng nào cho lần xuất bản này.
Cấu hình yêu cầu GenderAPI.io V2 trong Pabbly Connect
- Chọn trình kích hoạt Shopify cho sự kiện khách hàng bạn cần và lấy một bản ghi kiểm thử tiêu biểu. Lưu ID khách hàng và ánh xạ một trường tên (first name) có sẵn. Nếu tên trống, hãy bỏ qua thay vì dùng toàn bộ bản ghi khách hàng để thay thế.
- Thêm API by Pabbly và chọn "Custom Request". Chọn POST và URL V2 bên dưới. Cấu hình xác thực Bearer token bằng khóa GenderAPI của bạn, hoặc một header Authorization có toàn bộ giá trị là Bearer YOUR_API_KEY; đừng cấu hình đồng thời cả hai cơ chế.
- Đặt Content-Type là application/json. Custom Request có trường "Data" dành cho phần thân JSON. Hãy tạo một đối tượng có type = name, một đối tượng options chứa ai_mode = off, và chỉ định value là tên đã ánh xạ. Header Content-Type chỉ cho biết định dạng của phần thân đã chỉ định, chứ không chuyển các trường biểu mẫu thành đối tượng JSON.
- Giữ options ở dạng lồng nhau. Nếu hành động đã chọn chỉ chấp nhận JSON thô, hãy đảm bảo dấu ngoặc kép, dấu gạch chéo ngược và ký tự xuống dòng trong giá trị đã ánh xạ được thoát đúng theo JSON. Đừng chèn văn bản của khách hàng chưa được thoát ký tự; hãy dùng một bước được hỗ trợ có thể tạo JSON.
| Thiết lập HTTP | Giá trị | Mục đích |
|---|---|---|
Method | POST | Gửi một yêu cầu ước tính. |
URL | https://api.genderapi.io/api/v2/gender | Endpoint GenderAPI.io V2 cho một lần ước tính đơn lẻ. |
Authorization | Bearer YOUR_API_KEY | Thay giá trị giữ chỗ này trong phần cài đặt xác thực hoặc header của nền tảng. |
Content-Type | application/json | Gửi một đối tượng có đối tượng options lồng bên trong, không phải các trường biểu mẫu. |
options.ai_mode | off | Lần kiểm thử đầu tiên cố ý chỉ dùng tập dữ liệu. Mức tính phí thông thường là 1 tín dụng, kể cả với kết quả không xác định. |
Kiểm tra phần thân JSON trước khi gửi
Đây là ví dụ minh họa với đầu vào cố định, không phải kết quả ước tính. Trước tiên, hãy xác minh cấu trúc yêu cầu; sau đó thay value bằng trường nguồn đã ánh xạ, sử dụng cơ chế tuần tự hóa JSON đúng cách. Đừng gửi biểu thức ánh xạ của nền tảng đến API dưới dạng chuỗi nguyên văn.
Với loại đầu vào khác, hãy đặt type là name, email hoặc username và cung cấp value tương ứng. Chỉ thêm country khi có ngữ cảnh đáng tin cậy; trường này là tùy chọn và không phải là phép tra cứu quốc gia cư trú.
{
"type": "name",
"value": "Alice",
"options": {
"ai_mode": "off"
}
}Kiểm tra bước HTTP trước khi bật cập nhật
Kiểm tra phần thân phản hồi đã lấy được và đảm bảo bước tiếp theo đọc phần thân V2 thay vì các trường trạng thái truyền tải. Pabbly có thể cung cấp các khóa của phản hồi để ánh xạ ở các bước sau; hãy xác minh đường dẫn thực tế của chúng trong quy trình của bạn.
Trong khi cấu hình, chỉ chạy hành động kiểm thử đã chọn. Một lần kiểm thử có gửi yêu cầu có thể tiêu tốn tín dụng GenderAPI và tác vụ của nền tảng, ngay cả trước khi quy trình được bật.
Xử lý riêng kết quả identified, kết quả không xác định và lỗi
Hãy phân tích phần thân phản hồi trước khi chọn cách cập nhật đích. Các đường dẫn JSON bên dưới trỏ đến phần thân V2; nền tảng của bạn có thể bọc hoặc làm phẳng phần thân này. Hãy xác nhận cấu trúc thực tế được trả về bằng một lần kiểm thử có chủ đích và gắn kết quả với ID của bản ghi nguồn.
Một ước tính không xác lập danh tính của một người hay giới tính do chính người đó tự công bố. Hãy lưu ước tính tách biệt với thông tin do người đó cung cấp. Chọn tiêu chí chấp nhận dựa trên dữ liệu đại diện cho khối lượng công việc của chính bạn, và đánh giá riêng độ tin cậy của tập dữ liệu và độ tin cậy của AI.
| Mục kiểm tra | Giá trị hoặc kiểu dự kiến | Quyết định trong quy trình |
|---|---|---|
meta.access.mode | api_key cho quy trình dùng tài khoản này | Dừng lại khi gặp ip_trial và sửa khóa. Một phản hồi thành công ở chế độ dùng thử theo IP không chứng minh tài khoản đã được xác thực và có thể đã tiêu tốn tín dụng dùng thử. |
meta.usage.billing_status | confirmed hoặc unconfirmed | Nếu là unconfirmed, hãy lưu ID yêu cầu và đối chiếu tính phí trước khi thử lại hoặc tiếp tục xử lý. |
data.result_status / data.gender | identified với male hoặc female; unknown với null | Lưu các kết quả identified đã được chấp nhận vào một trường riêng dành cho giá trị ước tính. Giữ nguyên các kết quả không xác định mà không gán danh mục mặc định. |
data.confidence / data.confidence_kind | số từ 0 đến 1 hoặc null; loại bằng chứng hoặc null | Diễn giải observed_frequency và model_reported một cách riêng biệt; không giá trị nào là bảo đảm độ chính xác chung. |
data.source / data.sample_count | dataset, ai hoặc none / số nguyên hoặc null | Lưu lại cách ước tính được tạo ra. AI không có số lượng mẫu được lưu trữ; số lượng mẫu của tập dữ liệu không phải là điểm độ chính xác của sản phẩm. |
meta.request_id / meta.usage | tham chiếu yêu cầu / đối tượng mức sử dụng | Lưu cả hai cùng với bản ghi quy trình và kết quả. Không ghi khóa API và dữ liệu cá nhân không cần thiết vào nhật ký thông thường. |
Lỗi HTTP / không có phản hồi | Problem Details hoặc không có phản hồi đầy đủ | Tạm dừng cập nhật và kiểm tra lỗi cùng trạng thái tính phí. Hết thời gian chờ không chứng minh rằng máy chủ chưa xử lý gì. |
Chỉ cập nhật bản ghi tương ứng trong Shopify
Lưu ID khách hàng Shopify lấy từ trình kích hoạt. Chuyển các kết quả identified đã được xác nhận đến trường khách hàng mong muốn hoặc theo chính sách gắn thẻ, giữ các kết quả không xác định ở dạng unknown và không thay đổi tên gốc do khách hàng cung cấp. Với mỗi ước tính được chấp nhận, hãy lưu source và confidence_kind.
Trước khi bật cập nhật, hãy kiểm thử từng nhánh: kết quả identified, kết quả không xác định và lỗi. Phản hồi mẫu hư cấu cho phép kiểm tra điều kiện của nhánh mà không gửi yêu cầu ước tính mới. Việc cập nhật trong ứng dụng đích phải dựa trên các bước kiểm tra trên và không được ghi đè các trường hoặc thẻ không liên quan.
Kiểm soát việc thử lại và tính phí trùng lặp
Pabbly mô tả "Auto Re-execution" và các tùy chọn chạy lại thủ công cho bước thất bại hoặc bị bỏ qua, hoặc cho toàn bộ quy trình. Trước khi dùng một trong hai cách, hãy xem lại những gì sẽ được chạy. Việc chạy lại toàn bộ quy trình có thể lặp lại một yêu cầu GenderAPI đã hoàn tất; khi có thể, hãy sửa lỗi Shopify ở bước sau bằng phản hồi đã lưu.
Mỗi yêu cầu mới tới GenderAPI là một thao tác độc lập. Trước khi gửi, hãy loại bỏ các sự kiện nguồn bị lặp lại trong quy trình bằng ID nguồn và trạng thái xử lý đã lưu. ID của bản ghi nguồn không phải là khóa chống trùng lặp phía máy chủ.
Kết quả không xác định thành công là một kết quả đã hoàn tất và có tính phí. Khi hết thời gian chờ hoặc phản hồi không đầy đủ, bạn có thể không biết cả kết quả lẫn việc tính phí. Hãy lưu thông tin tham chiếu của yêu cầu nếu có và kiểm tra việc tính phí trước khi gửi lại yêu cầu. Nếu phản hồi giới hạn tốc độ có header Retry-After, hãy tuân theo header đó.
Chọn khi nào dùng AI
forceToGenderize là tùy chọn cho tên, địa chỉ email và tên người dùng. Khi bật trường này, hãy bỏ qua ai_mode hoặc dùng fallback; off và always xung đột với nó và trả về 422. Chỉ cần số dư ban đầu dương là đủ để bắt đầu một yêu cầu, kể cả khi lần tính phí cuối cùng làm số dư xuống dưới 0.
Chế độ biệt danh có thể trả về giới tính cùng name: null. Chế độ này cũng có thể trả về kết quả không xác định. Cả AI dự phòng thông thường lẫn suy luận biệt danh đều không bảo đảm câu trả lời đúng hoặc khác null.
| Tùy chọn yêu cầu | Cách hoạt động | Tín dụng cho một lần tra cứu thành công |
|---|---|---|
| options.ai_mode: off | Chỉ dùng tập dữ liệu. | 1, kể cả kết quả không xác định |
| options.ai_mode: fallback | Tra tập dữ liệu trước, sau đó dùng AI thông thường khi không có giới tính được trả về. Đây là mặc định cho yêu cầu đơn lẻ. | Tổng cộng 1, đã gồm AI dự phòng |
| options.ai_mode: always | Dùng AI trực tiếp. | 2 |
| forceToGenderize: true | Tra tập dữ liệu trước, sau đó cho phép AI diễn giải biệt danh cá nhân hoặc bí danh, kể cả khi không có tên thật. | 1 khi tập dữ liệu cho ra kết quả; tổng cộng 2 nếu dùng AI |
Xác minh quy trình trước khi tăng khối lượng
- Bằng một lần kiểm thử có chủ đích, hãy xác minh JSON thực tế đã được tuần tự hóa, các đường dẫn kết quả đã phân tích, quyền truy cập bằng khóa API và việc tính phí đã được xác nhận. Khi có thể, hãy kiểm thử cách xử lý kết quả không xác định và lỗi bằng các phản hồi mẫu.
- Xác định rõ bước nào của quy trình sẽ được thử lại và trường nào của khách hàng sẽ thay đổi. Hãy lưu ID của bản ghi nguồn, phản hồi đã nhận và tham chiếu yêu cầu để nếu bước cập nhật đích thất bại sau đó, bạn không cần gửi lại yêu cầu.
- Trước tiên, hãy bật một lần chạy nhỏ có kiểm soát và kiểm tra các bản ghi cùng lượng tín dụng đã dùng trước khi tăng mức xử lý song song. Tín dụng GenderAPI và chi phí tác vụ hoặc thao tác do nền tảng tự động hóa tính là hai khoản riêng biệt.
- Với yêu cầu hàng loạt, hãy dùng POST /api/v2/gender/batch với tối đa 50 mục khi truy cập bằng khóa API hoặc 10 mục khi dùng thử theo IP. Mảng items có thể kết hợp tên, địa chỉ email và tên người dùng, với tùy chọn rõ ràng và id duy nhất cho từng mục. Hãy kiểm tra từng kết quả; phản hồi HTTP 200 vẫn có thể chứa lỗi của từng mục. Việc trình kết nối gốc có hỗ trợ yêu cầu hàng loạt hay không cần được kiểm tra riêng.
Câu hỏi thường gặp
Tôi có thể dùng options.ai_mode như một trường biểu mẫu phẳng trong Pabbly không?
Phần thân POST của V2 cần một đối tượng JSON options. Việc nhãn trường có dấu chấm không tự nó chứng minh rằng nền tảng sẽ lồng trường đó. Hãy kiểm tra phần thân đã được tuần tự hóa và xác nhận nó khớp với ví dụ trước khi chạy yêu cầu.
Ví dụ gọi HTTP trực tiếp có sử dụng AI không?
Phần thân của yêu cầu đầu tiên đặt options.ai_mode là off. Hãy chủ động đổi giá trị này thành fallback nếu muốn dùng AI dự phòng thông thường (tổng cộng 1 tín dụng), hoặc thành always nếu muốn dùng AI trực tiếp (2 tín dụng). forceToGenderize thử tập dữ liệu trước: tốn 1 tín dụng nếu được giải quyết tại đó, hoặc tổng cộng 2 tín dụng khi AI được sử dụng.
Kết quả không xác định có miễn phí không, và có an toàn để tự động gửi lại không?
Không. Một kết quả không xác định thành công là kết quả hoàn chỉnh và bị tính phí. Một lần thử lại là một lần tra cứu mới. Với lỗi truyền tải hoặc tính phí chưa được xác nhận, hãy kiểm tra dữ liệu mức sử dụng được trả về và tham chiếu yêu cầu trước khi quyết định có gửi lại hay không.
Quy trình này đã được chạy trên một tài khoản đã kết nối chưa?
Chưa. Hướng dẫn thiết lập cho từng nền tảng đã được đối chiếu với tài liệu công khai vào ngày 26 tháng 9, 2026. Phần giải thích về yêu cầu và phản hồi của GenderAPI.io V2 đã được rà soát vào ngày 27 tháng 9, 2026. Lần rà soát bản tiếng Việt này vào ngày 29 tháng 9, 2026 là bước kiểm tra bản dịch, không phải một lần kiểm thử mới bằng tài khoản. Trước khi bật cập nhật trong môi trường production, hãy kiểm thử bằng tài khoản của chính bạn các trường hiện tại của hành động đã chọn, xác thực, phần thân yêu cầu, phản hồi và cách thử lại.
Nguồn và tài liệu
Phiên bản tiếng Việt được kiểm tra lần cuối vào ngày . Thông tin về các nền tảng dựa trên tài liệu công khai của họ, được kiểm tra vào ngày 26 tháng 9, 2026. Lần kiểm tra này không phải là một bài kiểm thử mới với tài khoản đã kết nối. Hãy xem cấu hình và tình trạng cung cấp hiện tại trong tài liệu chính thức của từng nền tảng.