Escolha a conexão do Integrately 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.
A página da GenderAPI.io no Integrately faz referência a genderapi.io e oferece ações para nomes, endereços de e-mail e extração do nome a partir de um endereço de e-mail. Ela não informa a versão da API subjacente nem o esquema completo da saída. Os nomes das ações não bastam, por si só, para confirmar a compatibilidade com a V2.
O Integrately documenta Webhook/API como uma ação POST de saída. Os controles atuais de cabeçalhos e o editor JSON não foram verificados de forma independente para este guia. Aplique o contrato HTTP da V2 abaixo somente depois de confirmar que a sua ação consegue enviar um cabeçalho Authorization e um corpo JSON aninhado. As ações nativas existentes mantêm o próprio contrato de campos.
Prepare a conta e o registro de origem
Este exemplo enriquece registros do Mailchimp com base no nome. 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.
Configure a requisição da GenderAPI.io V2 no Integrately
- Escolha um gatilho de assinantes do Mailchimp e verifique um registro de teste. Salve o ID do público (Audience) e do assinante para a atualização, selecione o campo de nome real e ignore os registros sem nome.
- Localize Webhook/API e a ação correspondente para enviar dados a uma URL. Verifique a configuração disponível antes de continuar: o contrato abaixo exige cabeçalhos autenticados e um corpo JSON aninhado, e os controles atuais do editor não foram verificados de forma independente aqui.
- Se a ação atender a esses requisitos, escolha POST e o endpoint da V2 abaixo. Com os controles disponíveis na sua conta, confirme que a requisição de saída contém Authorization: Bearer YOUR_API_KEY e Content-Type: application/json.
- Crie um corpo JSON com type = name, value = o nome mapeado e options com ai_mode = off. Verifique a pré-visualização da requisição para a ação escolhida: um payload de formulário plano não é um corpo JSON da V2, mesmo que o cabeçalho Content-Type esteja definido.
- Para nomes dinâmicos, use os controles de mapeamento ou de serialização JSON da plataforma. Se a ação escolhida não conseguir preservar JSON aninhado ou cabeçalhos autenticados, use uma etapa com suporte a HTTP em vez de escrever a chave ou o JSON nos parâmetros da string de consulta.
| 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.
{
"type": "name",
"value": "Alice",
"options": {
"ai_mode": "off"
}
}Verifique a etapa HTTP antes de ativar as atualizações
Teste uma ação de forma limitada e revise o corpo retornado antes de escolher campos nas etapas seguintes. As etapas nativas da GenderAPI.io e as etapas Webhook/API podem exibir rótulos de campo diferentes, mesmo para o mesmo cliente de origem.
Guarde a chave nos controles destinados à conexão ou à autenticação da requisição e restrinja quem pode ver ou compartilhar a automação. Este guia público não contém uma chave válida, uma conexão exportada nem uma atualização de clientes pré-configurada.
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. |
Atualize somente o registro correspondente no Mailchimp
Use os IDs salvos do público (Audience) e do assinante do Mailchimp para selecionar o registro de destino. Adicione condições para o status do resultado e para as verificações de acesso e de cobrança acima antes de gravar dados em um campo destinado a dados inferidos ou em uma tag aprovada. Nunca converta um gênero ausente ou o valor null em uma categoria padrão para o contato.
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.
Controle novas tentativas e cobranças repetidas
O Integrately documenta novas tentativas automáticas, incluindo configurações que valem para toda a empresa. Verifique a política e o histórico de atividades antes de ativar esta automação e avalie o impacto em outros fluxos de trabalho antes de alterar uma configuração compartilhada. Cada requisição HTTP repetida é uma requisição independente e cobrada. Salve as saídas concluídas para poder corrigir uma falha posterior no Mailchimp sem uma nova 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.
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 |
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.
Perguntas frequentes
Posso mapear o campo probability da antiga ação nativa para o campo confidence da V2?
Verifique primeiro o contrato de resposta. Uma requisição direta à V2 retorna data.confidence junto com data.confidence_kind em uma escala de 0 a 1 ou como null. Nada sustenta a suposição de que os rótulos de campo e a escala do conector nativo correspondam a esses caminhos.
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
A última revisão da versão em português foi em . As informações sobre as plataformas se baseiam na documentação pública delas, revisada em 26 de setembro de 2026. A revisão não é um novo teste com uma conta conectada. Confira a configuração e a disponibilidade atuais na documentação oficial das plataformas.