Fluxo de trabalho da API de validação de e-mails: do sandbox à produção com a FairValid

Fluxo de trabalho da API de validação de e-mails: do teste no sandbox aos resultados em produção

Pergunta: Você é um desenvolvedor adicionando verificação de e-mails ao seu próprio sistema. Quais etapas levam você de uma primeira chamada de teste a resultados confiáveis em produção?

Resposta curta: Comece com uma chave Test e o sandbox gratuito. Depois, passe para uma chave Live que tenha apenas os escopos de que você precisa. Envie cada submissão com uma chave de idempotência. Leia o estado do job e percorra os resultados página a página. Trate cada resultado e cada código de erro separadamente. As etapas abaixo seguem a referência da API para clientes da FairValid.

Etapa 1: desenvolva primeiro usando o sandbox

Crie uma chave Test na página de chaves da API e mantenha-a no seu servidor. A referência usa duas variáveis de ambiente, FAIRVALID_API_KEY e FAIRVALID_BASE_URL. As chaves Test não fazem chamadas ao provedor e não consomem créditos.

As chaves Test aceitam apenas um pequeno conjunto de endereços reservados no domínio example.com. Esses endereços simulam os resultados válido, inválido, catch-all, desconhecido, pendente e indisponível. Você encontra os endereços exatos na seção "Sandbox gratuito" da referência da API. Os jobs de teste retornam estados fixos e reproduzíveis: concluído, pendente, com falha ou cancelado. Os jobs de teste em lote permitem consultar status, resultados e cancelamento.

O sandbox mostra esses resultados específicos. Ele não cobre todos os caminhos que sua integração pode seguir, então planeje um tratamento separado para os códigos de erro descritos na Etapa 7.

Os jobs de teste em lote são limitados a 20 novos jobs por workspace por hora, ou 100 a cada 30 dias. Ultrapassar qualquer um desses limites retorna HTTP 429. Uma nova tentativa idêntica continua retornando o job original.

Etapa 2: passe para uma chave Live com os escopos de que você precisa

Para produção, crie uma chave Live com o escopo submit. Use POST /api/v1/jobs para lotes ou POST /api/v1/verifications para um único endereço. Adicione o escopo read se a chave também precisar ler o estado e os resultados dos jobs. As chaves Live também podem ter o escopo balance. À parte, GET /api/v1/balance lê os créditos disponíveis e retidos do workspace. O segredo completo é exibido apenas uma vez, então armazene-o com segurança ao criar a chave.

Os jobs Live usam a fila de verificação e o saldo de créditos do seu workspace. Os escopos e limites da chave, o acesso ao workspace e os limites de processamento continuam valendo.

Etapa 3: envie um job com uma chave de idempotência

Um job aceita de 1 a 5.000 endereços em JSON, com até 2 MiB. Envie um cabeçalho Idempotency-Key em cada envio de job e em cada envio Live de endereço único. A chave deve ter de 8 a 128 caracteres e pode usar letras, dígitos, pontos, dois-pontos, sublinhados ou hífens.

• Um novo job retorna HTTP 202 com um job_id no formato UUID.
• Uma nova tentativa correspondente retorna HTTP 200 com o mesmo job.
• Reutilizar uma chave de idempotência com um corpo alterado retorna HTTP 409 idempotency_conflict.

Se você não souber se uma requisição foi processada, tente novamente com a mesma chave da API, a mesma chave de idempotência e o mesmo corpo normalizado. A repetição é vinculada à chave da API, então substituir essa credencial e reenviar pode criar uma segunda execução. Use uma nova chave de idempotência apenas quando realmente quiser uma nova execução, que pode ser cobrada.

Etapa 4: leia o job e percorra os resultados

Leia o job com GET /api/v1/jobs/{id}. O status pode ser queued, running, paused, canceling, canceled ou completed. Leia os resultados com GET /api/v1/jobs/{id}/results. Cada página retorna até 50 resultados, além de um next_cursor assinado. Passe esse valor como o parâmetro de consulta cursor. Ele mantém o filtro e a pesquisa originais.

Os filtros são all, valid, invalid, catch_all, unknown, still_checking e not_checked. Para interromper um job, POST /api/v1/jobs/{id}/cancel solicita o cancelamento, mas o trabalho já em andamento ainda pode ser concluído.

A referência também descreve um evento de conclusão assinado e traz links para o gerenciamento de webhooks.

Etapa 5: trate cada resultado como um estado próprio

O guia de resultados explica o que cada resultado significa:

• Válido: uma verificação positiva utilizável. Nunca garante a entrega na caixa de entrada.
• Inválido: o endereço não passou na verificação.
• Catch-all: o domínio pode aceitar muitos endereços, então uma conclusão no nível da caixa de correio pode ser menos certa. Leia os detalhes antes de usá-lo.
• Desconhecido: a verificação não conseguiu retornar uma resposta confiável.
• Ainda em verificação: ainda não há uma resposta final.

O guia descreve as falhas técnicas e os itens não processados separadamente de Desconhecido, e a API oferece unknown, still_checking e not_checked como filtros separados. Mantenha esses estados em campos ou status separados nos seus próprios dados, em vez de agrupá-los como Desconhecido.

Etapa 6: entenda as retenções de créditos antes de conciliar

A referência da API informa que os créditos do workspace são reservados à medida que as verificações são admitidas para processamento. Os resultados seguem então as mesmas regras de cobrança e devolução do painel. A página de preços da FairValid informa que uma retenção de créditos reserva espaço para uma verificação em andamento e que o resultado final determina a cobrança:

• Válido ou inválido: 1 crédito por resultado concluído.
• Desconhecido ou catch-all: nenhum crédito de verificação é descontado no final. Os créditos retidos são liberados ou devolvidos ao saldo.
• Ainda em verificação: ainda não há cobrança final. Uma retenção não é uma cobrança concluída.
• Falhas técnicas e trabalho não processado: nenhum crédito de verificação é descontado no final. As reservas são liberadas ou devolvidas ao saldo.

Se você consultar o saldo no meio de um job, lembre-se de que os créditos retidos ainda não são cobranças finais. Faça a conciliação depois que os resultados forem finais. Toda conta inclui 300 créditos gratuitos por mês. Eles são usados primeiro e não se acumulam para o mês seguinte. Os créditos pagos não utilizados continuam disponíveis enquanto a conta estiver aberta.

Etapa 7: trate os erros conforme a causa, e não com uma única regra de nova tentativa

• 401: a chave está ausente, foi revogada ou não tem o escopo necessário. Corrija a credencial ou seus escopos.
• 402 key_cap_reached: a nova requisição ultrapassaria o limite vitalício da chave, e nenhum job ou retenção foi criado. O limite conta os créditos já cobrados mais os créditos reservados para identidades únicas aceitas. Como é um limite vitalício, ele não se renova com o tempo, e esperar não resolve. Peça a alguém com acesso que revise a configuração de limite dessa chave. Um limite não pode adicionar créditos ao workspace.
• 422: endereços inválidos ou limites da lista. Corrija a entrada.
• 503 live_verification_unavailable: durante uma pausa operacional, um novo envio Live pode retornar este erro sem reter créditos. Tente novamente mais tarde com a mesma chave de idempotência. Um 503 após um envio incerto não comprova que nenhum job foi criado, então reutilize a chave original.

Todo erro inclui um código, uma mensagem e um ID de requisição. Registre os três para tê-los à mão caso entre em contato com o suporte.

Uma ordem de trabalho sensata

1. Desenvolva a integração usando o sandbox e confirme que cada resultado simulado vai parar onde você espera.
2. Adicione um tratamento explícito para os códigos de erro acima.
3. Crie uma chave Live com os escopos mais restritos de que você precisa e um limite compatível com o seu orçamento.
4. Comece com um job Live pequeno. Compare os resultados e os estados dos créditos com o painel e depois aumente a escala.

Se quiser experimentar este fluxo de trabalho, o sandbox gratuito permite testar os resultados simulados sem usar nenhum crédito. A referência da API traz os detalhes exatos das requisições.