Flujo de trabajo con la API de validación de correo electrónico: del sandbox a producción con FairValid

Flujo de trabajo con la API de validación de correo electrónico: de la prueba en el sandbox a los resultados en producción

Pregunta: Eres un desarrollador que está añadiendo verificación de correo electrónico a tu propio sistema. ¿Qué pasos te llevan de una primera llamada de prueba a resultados fiables en producción?

Respuesta breve: Empieza con una clave Test y el sandbox gratuito. Después cambia a una clave Live que tenga solo los permisos que necesitas. Envía cada solicitud con una clave de idempotencia. Consulta el estado del trabajo y recorre los resultados por páginas. Gestiona cada resultado y cada código de error por separado. Los pasos siguientes se basan en la referencia de la API para clientes de FairValid.

Paso 1: desarrolla primero contra el sandbox

Crea una clave Test en la página de claves de API y guárdala en tu servidor. La referencia utiliza dos variables de entorno, FAIRVALID_API_KEY y FAIRVALID_BASE_URL. Las claves Test no realizan ninguna llamada al proveedor ni consumen créditos.

Las claves Test solo aceptan un pequeño conjunto de direcciones reservadas en el dominio example.com. Esas direcciones simulan resultados válido, inválido, catch-all, desconocido, pendiente y no disponible. Encontrarás las direcciones exactas en la sección «Sandbox gratuito» de la referencia de la API. Los trabajos de prueba devuelven estados fijos y repetibles: completado, pendiente, fallido o cancelado. Los trabajos de prueba masivos admiten consulta de estado, resultados y cancelación.

El sandbox te muestra esos resultados concretos. No cubre todos los caminos que puede seguir tu integración, así que prevé una gestión específica para los códigos de error descritos en el paso 7.

Los trabajos de prueba masivos están limitados a 20 trabajos nuevos por espacio de trabajo por hora, o 100 cada 30 días. Superar cualquiera de los dos límites devuelve HTTP 429. Un reintento idéntico sigue devolviendo el trabajo original.

Paso 2: pasa a una clave Live con los permisos que necesitas

Para producción, crea una clave Live con el permiso submit. Usa POST /api/v1/jobs para lotes o POST /api/v1/verifications para una sola dirección. Añade el permiso read si la clave también necesita consultar el estado y los resultados de los trabajos. Las claves Live también pueden tener el permiso balance. Por otro lado, GET /api/v1/balance consulta los créditos disponibles y retenidos del espacio de trabajo. El secreto completo solo se muestra una vez, así que guárdalo de forma segura al crear la clave.

Los trabajos Live usan la cola de verificación y el saldo de créditos de tu espacio de trabajo. Los permisos de la clave, los topes de la clave, el acceso al espacio de trabajo y los límites de procesamiento siguen aplicándose.

Paso 3: envía un trabajo con una clave de idempotencia

Un trabajo acepta de 1 a 5.000 direcciones en JSON, hasta 2 MiB. Envía una cabecera Idempotency-Key con cada envío de trabajo y con cada envío Live de una sola dirección. La clave debe tener entre 8 y 128 caracteres y puede contener letras, dígitos, puntos, dos puntos, guiones bajos o guiones.

• Un trabajo nuevo devuelve HTTP 202 con un job_id en formato UUID.
• Un reintento coincidente devuelve HTTP 200 con el mismo trabajo.
• Reutilizar una clave de idempotencia con un cuerpo modificado devuelve HTTP 409 idempotency_conflict.

Si no sabes con certeza si una solicitud se procesó, reintenta con la misma clave de API, la misma clave de idempotencia y el mismo cuerpo normalizado. La repetición está vinculada a la clave de API, así que sustituir esa credencial y volver a enviar puede crear una segunda ejecución. Usa una clave de idempotencia nueva solo cuando realmente quieras una ejecución nueva, que puede cobrarse.

Paso 4: consulta el trabajo y recorre los resultados por páginas

Consulta el trabajo con GET /api/v1/jobs/{id}. Su estado puede ser en cola, en ejecución, en pausa, cancelándose, cancelado o completado. Consulta los resultados con GET /api/v1/jobs/{id}/results. Cada página devuelve hasta 50 resultados más un next_cursor firmado. Pasa ese valor como parámetro de consulta cursor. Conserva tu filtro y tu búsqueda originales.

Los filtros son all, valid, invalid, catch_all, unknown, still_checking y not_checked. Para detener un trabajo, POST /api/v1/jobs/{id}/cancel solicita la cancelación, pero el trabajo que ya esté en curso puede llegar a terminar.

La referencia también describe un evento de finalización firmado y enlaza a la gestión de webhooks.

Paso 5: trata cada resultado como un estado propio

La guía de resultados explica qué significa cada resultado:

• Válido: una comprobación positiva utilizable. Nunca garantiza la entrega en la bandeja de entrada.
• Inválido: la dirección no superó la comprobación.
• Catch-all: el dominio puede aceptar muchas direcciones, por lo que una conclusión a nivel de buzón puede ser menos segura. Lee el detalle antes de usarlo.
• Desconocido: la comprobación no pudo devolver una respuesta fiable.
• Aún en comprobación: todavía no hay una respuesta definitiva.

La guía describe los fallos técnicos y los elementos no procesados por separado del estado Desconocido, y la API ofrece unknown, still_checking y not_checked como filtros independientes. Mantén estos estados en campos o estados separados en tus propios datos en lugar de agruparlos como Desconocido.

Paso 6: entiende las retenciones de créditos antes de conciliar

La referencia de la API indica que los créditos del espacio de trabajo se reservan a medida que las comprobaciones se admiten para su procesamiento. Después, los resultados siguen las mismas reglas de cobro y devolución que el panel. Los precios de FairValid indican que una retención de créditos reserva margen para una comprobación en curso y que el resultado final determina el cobro:

• Válido o inválido: 1 crédito por cada resultado completado.
• Desconocido o catch-all: al final no se descuenta ningún crédito de verificación. Los créditos retenidos se liberan o se devuelven.
• Aún en comprobación: todavía no hay cobro definitivo. Una retención no es un cobro completado.
• Fallos técnicos y trabajo no procesado: al final no se descuenta ningún crédito de verificación. Las reservas se liberan o se devuelven.

Si consultas tu saldo a mitad de un trabajo, recuerda que los créditos retenidos todavía no son cobros definitivos. Concilia cuando los resultados sean definitivos. Cada cuenta incluye 300 créditos gratuitos al mes. Se usan primero y no se acumulan para el mes siguiente. Los créditos de pago no utilizados siguen disponibles mientras la cuenta permanezca abierta.

Paso 7: gestiona los errores según su causa, no con una única regla de reintento

• 401: falta la clave, se ha revocado o no tiene el permiso necesario. Corrige la credencial o sus permisos.
• 402 key_cap_reached: la nueva solicitud superaría el tope total de la clave, y no se creó ningún trabajo ni retención. El tope contabiliza los créditos ya cobrados más los créditos reservados para identidades únicas aceptadas. Como es un límite para toda la vida de la clave, no se renueva con el tiempo y esperar no lo resolverá. Pide a alguien con acceso que revise la configuración del tope de esa clave. Un tope no puede añadir créditos al espacio de trabajo.
• 422: direcciones no válidas o límites de la lista. Corrige los datos de entrada.
• 503 live_verification_unavailable: durante una pausa operativa, un nuevo envío Live puede devolver este error sin retener créditos. Reintenta más tarde con la misma clave de idempotencia. Un 503 tras un envío incierto no demuestra que no se haya creado ningún trabajo, así que reutiliza la clave original.

Cada error incluye un código, un mensaje y un ID de solicitud. Registra los tres para tenerlos a mano si contactas con soporte.

Un orden de trabajo razonable

1. Desarrolla la integración contra el sandbox y confirma que cada resultado simulado termina donde esperas.
2. Añade una gestión explícita para los códigos de error anteriores.
3. Crea una clave Live con los permisos más restringidos que necesites y un tope que se ajuste a tu presupuesto.
4. Empieza con un trabajo Live pequeño. Compara sus resultados y estados de créditos con el panel y, después, amplía la escala.

Si quieres probar este flujo de trabajo, el sandbox gratuito te permite probar los resultados simulados sin consumir créditos. La referencia de la API incluye los detalles exactos de las solicitudes.