# Conecte o Zapier à GenderAPI.io V2

> Conecte o Zapier à GenderAPI.io V2 para registros do Mailchimp. Escolha o conector certo, envie type e value e depois trate data, meta, créditos e erros.

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

Last reviewed: 2026-09-29

## Escolha a conexão do Zapier adequada ao seu contrato de API

A receita HTTP deste guia chama a GenderAPI.io V2 em https://api.genderapi.io/api/v2/gender. Envie type e value no corpo JSON. A previsão fica em data, e as informações sobre a requisição e a cobrança ficam em meta. Os conectores nativos têm contratos próprios, descritos abaixo.

O Zapier oferece ações da GenderAPI.io para determinar o gênero a partir de um nome ou de um endereço de e-mail. A página pública não informa a versão do endpoint nem o contrato de resposta da V2. Verifique a saída das ações nativas existentes antes de alterar os mapeamentos nas etapas seguintes.

A configuração da V2 abaixo usa o Webhooks by Zapier com uma requisição POST estruturada. O Webhooks by Zapier exige um plano pago do Zapier. O saldo da conta da GenderAPI e as tarefas usadas no Zapier são cobrados separadamente.

- [Aplicativo da GenderAPI.io no Zapier](https://zapier.com/apps/gender-api/integrations)
- [Documentação existente da V1](https://www.genderapi.io/pt/api-documentation/v1)

## Prepare a conta e o registro de origem

Este exemplo enriquece registros do Mailchimp com base no endereço de e-mail. Você precisa de acesso ao aplicativo de origem e ao de destino, de uma chave de conta da GenderAPI.io e dos recursos da plataforma usados pela ação HTTP. O guia não contém credenciais válidas nem contas conectadas.

A V1 e a V2 usam a mesma chave de conta e o mesmo saldo. Antes de configurar uma requisição paga, verifique a chave com GET /api/v2/usage e confirme que meta.access.mode tem o valor api_key na resposta desse endpoint. Uma chave ausente ou não reconhecida pode recorrer ao teste por IP compartilhado. Uma automação em produção não deve depender disso sem que você saiba.

Mantenha o fluxo de trabalho desativado enquanto o configura. Uma previsão de teste consome créditos normais. As instruções foram revisadas com base na documentação pública e no contrato da V2. Nenhum fluxo de trabalho autenticado foi executado de ponta a ponta em nenhuma plataforma para esta publicação.

- [Autenticação e verificação gratuita do uso](https://www.genderapi.io/pt/docs/v2/authentication#environment-setup)

## Configure a requisição da GenderAPI.io V2 no Zapier

- Comece com um gatilho do Mailchimp que forneça o registro de assinante correto. Salve o ID do público (Audience) e do contato e adicione um filtro antes da ação HTTP que ignore endereços de e-mail vazios.
- Escolha Webhooks by Zapier e a ação POST. Informe a URL abaixo e Payload Type: JSON. Adicione os campos de dados type = email, value = o endereço de e-mail mapeado do assinante e options__ai_mode = off.
- No Zapier, a notação com sublinhado duplo options__ai_mode é aninhada como options.ai_mode no corpo JSON. O bloco de código abaixo mostra o corpo que a API recebe. Não é um quarto campo que você precise adicionar na ação.
- Adicione Authorization com o valor Bearer YOUR_API_KEY na seção Headers. Use application/json como Content-Type. Não escreva a chave nos campos do gatilho, na string de consulta nem em respostas de exemplo.

| Configuração HTTP | Valor | Finalidade |
| --- | --- | --- |
| `Method` | `POST` | Envia uma requisição de previsão. |
| `URL` | `https://api.genderapi.io/api/v2/gender` | Endpoint da GenderAPI.io V2 para previsões individuais. |
| `Authorization` | `Bearer YOUR_API_KEY` | Substitua o espaço reservado nas configurações de autenticação ou de cabeçalhos da plataforma. |
| `Content-Type` | `application/json` | Envia um objeto com um objeto options aninhado, e não campos de formulário. |
| `options.ai_mode` | `off` | Primeiro teste intencional apenas com o conjunto de dados: cobrança normal de 1 crédito, mesmo que o resultado seja unknown. |

## Verifique o corpo JSON antes de enviá-lo

O exemplo mostra uma entrada fixa. Não é um resultado esperado. Verifique primeiro a estrutura da requisição e depois substitua value pelo campo de origem mapeado, usando uma serialização JSON correta. Não envie à API as expressões de mapeamento da plataforma como texto literal.

Para outras entradas, defina type como name, email ou username e informe o valor correspondente em value. Adicione country somente se você tiver um contexto confiável. O campo é opcional e não serve para determinar em que país uma pessoa mora.

**Requisição JSON da V2 para Zapier**

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

- [Campos, tipos e valores padrão da requisição](https://www.genderapi.io/pt/docs/v2/request-parameters)

## Verifique a etapa HTTP antes de ativar as atualizações

Os cabeçalhos do webhook não são um campo destinado a segredos: qualquer pessoa que possa editar o Zap consegue vê-los. Restrinja o acesso e não compartilhe o Zap, capturas de tela ou exportações que contenham credenciais. O Zapier também oferece o API by Zapier com credenciais salvas, mas nele a configuração do corpo da requisição é diferente desta receita POST estruturada.

Não encapsule o corpo: envie um único objeto, e não uma lista ou um array. Escolha a ação JSON estruturada para dados de clientes mapeados. Custom Request envia texto bruto e não escapa automaticamente caracteres especiais nos valores inseridos.

- [Requisições de webhook estruturadas e JSON aninhado no Zapier](https://help.zapier.com/hc/en-us/articles/8496326446989-Send-webhooks-in-Zap-workflows)
- [Conexões com credenciais no API by Zapier](https://help.zapier.com/hc/en-us/articles/44391660158733-How-to-get-started-with-API-by-Zapier)
- [Como funciona a repetição (Replay) no Zapier](https://help.zapier.com/hc/en-us/articles/19220226086797-What-is-replay)

## Trate identified, unknown e erros separadamente

Interprete o corpo da resposta antes de escolher uma atualização no sistema de destino. Os caminhos JSON abaixo se referem ao corpo da resposta da V2. A sua plataforma pode encapsulá-lo ou achatá-lo. Verifique a estrutura realmente retornada com um teste limitado e salve o resultado junto com o ID do registro de origem.

Uma previsão não determina a identidade de uma pessoa nem o gênero que ela mesma declara. Armazene-a separadamente das informações fornecidas pela própria pessoa. Defina critérios de aceitação com dados representativos do seu caso de uso e avalie separadamente a confiança do conjunto de dados e a confiança da IA.

| Verificação | Valor ou tipo esperado | Decisão no fluxo de trabalho |
| --- | --- | --- |
| `meta.access.mode` | api_key para este fluxo de trabalho com conta | Interrompa o fluxo de trabalho se o valor for ip_trial e corrija a chave. Uma resposta bem-sucedida pelo teste por IP não comprova que a conta foi autenticada e pode já ter consumido créditos do teste. |
| `meta.usage.billing_status` | confirmed ou unconfirmed | Se o valor for unconfirmed, salve o ID da requisição e esclareça a cobrança antes de tentar novamente ou continuar. |
| `data.result_status / data.gender` | identified com male ou female; unknown com null | Salve os resultados identified aceitos em um campo destinado a dados inferidos. Preserve os resultados unknown sem atribuir uma categoria padrão. |
| `data.confidence / data.confidence_kind` | Número de 0 a 1 ou null; tipo de evidência ou null | Interprete observed_frequency e model_reported separadamente. Nenhum dos valores garante uma precisão geral. |
| `data.source / data.sample_count` | dataset, ai ou none / número inteiro ou null | Salve a origem da previsão. A IA não tem um tamanho de amostra armazenado, e um tamanho de amostra do conjunto de dados não é uma medida da precisão do produto. |
| `meta.request_id / meta.usage` | Referência da requisição / objeto de uso | Salve ambos junto com o registro do fluxo de trabalho e o resultado. Não grave chaves de API nem dados pessoais desnecessários em logs comuns. |
| `Erro HTTP / nenhuma resposta` | Problem Details ou nenhuma resposta completa | Interrompa a atualização e verifique o erro e o status da cobrança. Um timeout não comprova que o servidor não processou nada. |

- [Documentação completa da resposta da V2](https://www.genderapi.io/pt/docs/v2/responses)
- [Erros, timeouts e decisões sobre novas tentativas](https://www.genderapi.io/pt/docs/v2/errors-and-retries)

## Atualize somente o registro correspondente no Mailchimp

Revise a resposta interpretada da ação de teste e selecione os campos para data.gender, data.result_status e os demais caminhos da V2 indicados acima. O seletor de campos do Zapier pode achatar rótulos aninhados: baseie-se no valor observado e no caminho de nível superior, em vez de presumir o antigo campo probability do conector nativo. Atualize somente o assinante do Mailchimp cujo ID foi salvo.

Teste as ramificações para um resultado identified, um resultado unknown e um erro antes de ativar as atualizações. Com respostas de exemplo fictícias, você pode verificar as condições da ramificação sem enviar uma nova previsão. A atualização no aplicativo de destino deve depender das verificações acima e não pode sobrescrever campos ou tags que não tenham relação com ela.

- [Campos da resposta e resultados desconhecidos](https://www.genderapi.io/pt/docs/v2/responses)
- [Precisão e confiança explicadas](https://www.genderapi.io/pt/accuracy-methodology)
- [Fontes de dados e perfil datado do banco de dados](https://www.genderapi.io/pt/data-provenance)

## Controle novas tentativas e cobranças repetidas

Verifique as configurações de Autoreplay e de repetição manual (Replay) no Zapier antes de ativar o Zap. Se você repetir uma ação de webhook que falhou, uma nova requisição é enviada. Não repita uma requisição concluída apenas para corrigir uma etapa posterior do Mailchimp. Salve juntos o ID original do assinante e o resultado da requisição.

Cada nova requisição à GenderAPI é uma operação independente. Elimine duplicatas de eventos de origem repetidos no seu fluxo de trabalho antes do envio, usando o ID de origem salvo e o status de processamento. O ID do registro de origem não é uma chave que proteja contra repetições no lado do servidor.

Um resultado unknown concluído é um resultado completo e cobrado. Em caso de timeout ou de resposta incompleta, tanto o resultado quanto a cobrança podem ser desconhecidos: salve a referência da requisição, se houver, e esclareça a cobrança antes de enviar a requisição novamente. Respeite o cabeçalho Retry-After quando ele acompanhar uma resposta de limite de requisições excedido.

- [Créditos e status da cobrança](https://www.genderapi.io/pt/docs/v2/credits-and-usage)

## Decidir quando usar a IA

forceToGenderize é opcional para nomes, endereços de e-mail e nomes de usuário. Quando ativado, omita ai_mode ou use fallback; off e always não podem ser combinados com essa opção e retornam 422. Um saldo inicial positivo basta para iniciar uma requisição, mesmo que a cobrança final deixe o saldo negativo.

O modo de apelidos pode retornar um gênero junto com name: null. Ele também pode dar um resultado desconhecido. Nem o fallback de IA comum nem a interpretação de apelidos garantem uma resposta correta ou um valor diferente de null.

| Opção da requisição | Comportamento | Créditos por consulta bem-sucedida |
| --- | --- | --- |
| options.ai_mode: off | Usa apenas o conjunto de dados. | 1, inclusive para um resultado desconhecido |
| options.ai_mode: fallback | Consulta primeiro o conjunto de dados e depois usa a IA comum se nenhum gênero for retornado. É o padrão das requisições individuais. | 1 no total, incluindo o fallback de IA |
| options.ai_mode: always | Usa a IA diretamente. | 2 |
| forceToGenderize: true | Consulta primeiro o conjunto de dados e depois deixa a IA interpretar um apelido pessoal ou um alias, mesmo sem um nome próprio real. | 1 para um resultado encontrado no conjunto de dados; 2 no total se a IA for usada |

- [Opções de IA e interpretação de apelidos](https://www.genderapi.io/pt/docs/v2/ai-options)
- [Créditos e uso](https://www.genderapi.io/pt/docs/v2/credits-and-usage)

## Verifique o fluxo de trabalho antes de aumentar o volume

- Com um teste limitado, verifique o JSON realmente serializado, os caminhos de resultado interpretados, o acesso com chave de API e a confirmação da cobrança. Se possível, teste o tratamento de resultados unknown e de erros com respostas de exemplo.
- Defina quais etapas do fluxo de trabalho se repetem e quais campos de clientes são alterados. Salve o ID do registro de origem, a resposta recebida e a referência da requisição, para que uma falha posterior no sistema de destino não exija uma nova requisição.
- Ative primeiro uma execução pequena e controlada e verifique os registros e os créditos antes de aumentar o paralelismo. Os créditos da GenderAPI e as tarefas ou operações cobradas pela plataforma de automação são custos separados.
- Para lotes, use POST /api/v2/gender/batch com até 50 itens no acesso com chave de API ou 10 no teste por IP. O array items pode misturar nomes, endereços de e-mail e nomes de usuário com opções explícitas e um ID exclusivo para cada item. Verifique cada resultado: uma resposta HTTP 200 pode conter erros em itens individuais. Se um conector nativo oferece suporte a lotes, isso precisa ser verificado separadamente.

- [Lotes e erros em itens individuais](https://www.genderapi.io/pt/docs/v2/batch)
- [Guia de implementação para Python](https://www.genderapi.io/pt/integrations/python)
- [Guia de implementação para Node.js](https://www.genderapi.io/pt/integrations/javascript)

## Por que a configuração no Zapier usa options__ai_mode?

A ação POST estruturada do Webhooks usa um sublinhado duplo para criar JSON aninhado. A API recebe options: {ai_mode: off}, em que off é uma string. Ela não recebe um campo literal options__ai_mode no nível superior.

## O exemplo HTTP direto usa IA?

O corpo da primeira requisição define options.ai_mode como off. Altere o valor intencionalmente para fallback para usar o fallback de IA automático comum por 1 crédito no total, ou para always para usar a IA diretamente por 2 créditos. forceToGenderize consulta primeiro o conjunto de dados: custa 1 crédito se a requisição for resolvida ali, ou 2 no total se a IA for usada.

## Um resultado unknown é gratuito e pode ser repetido automaticamente com segurança?

Não. Um resultado unknown concluído é completo e cobrado. Uma nova tentativa é uma nova consulta. Em caso de erro de transporte ou de cobrança não confirmada, verifique os dados de uso retornados e a referência da requisição antes de decidir se ela deve ser enviada novamente.

## Este fluxo de trabalho foi executado com uma conta conectada?

Não. As instruções de configuração das plataformas foram revisadas em 26 de setembro de 2026 com base na documentação pública delas. As explicações sobre a requisição e a resposta da GenderAPI.io V2 foram revisadas em 27 de setembro de 2026. A revisão desta versão em português em 29 de setembro de 2026 é uma verificação da tradução, e não um novo teste com uma conta. Antes de ativar atualizações em produção, verifique com a sua própria conta os campos atuais da ação escolhida, a autenticação, o corpo da requisição, a resposta e as novas tentativas.

## Fontes e documentação

- [Aplicativo da GenderAPI.io no Zapier](https://zapier.com/apps/gender-api/integrations)
- [Requisições de webhook estruturadas e JSON aninhado no Zapier](https://help.zapier.com/hc/en-us/articles/8496326446989-Send-webhooks-in-Zap-workflows)
- [Conexões com credenciais no API by Zapier](https://help.zapier.com/hc/en-us/articles/44391660158733-How-to-get-started-with-API-by-Zapier)
- [Como funciona a repetição (Replay) no Zapier](https://help.zapier.com/hc/en-us/articles/19220226086797-What-is-replay)
- [Contrato de requisição da GenderAPI.io V2](https://www.genderapi.io/pt/docs/v2/request-parameters)
- [Contrato de resposta da GenderAPI.io V2](https://www.genderapi.io/pt/docs/v2/responses)
- [Cobrança e créditos da GenderAPI.io V2](https://www.genderapi.io/pt/docs/v2/credits-and-usage)