# Conecte o Pipedream à GenderAPI.io V2

> Conecte o Pipedream à GenderAPI.io V2 para registros do Twilio SendGrid. 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/pipedream-gender-api-integration

Last reviewed: 2026-09-29

## Escolha a conexão do Pipedream 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 componente público da GenderAPI.io no Pipedream, revisado em 26 de setembro de 2026, usa a base antiga https://api.genderapi.io/api e envia name ou email, um country opcional e a chave de API como parâmetros da string de consulta. A implementação publicada é um conector da V1, e não um endpoint JSON da V2.

Você pode manter a ação nativa existente com o contrato dela ou adicionar uma etapa HTTP genérica para a V2. Não presuma que a autenticação automática da conta conectada de forma nativa sirva para esta requisição separada da V2: a receita usa explicitamente um cabeçalho Bearer.

- [Aplicativo da GenderAPI.io no Pipedream](https://pipedream.com/apps/genderapi-io)
- [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 Twilio SendGrid 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 Pipedream

- Escolha um evento do Twilio SendGrid ou um agendamento adequado à sua conta e ao seu fluxo de trabalho. Verifique um contato de teste, salve o ID estável dele e ignore endereços de e-mail vazios antes da etapa de enriquecimento. O intervalo disponível para o gatilho é uma configuração da plataforma, e não um compromisso da GenderAPI.
- Adicione a ação Send any HTTP Request, escolha POST e informe a URL abaixo. Configure um corpo JSON com type = email, value = o endereço de e-mail do contato e options.ai_mode = off.
- Salve a chave com os controles de credenciais ou de variáveis de ambiente do Pipedream. Defina Authorization como Bearer seguido do segredo e Content-Type como application/json. Não continue com a autenticação nativa com a chave na string de consulta e não exiba a chave em nenhuma etapa.
- Crie o corpo como um objeto JSON com os controles de mapeamento que a ação suporta. Não monte JSON bruto concatenando os valores do contato sem escapar caracteres especiais. Verifique a pré-visualização da requisição antes de executar um teste limitado.

| 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 Pipedream**

```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

Revise a resposta que a etapa HTTP exporta e localize o corpo interpretado. Se a ação escolhida retornar o corpo como texto, interprete-o uma vez antes de ler data e meta. O campo data do envelope de transporte não é o mesmo que o campo data do corpo da V2.

Para um fluxo de trabalho baseado em código, com controle explícito de timeout, redirecionamentos e novas tentativas, você pode usar o guia de Node.js testado abaixo. A ação genérica e o aplicativo nativo podem ter configurações de transporte padrão diferentes.

- [Componente público da GenderAPI.io no Pipedream](https://github.com/PipedreamHQ/pipedream/blob/master/components/genderapi_io/genderapi_io.app.mjs)
- [Ações de requisição HTTP no Pipedream](https://pipedream.com/docs/workflows/building-workflows/http)
- [Variáveis de ambiente secretas no Pipedream](https://pipedream.com/docs/workflows/environment-variables)
- [Configurações de fluxos de trabalho e novas tentativas no Pipedream](https://pipedream.com/docs/workflows/building-workflows/settings)

## 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 Twilio SendGrid

Salve o ID do contato retornado pelo gatilho junto com o corpo da V2 interpretado. Atualize somente os campos personalizados planejados no SendGrid, depois das verificações de resultado acima. Preserve o nome que o próprio contato informou: um data.name inferido do endereço de e-mail é um candidato inferido, e não uma substituição confirmada.

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

O Pipedream documenta novas tentativas automáticas a partir da etapa que falhou, dependendo do plano. Verifique essas configurações e o comportamento de novas tentativas da ação HTTP escolhida. Uma nova tentativa em uma etapa de enriquecimento que falhou pode gerar novos custos. Uma falha posterior no sistema de destino deve ser corrigida com a saída salva do enriquecimento.

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)

## A ação nativa da GenderAPI.io no Pipedream usa a V2?

O componente público revisado em 26 de setembro de 2026 usa os endpoints antigos da V1 e autenticação com a chave na string de consulta. Para uma requisição da V2, use a receita HTTP explícita para a V2 e verifique novamente o componente publicado se a versão dele mudar.

## 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 Pipedream](https://pipedream.com/apps/genderapi-io)
- [Componente público da GenderAPI.io no Pipedream](https://github.com/PipedreamHQ/pipedream/blob/master/components/genderapi_io/genderapi_io.app.mjs)
- [Ações de requisição HTTP no Pipedream](https://pipedream.com/docs/workflows/building-workflows/http)
- [Variáveis de ambiente secretas no Pipedream](https://pipedream.com/docs/workflows/environment-variables)
- [Configurações de fluxos de trabalho e novas tentativas no Pipedream](https://pipedream.com/docs/workflows/building-workflows/settings)
- [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)