# Integra GenderAPI.io V2 con Zapier

> Conecta registros de Mailchimp con GenderAPI.io V2 mediante HTTP en Zapier. Configura el JSON, interpreta los resultados y controla créditos, errores y reintentos.

Canonical HTML: https://www.genderapi.io/es/blog/zapier-gender-api-integration

Last reviewed: 2026-09-28

## Distingue la versión de API de tu conexión de Zapier

Esta guía HTTP utiliza https://api.genderapi.io/api/v2/gender. Envía type y value en JSON; la predicción está en data y la información de solicitud y uso, en meta.

Zapier incluye acciones de GenderAPI.io para nombres y correos. La ficha pública no confirma la versión del endpoint ni el contrato de respuesta V2; revisa la salida de las acciones existentes. Esta configuración usa Webhooks by Zapier, disponible en planes de pago. Las tareas de Zapier y el saldo de GenderAPI se contabilizan por separado.

- [Ficha de GenderAPI.io en Zapier](https://zapier.com/apps/gender-api/integrations)
- [Referencia de V1](https://www.genderapi.io/es/api-documentation/v1)

## Prepara la cuenta y el registro de origen

Necesitas acceso a las aplicaciones de origen y destino, una clave de cuenta de GenderAPI y las funciones HTTP de la plataforma. Esta guía no incluye credenciales ni cuentas conectadas. Conserva el identificador del registro y filtra los correos vacíos antes de consultar.

V1 y V2 comparten la clave de cuenta y el saldo. Antes de enviar consultas con coste, comprueba la clave con GET /api/v2/usage y verifica que meta.access.mode sea api_key. Una clave ausente o no reconocida puede activar la prueba compartida por IP; una automatización de producción no debe depender de ella sin advertirlo.

Mantén el flujo desactivado durante la configuración. Una consulta de prueba también consume créditos. Estas instrucciones se revisaron con la documentación pública y el contrato V2; no se ejecutaron de principio a fin en una cuenta conectada.

- [Autenticación y comprobación del acceso](https://www.genderapi.io/es/docs/v2/authentication#environment-setup)

## Configura la solicitud HTTP V2 en Zapier

- Elige el disparador de Mailchimp que proporcione el suscriptor previsto. Conserva los identificadores de audiencia y contacto, y filtra los correos vacíos antes del paso HTTP.
- Selecciona Webhooks by Zapier > POST y Payload Type: JSON. Añade type = email, value = correo del suscriptor y options__ai_mode = off.
- La doble barra baja convierte options__ai_mode en el campo ai_mode del objeto options. La API no debe recibir un campo options__ai_mode en el nivel superior.
- En Headers, configura Authorization: Bearer YOUR_API_KEY y Content-Type: application/json. No incluyas la clave en la URL, los campos del disparador ni las respuestas de ejemplo.

| Configuración HTTP | Valor | Finalidad |
| --- | --- | --- |
| `Method` | `POST` | Envía una consulta individual. |
| `URL` | `https://api.genderapi.io/api/v2/gender` | Endpoint V2 de predicción individual. |
| `Authorization` | `Bearer YOUR_API_KEY` | Añade la clave real mediante los controles de credenciales o encabezados de la plataforma. |
| `Content-Type` | `application/json` | Envía JSON con el objeto options anidado, no datos de formulario. |
| `options.ai_mode` | `off` | Solo conjunto de datos por decisión explícita: 1 crédito, incluso si el resultado es unknown. |

## Revisa el cuerpo JSON antes de enviarlo

Este es un ejemplo fijo de entrada, no una predicción. Comprueba su estructura y asigna a value el campo de origen mediante las herramientas de serialización JSON. No envíes expresiones de asignación de la plataforma como texto literal.

Para otra entrada, elige name, email o username en type y envía el value correspondiente. country es opcional: inclúyelo solo si dispones de ese contexto. No sirve para averiguar el país de residencia de la persona.

**Solicitud JSON V2 para Zapier**

```json
{
  "type": "email",
  "value": "alex@example.com",
  "options": {
    "ai_mode": "off"
  }
}
```

- [Parámetros, tipos y valores predeterminados](https://www.genderapi.io/es/docs/v2/request-parameters)

## Revisa el paso HTTP antes de activar las actualizaciones

Los encabezados de Webhooks no son un almacén de credenciales separado: quienes editan el Zap pueden verlos. Limita el acceso y evita compartir capturas o exportaciones con la clave. API by Zapier ofrece credenciales guardadas, pero la configuración de su cuerpo difiere de esta receta POST.

Envía un único objeto sin envolverlo en una lista o matriz. Usa el JSON estructurado para los datos del cliente. Custom Request envía texto sin procesar y no escapa automáticamente los valores insertados.

- [Documentación de Zapier: integrations](https://zapier.com/apps/gender-api/integrations)
- [Documentación de Zapier: 8496326446989-Send-webhooks-in-Zap-workflows](https://help.zapier.com/hc/en-us/articles/8496326446989-Send-webhooks-in-Zap-workflows)
- [Documentación de Zapier: 44391660158733-How-to-get-started-with-API-by-Zapier](https://help.zapier.com/hc/en-us/articles/44391660158733-How-to-get-started-with-API-by-Zapier)
- [Documentación de Zapier: 19220226086797-What-is-replay](https://help.zapier.com/hc/en-us/articles/19220226086797-What-is-replay)

## Separa los resultados identificados, desconocidos y los errores

Analiza el cuerpo de la respuesta antes de actualizar el registro. Las rutas siguientes pertenecen al cuerpo V2; la plataforma puede anidarlo en otro campo o aplanar sus etiquetas. Inspecciona la estructura en una prueba controlada y guarda el resultado junto al identificador de origen.

Una predicción no verifica la identidad ni la declaración de la persona. Guarda la inferencia por separado de la información que esta haya proporcionado. Evalúa el umbral de aceptación con tus datos y distingue las puntuaciones del conjunto de datos de las de IA.

| Comprobación | Valor o tipo esperado | Decisión del flujo |
| --- | --- | --- |
| `meta.access.mode` | api_key | Si aparece ip_trial, detén el flujo y corrige la clave. Una respuesta de prueba no autentica la cuenta y puede haber consumido créditos de prueba. |
| `meta.usage.billing_status` | confirmed o unconfirmed | Si es unconfirmed, guarda request_id y aclara el cargo antes de continuar o reenviar. |
| `data.result_status / data.gender` | identified con male/female; unknown con null | Guarda una predicción aceptada en un campo de inferencia separado. No asignes una categoría predeterminada a unknown. |
| `data.confidence / data.confidence_kind` | 0–1 o null; tipo de evidencia o null | Interpreta observed_frequency y model_reported por separado. Ninguno garantiza la exactitud general. |
| `data.source / data.sample_count` | dataset, ai, none / entero o null | Conserva la fuente. La IA no tiene un recuento de muestras registrado; el recuento del conjunto de datos no es una medida de exactitud del producto. |
| `meta.request_id / meta.usage` | Referencia de solicitud / objeto de uso | Guárdalos con el registro de trabajo. Evita registrar la clave y datos personales innecesarios. |
| `Error HTTP / respuesta incompleta` | Problem Details o falta de respuesta completa | Detén la actualización y revisa el error y el cargo. Un tiempo de espera agotado no demuestra que el servidor no haya procesado la consulta. |

- [Campos de respuesta V2](https://www.genderapi.io/es/docs/v2/responses)
- [Errores y reintentos](https://www.genderapi.io/es/docs/v2/errors-and-retries)

## Actualiza únicamente el registro correcto de Mailchimp

Busca data.gender, data.result_status y las demás rutas V2 en la respuesta de prueba. El selector puede aplanar etiquetas anidadas: usa el valor y su ruta observados, sin asumir un campo probability antiguo. Actualiza solo el suscriptor de Mailchimp cuyo identificador guardaste.

Prueba las ramas de resultados identificados, desconocidos y errores antes de activar las actualizaciones. Puedes usar respuestas simuladas sin enviar nuevas predicciones. La actualización debe depender de esas comprobaciones y conservar los campos y etiquetas ajenos al flujo.

- [Campos de respuesta](https://www.genderapi.io/es/docs/v2/responses)

## Controla los reintentos y los cargos adicionales

Antes de activar el Zap, revisa Autoreplay y los reintentos manuales. Repetir un webhook fallido envía una consulta nueva. No repitas una predicción correcta para reparar un paso posterior de Mailchimp: guarda juntos los identificadores del suscriptor y el resultado.

Cada nueva solicitud a GenderAPI es una operación independiente. Deduplica los eventos en tu flujo antes de enviarlos, usando el identificador de origen y el estado del trabajo. Ese identificador no evita por sí solo nuevos cargos en el servidor.

Un resultado unknown correcto es una consulta completada con coste. Si se agota el tiempo de espera o falta la respuesta, el resultado y el cargo pueden ser inciertos. Conserva la referencia de solicitud disponible y aclara el estado antes de reenviar. Respeta Retry-After cuando se incluya en una respuesta de límite de solicitudes.

- [Créditos y estado del cargo](https://www.genderapi.io/es/docs/v2/credits-and-usage)

## Elige cuándo utilizar la IA

forceToGenderize es opcional para nombres, correos electrónicos y nombres de usuario. Si lo activas, omite ai_mode o utiliza fallback; combinarlo con off o always devuelve un error 422. Basta con un saldo inicial positivo para iniciar la consulta, aunque el cargo final deje el saldo por debajo de cero.

El análisis de alias puede devolver un género con name: null. También puede devolver unknown. Ni el respaldo estándar de IA ni el análisis de alias garantizan una respuesta correcta o distinta de null.

| Opción de la solicitud | Comportamiento | Créditos por consulta completada |
| --- | --- | --- |
| options.ai_mode: off | Consulta únicamente el conjunto de datos. | 1 crédito, incluido unknown |
| options.ai_mode: fallback | Consulta primero el conjunto de datos y recurre a la IA estándar si no obtiene un género. Es el modo predeterminado de las consultas individuales. | 1 crédito en total, incluido el respaldo de IA |
| options.ai_mode: always | Consulta directamente a la IA. | 2 créditos |
| forceToGenderize: true | Consulta primero el conjunto de datos; si no encuentra un género, permite interpretar el significado de un alias personal, aunque no contenga un nombre real. | 1 crédito si el conjunto de datos resuelve la consulta; 2 en total si se utiliza IA |

- [Opciones de IA y análisis de alias](https://www.genderapi.io/es/docs/v2/ai-options)
- [Créditos y uso](https://www.genderapi.io/es/docs/v2/credits-and-usage)

## Valida el flujo antes de aumentar el volumen

- En una prueba deliberada, comprueba el JSON enviado, las rutas de los campos, el acceso de cuenta y la confirmación del cargo. Prueba las ramas de resultados desconocidos y errores con respuestas simuladas cuando sea posible.
- Comprueba qué pasos se repiten y qué campos del cliente cambian. Guarda el identificador de origen, la respuesta completada y la referencia de solicitud para poder corregir una actualización posterior sin repetir la predicción.
- Empieza con una ejecución pequeña y controlada. Revisa los registros y créditos antes de aumentar la concurrencia. Los créditos de GenderAPI y las tareas u operaciones de la plataforma son costes distintos.
- Para lotes, usa POST /api/v2/gender/batch: hasta 50 elementos con clave de cuenta y 10 en la prueba por IP. items puede combinar nombres, correos y usuarios; asigna opciones explícitas e identificadores únicos. HTTP 200 puede contener fallos parciales: revisa cada elemento. Verifica por separado el soporte de lotes del conector nativo.

- [Lotes y fallos parciales](https://www.genderapi.io/es/docs/v2/batch)
- [Guía de Python](https://www.genderapi.io/es/integrations/python)
- [Guía de Node.js](https://www.genderapi.io/es/integrations/javascript)

## ¿Por qué la configuración de Zapier utiliza options__ai_mode?

La acción POST estructurada de Webhooks convierte la doble barra baja en JSON anidado. La API recibe el texto off en ai_mode, dentro de options; no recibe options__ai_mode como campo de nivel superior.

## ¿Puedo usar IA en esta conexión HTTP?

El ejemplo inicial utiliza options.ai_mode: off. fallback permite recurrir a IA con un coste total de 1 crédito; always usa IA directamente por 2 créditos. forceToGenderize consulta primero el conjunto de datos: cuesta 1 crédito si encuentra un resultado y 2 en total si utiliza IA.

## ¿Un resultado desconocido es gratuito o se puede repetir automáticamente?

No. Un resultado unknown correcto está completado y tiene coste. Repetirlo es una nueva operación. Ante un error de conexión o un cargo sin confirmar, revisa el uso y la referencia de solicitud antes de reenviar.

## ¿Se ha ejecutado este flujo en una cuenta conectada?

No. La configuración se revisó con documentación pública de las plataformas y el contrato V2. Antes de activar actualizaciones de producción, prueba los campos de la acción, la autenticación, el cuerpo, la respuesta y los reintentos en tu cuenta.

## Documentación de referencia

- [Documentación oficial de Zapier: Zapier GenderAPI.io app listing](https://zapier.com/apps/gender-api/integrations)
- [Documentación oficial de Zapier: Zapier structured Webhooks requests and nested JSON](https://help.zapier.com/hc/en-us/articles/8496326446989-Send-webhooks-in-Zap-workflows)
- [Documentación oficial de Zapier: API by Zapier credential connections](https://help.zapier.com/hc/en-us/articles/44391660158733-How-to-get-started-with-API-by-Zapier)
- [Documentación oficial de Zapier: Zapier replay behavior](https://help.zapier.com/hc/en-us/articles/19220226086797-What-is-replay)
- [Referencia de GenderAPI V2](https://www.genderapi.io/es/docs/v2/request-parameters)
- [Referencia de GenderAPI V2](https://www.genderapi.io/es/docs/v2/responses)
- [Referencia de GenderAPI V2](https://www.genderapi.io/es/docs/v2/credits-and-usage)