Kết nối Make với GenderAPI.io V2

Chọn cách kết nối Make 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.

Make niêm yết một ứng dụng GenderAPI.io với các hành động cho tên và địa chỉ email. Trang niêm yết công khai liên kết đến genderapi.io, nhưng không nêu rõ phiên bản endpoint đầy đủ hay lược đồ phản hồi hoàn chỉnh. Hãy kiểm tra đầu ra thực tế của mô-đun đã chọn trước khi thay đổi ánh xạ trong các scenario hiện có.

Để sử dụng hành vi V2 một cách rõ ràng, hãy dùng ứng dụng HTTP của Make và yêu cầu bên dưới. Cấu hình HTTP này không nâng cấp mô-đun GenderAPI hiện có; hãy vận hành riêng các scenario đang chạy cho đến khi phương án thay thế đã được kiểm tra.

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 địa chỉ email. 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.

Xác thực và kiểm tra mức sử dụng miễn phí

Cấu hình yêu cầu GenderAPI.io V2 trong Make

Chọn trình kích hoạt khách hàng Shopify phù hợp với scenario của bạn và tải một bản ghi kiểm thử tiêu biểu. Giữ lại ID khách hàng cho bước cập nhật cuối cùng và bỏ qua các bản ghi mà trường địa chỉ email để trống.
Thêm "HTTP > Make a request". Trong ứng dụng HTTP hiện tại, chọn xác thực API key và tạo thông tin xác thực với giá trị khóa là Bearer YOUR_API_KEY, vị trí đặt là Header và tên tham số là Authorization. Hãy dùng kho thông tin xác thực thay vì đưa khóa vào URL.
Đặt phương thức là POST và URL như bên dưới. Chọn application/json cho phần thân yêu cầu và một cấu trúc dữ liệu gồm các trường chuỗi type và value, cùng với một tập hợp options chứa trường chuỗi ai_mode. Đặt type là email và ai_mode là off; ánh xạ địa chỉ email của khách hàng vào value.
Bật "Parse response". Phần thân được tạo bằng cấu trúc dữ liệu của Make sẽ tuần tự hóa các giá trị đã ánh xạ thành JSON, vì vậy tên hoặc địa chỉ có chứa dấu ngoặc kép không cần phải nối chuỗi thủ công.

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": "email",
  "value": "alex@example.com",
  "options": {
    "ai_mode": "off"
  }
}

Tất cả trường, kiểu và giá trị mặc định của yêu cầu

Kiểm tra bước HTTP trước khi bật cập nhật

Giữ chế độ chuyển hướng ở trạng thái tắt cho đích API HTTPS cố định này. Khi chuyển đổi giữa các phiên bản ứng dụng HTTP của Make, hãy kiểm tra lại thiết lập xác thực và phần thân yêu cầu; các tùy chọn điều khiển có thể khác nhau.

Chạy một lần kiểm thử có chủ đích, kiểm tra gói phản hồi đã phân tích và tạo các nhánh riêng cho kết quả identified đã được chấp nhận, kết quả không xác định và lỗi vận hành trước khi thêm bước cập nhật khách hàng.

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

Trong phản hồi HTTP đã phân tích, hãy ánh xạ các đường dẫn phần thân V2 bên dưới. Make có thể đặt phần thân bên dưới nhãn đầu ra của mô-đun; hãy chọn các đối tượng data và meta lồng nhau từ gói đã kiểm tra. Chỉ cập nhật khách hàng có ID được lưu từ trình kích hoạt, sử dụng một trường riêng dành cho giá trị ước tính hoặc chính sách gắn thẻ đã xác định.

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

Hãy xem lại các trình xử lý lỗi và thiết lập về lần chạy chưa hoàn tất của Make. Một số lỗi tạm thời có thể được thử lại ngay cả khi không có trình xử lý thử lại rõ ràng. Việc thử lại mô-đun HTTP có thể gửi thêm một yêu cầu có tính phí. Nếu yêu cầu đã thành công nhưng bước cập nhật Shopify sau đó thất bại, hãy dùng lại đầu ra đã lưu để sửa bước cập nhật đó.

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 đó.

Tín dụng và trạng thái tính phí

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ó nên dán khóa API vào URL trong Make không?

Không. Với cấu hình HTTP cho V2, hãy lưu Bearer YOUR_API_KEY trong thông tin xác thực kiểu API key, với vị trí đặt là Header và tên tham số là Authorization. Endpoint POST này không chấp nhận tham số truy vấn key.

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 29 tháng 9, 2026. 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.