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

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

Zapier niêm yết các hành động của GenderAPI.io để xác định giới tính từ tên hoặc địa chỉ email. Trang niêm yết công khai không nêu rõ phiên bản endpoint hay đặc tả phản hồi V2. Hãy kiểm tra đầu ra của các hành động gốc hiện có trước khi thay đổi ánh xạ trường ở các bước tiếp theo.

Cấu hình V2 bên dưới sử dụng Webhooks by Zapier với payload POST có cấu trúc. Để dùng Webhooks by Zapier, bạn cần một gói trả phí của Zapier. Số dư tài khoản GenderAPI và lượng tác vụ tiêu tốn trên Zapier được tính riêng.

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 Mailchimp 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 Zapier

Bắt đầu với trình kích hoạt Mailchimp cung cấp bản ghi người đăng ký mong muốn. Giữ lại ID của audience và liên hệ, và thêm một bộ lọc để bỏ qua địa chỉ email trống trước hành động HTTP.
Chọn Webhooks by Zapier và hành động POST của nó. Nhập URL bên dưới và đặt "Payload Type" là JSON. Thêm các trường dữ liệu type = email, options__ai_mode = off, và chỉ định value là địa chỉ email của người đăng ký đã ánh xạ.
Trong Zapier, ký hiệu hai dấu gạch dưới sẽ lồng options__ai_mode thành options.ai_mode trong phần thân JSON. Khối mã bên dưới cho thấy phần thân mà API nhận được, không phải một trường thứ tư cần thêm vào hành động.
Trong "Headers", thêm Authorization với giá trị Bearer YOUR_API_KEY. Dùng application/json cho Content-Type. Đừng đặt khóa vào các trường của trình kích hoạt, chuỗi truy vấn hay dữ liệu phản hồi mẫu.

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

Header của Webhooks không phải là trường kết nối dành riêng cho thông tin bí mật: những người có quyền chỉnh sửa Zap đều có thể nhìn thấy chúng. Hãy giới hạn quyền truy cập và không chia sẻ Zap, ảnh chụp màn hình hay bản xuất có chứa thông tin xác thực. Zapier cũng cung cấp API by Zapier với thông tin xác thực đã lưu, nhưng cách thiết lập phần thân yêu cầu của nó khác với cấu hình POST có cấu trúc này.

Không bọc phần thân và gửi một đối tượng duy nhất, không phải danh sách hay mảng. Với dữ liệu khách hàng đã ánh xạ, hãy chọn hành động JSON có cấu trúc; Custom Request gửi văn bản thô và không tự động thoát các ký tự đặc biệt trong giá trị được chèn vào.

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 Mailchimp

Hãy kiểm tra phản hồi đã phân tích của hành động kiểm thử và chọn các trường tương ứng với data.gender, data.result_status và các đường dẫn V2 khác bên dưới. Bộ chọn trường của Zapier có thể làm phẳng nhãn của các trường lồng nhau; hãy dựa vào giá trị thực tế quan sát được và đường dẫn cha thay vì mặc định dùng trường probability cũ của trình kết nối gốc. Chỉ cập nhật người đăng ký Mailchimp có ID đã lưu.

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

Trước khi bật Zap, hãy xem lại thiết lập "Autoreplay" và chạy lại thủ công ("Replay") của Zapier. Việc chạy lại một hành động webhook thất bại sẽ gửi một yêu cầu mới. Đừng chạy lại một yêu cầu đã thành công chỉ để sửa một bước Mailchimp phía sau. Hãy lưu ID gốc của người đăng ký cùng với kết quả của yêu cầ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 đó.

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

Vì sao cấu hình Zapier dùng options__ai_mode?

Hành động POST có cấu trúc của Webhooks dùng hai dấu gạch dưới để tạo JSON lồng nhau. API nhận được options: {ai_mode: off}, trong đó off là một chuỗi. API không nhận nguyên văn một trường cấp cao nhất tên là options__ai_mode.

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.