Cómo leer una comprobación de registro

Use la action externa de la respuesta para decidir cómo continúa el registro. Una dirección entregable puede seguir necesitando confirmación por las señales de visita. Que una señal exija confirmación no demuestra que el visitante sea un bot.

Los ejemplos describen la respuesta combinada de POST /v1/signup-checks. Son ilustraciones ficticias abreviadas de campos seleccionados, no respuestas completas de la API ni mediciones de visitantes reales.

Lea la respuesta en este orden

1. Lea la action externa: allow, allow_with_email_confirmation o reject. Esta recomendación tiene en cuenta ambas partes.
2. Lea email.action y email.status para entender la decisión del correo. Sus reason_codes explican la evidencia y sus límites.
3. Lea signals.status para saber si se evaluaron las señales de visita, el token era inutilizable o el servicio no estaba disponible.
4. Inspeccione signals.findings y signal_codes para ver qué hallazgos exigieron confirmación. Consulte not_evaluated y not_evaluated_classes, cuando aparezcan, para las comparaciones que no se pudieron realizar.

Estos campos responden a preguntas distintas. evaluated describe el estado de evaluación de las señales; no significa que el registro haya sido satisfactorio. Una lista signal_codes vacía indica que ningún hallazgo elevó la recomendación, no que se ejecutaran todas las comparaciones ni que la visita sea segura.

Si usa POST /v1/signup-signals, no hay una parte de correo en la respuesta. Su action es la recomendación de solo señales, como si el correo hubiera devuelto allow. No sustituye a la regla de correo que aplique en otro paso.

Un correo entregable puede seguir exigiendo confirmación

En este ejemplo, el correo permite continuar. El mismo token se presenta en una operación nueva, por lo que una señal pide confirmación:

{
  "action": "allow_with_email_confirmation",
  "signal_codes": ["fp_token_reused"],
  "email": {"status": "deliverable", "action": "allow"},
  "signals": {
    "status": "evaluated",
    "findings": [
      {"code": "fp_token_reused", "class": "token", "default_raises": true}
    ]
  }
}

Leer solo email.action omitiría la confirmación necesaria. La action externa la incluye. El hallazgo registra la reutilización del token; no establece por qué se usó otra vez ni quién envió la petición.

Su aplicación implementa allow_with_email_confirmation: envía un mensaje y comprueba su enlace o código antes de conceder el acceso que depende del control del buzón. La verificación de correo de Emvero no envía mensajes a la dirección comprobada. La diferencia entre verificar y confirmar el correo es relevante aquí: confirmar establece acceso a un buzón, no una identidad humana única.

Las señales pueden cambiar la decisión del correo de allow a allow_with_email_confirmation. No pueden causar reject, suavizar un rechazo del correo ni retirar una confirmación ya exigida. Cuando la acción externa es reject, se basa en la decisión del correo.

Identifique qué evidencia cambió la acción

signals.findings contiene los hallazgos comunicados. El campo default_raises de cada uno indica si pide confirmación según la política por defecto de Emvero. La lista superior signal_codes contiene los códigos de hallazgos con default_raises: true, en el orden recibido y sin duplicados.

Por tanto, puede haber un hallazgo sin que cambie la acción. Este ejemplo de VPN mantiene la decisión del correo:

{
  "action": "allow",
  "signal_codes": [],
  "email": {"status": "deliverable", "action": "allow"},
  "signals": {
    "status": "evaluated",
    "findings": [
      {"code": "fp_network_vpn", "class": "identity", "default_raises": false}
    ]
  }
}

fp_network_vpn comunica una observación de red. Con default_raises: false, el hallazgo por sí solo no exige confirmación. Los hallazgos de VPN, Tor, proxy y alojamiento son informativos por defecto; una etiqueta de red no demuestra abuso. Lea el indicador recibido en vez de deducirlo del nombre del código. La referencia de códigos de señales define el vocabulario.

Los reason_codes del correo permanecen en email. Explican la evidencia del correo y no se convierten en códigos de señales. El artículo sobre el resultado del correo detalla esa parte. Mantenga separadas ambas listas al mostrar un resultado o investigar un registro.

signal_codes puede contener códigos aunque el correo ya exija confirmación o rechazo. La lista registra las señales que elevaron su parte de la recomendación; no indica que fueran la única causa de la acción final.

Los hallazgos del navegador y las notas cumplen funciones distintas

signals.probe indica si se leyó la prueba del navegador y qué comprobaciones pudieron ejecutarse. fp_probe_forged y fp_probe_automation tienen default_raises: true y pueden exigir confirmar el correo. fp_probe_tampering es informativo porque las extensiones y el código de la página también pueden alterar propiedades nativas.

La matriz independiente signals.notes contiene rtt_extra_leg, webtransport, ua_brand, bot_claim y bot_operator. notes_version identifica el vocabulario; la versión actual es la 2. Las notas no entran en signal_codes ni cambian la acción por defecto. Una nota no disponible o una prueba ausente limitan la evidencia; no equivalen a un token fallido ni a una caída del servicio de señales. Cada nota incluye value, rules_version y group. Su aplicación puede considerar las notas junto con su historial. Las observaciones del mismo grupo pueden describir una sola causa y no deben tratarse como pruebas independientes.

bot_claim indica un rastreador declarado cuya red coincide con la del operador (crawler_verified), una declaración fuera de esa red (crawler_unverified), un rastreador sin un método admitido para comprobar su operador (crawler_unchecked), una herramienta declarada (tool) o ninguna de esas declaraciones (none). bot_operator nombra al operador del rastreador declarado. unavailable significa que no se pudo evaluar la nota; none no demuestra que el visitante sea humano. Incluso crawler_unverified es informativo. Actualmente no se ofrecen contadores de visitas repetidas, detección de granjas de automatización mediante clústeres ni una señal que eleve la acción por declarar una herramienta.

Una prueba de navegador ausente puede producir fp_probe_not_evaluated mientras el token sigue siendo válido y signals.status es evaluated. Esa operación sigue costando cinco créditos de señales. Un valor de nota unavailable o unknown limita lo que establece la nota; no significa que todo el servicio de señales estuviera caído. La referencia de códigos de señales explica los nuevos hallazgos y las notas.

Compare los resultados combinados

Estos diez casos ficticios usan el mismo contrato. El caso habitual no tiene hallazgos. El caso de VPN incluye un hallazgo informativo sin código que eleve la acción.

Los dos resultados allow con señales evaluadas y no disponibles no establecen lo mismo. En el caso habitual se evaluaron las señales y ninguna elevó la acción. En el caso no disponible no se completó la evaluación; solo el correo determinó la recomendación.

Distinga un token inutilizable de las señales no disponibles

Un token ausente da signals.status: token_unusable, con fp_token_absent en signal_codes. Un token caducado también da token_unusable, con fp_token_expired. Estos hallazgos exigen confirmación si el correo permitiría continuar. No obligan a considerar abusivo al visitante: un script bloqueado o un formulario abierto mucho tiempo pueden dejar sin token utilizable a una persona que se registra normalmente.

Si el servicio no puede evaluar la petición, el endpoint combinado puede devolver HTTP 200 con signals.status: unavailable. En ese resultado, el objeto signals contiene solo el estado:

{
  "action": "allow",
  "signal_codes": [],
  "email": {"status": "deliverable", "action": "allow"},
  "signals": {"status": "unavailable"}
}

El servicio no ha establecido que la visita sea segura ni que no haya VPN. La acción externa sigue solo el correo. Su aplicación decide qué acceso permite sin evidencia de señales. Si el correo exigía confirmación o rechazo, esa condición se mantendría.

Incluso un resultado evaluated puede tener lagunas. La falta de IP, datos del navegador o una medición puede impedir comparaciones concretas. Cuando se devuelven, not_evaluated y not_evaluated_classes describen esas lagunas. No son resultados adicionales del correo, y la ausencia de un hallazgo no prueba que su comparación fuera favorable.

Un error HTTP que impida recibir el resultado es otro desenlace de integración. No lo convierta en un resultado evaluated inventado. El contrato de respuesta de la API distingue los resultados de señales de los errores de petición, conexión y contabilidad.

Correo pendiente no significa señales pendientes

Cuando email.status es pending, las señales ya son definitivas. La action externa sigue siendo allow_with_email_confirmation mientras termina el correo. Conserve el identificador y consulte GET /v1/signup-checks/{id} tras email.retry_after_ms.

La consulta devuelve el resultado actual del correo con las señales guardadas y recalcula la acción. No vuelve a evaluar la visita. Si después el correo devuelve allow, una señal guardada que exija confirmación la sigue exigiendo. Si devuelve reject, la acción combinada pasa a reject.

pending indica trabajo de correo sin terminar. Un resultado final unknown indica que la evidencia no resolvió la dirección. Ninguno establece que sea inválida. Siga la acción recibida y consulte la evidencia del correo para entender el límite.

Repita la operación sin generar una reutilización del token

Si se pierde una respuesta, reintente la misma operación lógica con el Idempotency-Key guardado y el mismo contenido. Dentro del plazo de 30 minutos, la API devuelve la comprobación guardada. La repetición no reevalúa las señales ni genera un segundo cobro. En una comprobación combinada, ese registro puede incluir un resultado de correo más reciente; repetir no garantiza que todos los bytes de la respuesta queden congelados mientras termina el correo.

Una operación nueva con el mismo token es una segunda presentación. Puede añadir fp_token_reused y exigir confirmación, como en el primer ejemplo. Generar una clave nueva tras perder una respuesta cambia el significado de la petición. Use la clave original para reintentos de transporte y un token nuevo para un intento de registro nuevo.

Reutilizar una clave con otro contenido da 409 idempotency_conflict. Si la primera petición sigue en curso, 409 request_in_progress indica que espere según Retry-After. La documentación de idempotencia explica el límite de la operación. Consultar la comprobación guardada con GET también es distinto de enviar otra con el mismo token.

Siga la guía para evitar registros de bots para conectar estas decisiones con su proceso. La página de Signup Protection explica el producto y cómo conectar el formulario y el servidor.