Descripción general

Usa Upsky Verify para comprobar la identidad de una persona antes de que use tu app. Tiene niveles de verificación, desde una selfie con estimación de edad hasta una identificación oficial comparada con el rostro de la persona.

Cómo funcionaCopiar enlace

1. Tu servidor crea una sesión.
2. Envías a la persona a la url de la sesión, una página en verify.upsky.dev que funciona en cualquier teléfono. También puedes iniciarla desde el panel, que te da un código QR y un enlace para compartir.
3. La persona acepta el aviso, fotografía su identificación si el nivel lo pide y se toma una selfie.
4. Upsky hace las revisiones y envía un webhook con el resultado. También puedes consultar la sesión cuando quieras.

Solo pagas cuando una sesión llega a una decisión. Un enlace que expira o que cancelas no cuesta nada.

Crea una sesiónCopiar enlace

curl https://api.upsky.dev/v1/verify/sessions \
  -H "Authorization: Bearer $UPSKY_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{ "tier": "identity", "reference": "user_123", "return_url": "https://example.com/done" }'

SelfiesCopiar enlace

Por defecto, la selfie tiene que tomarse con la cámara en la página, en ese momento. Pon allow_selfie_upload en true para que la persona también pueda elegir una foto que ya tiene. La sesión devuelve el ajuste como allow_selfie_upload, y el panel tiene el mismo interruptor al iniciar una verificación.

Las sesiones reales siempre toman la selfie con la cámara, durante la prueba de vida, sin importar este ajuste.

Mostrar el resultadoCopiar enlace

Por defecto, el enlace solo agradece a la persona y tú le dices el resultado. Pon show_result en true para mostrarlo en el enlace: justo después de enviar sus fotos, la página espera las revisiones y dice si quedó verificada, si no, o si está en revisión. Nunca dice el motivo, para que la página no sirva para averiguar qué pasa las revisiones. El panel tiene el mismo interruptor al iniciar una verificación.

Si una sesión en revisión se aprueba o rechaza después, el enlace muestra el nuevo resultado la próxima vez que se abra.

Umbrales de aprobaciónCopiar enlace

Qué tan segura debe estar cada revisión lo decide tu equipo, en el panel en Verify → Configuración. Elige un preajuste, o define cada número con Personalizado:

Una puntuación igual o mayor que la marca de aprobación pasa. Desde la marca de revisión hasta la de aprobación, la sesión va a revisión (liveness_inconclusive o face_match_inconclusive), para que una persona la vea. Por debajo de la marca de revisión se rechaza (liveness_failed o face_mismatch). En el nivel age, una selfie sola pasa cuando la persona aparenta al menos minimum_age más el margen de edad: el punto medio del rango estimado, devuelto como checks.age.estimated_age. Para una verificación de 18+, pasa si aparenta 20 en Flexible, 21 en Equilibrado y 23 en Estricto. Un rango completo por debajo de minimum_age se rechaza, y lo que quede en medio va a revisión.

Equilibrado es el predeterminado. Un proyecto puede tener sus propios umbrales, elegidos en el mismo lugar: una sesión con ese project_id los usa, y las demás usan los de tu equipo. Cada sesión conserva los umbrales con los que se creó, devueltos como thresholds, así que cambiar tu configuración nunca cambia cómo se decide una sesión existente. Cuando una prueba de vida saca menos que la marca de aprobación, la página sugiere intentarlo de nuevo, dentro de los tres intentos del enlace.

Identificaciones aceptadasCopiar enlace

En el nivel identity, tú eliges qué identificaciones puede usar una persona y de qué países, en el panel en Verify → Configuración o por sesión:

curl https://api.upsky.dev/v1/verify/sessions \
  -H "Authorization: Bearer $UPSKY_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "options": {
      "documents": {
        "allowed_types": ["passport", "mx_ine"],
        "allowed_countries": ["MEX", "USA"]
      }
    }
  }'

allowed_types es cualquiera de mx_ine, passport, us_drivers_license e id_card. La persona solo ve las que aceptas, y no se le pide elegir cuando hay una sola. allowed_countries recibe códigos ISO 3166-1 alfa-3; déjalo vacío para aceptar cualquier país. La INE solo cuenta como MEX y la licencia de conducir de EE. UU. como USA, así que se rechaza una solicitud que no acepte ni un país que coincida ni otra identificación.

La identificación se lee en cuanto llegan sus fotos. Si está borrosa, no es del tipo que la persona eligió, está vencida o es de un país que no aceptas, la página lo dice y pide fotos nuevas, hasta max_attempts veces (3 de forma predeterminada, de 1 a 5). Después del último intento la persona envía las fotos que tiene, y tus reglas de resultado deciden.

Reglas de resultadoCopiar enlace

Cada problema que una revisión puede encontrar lleva a uno de tres resultados: rechazar la sesión (reject), enviarla a revisión (review) o ignorarlo (ignore). Configúralas en Verify → Configuración, o por sesión en options.rules:

Una prueba de vida fallida, una selfie sin rostro, un rostro que no es el de la identificación y una edad menor a la mínima siempre se rechazan.

Datos esperadosCopiar enlace

Si ya sabes quién debería ser la persona, envíalo como expected y la identificación se compara con eso:

{
  "tier": "identity",
  "expected": {
    "first_name": "Ana",
    "last_name": "García",
    "date_of_birth": "1992-04-15"
  }
}

Los nombres coinciden sin importar acentos, mayúsculas o segundos nombres: "Ana" coincide con "ANA MARIA". El resultado está en checks.data_match, campo por campo: match, mismatch, o not_read cuando la identificación no dio nada que comparar. Una diferencia envía la sesión a revisión, salvo que cambies la regla name_mismatch o date_of_birth_mismatch.

MarcaCopiar enlace

La página que abre un enlace puede llevar tu nombre, tu logo, tu color y un mensaje breve con tus palabras. Configúralos en Verify → Configuración, para tu equipo o para un proyecto; una sesión con ese project_id usa los del proyecto. Los cambios llegan a los enlaces que ya enviaste.

Retención y borrado de datosCopiar enlace

Las fotos se borran 30 días después de que termina una sesión. Cámbialo en Verify → Configuración, o por sesión con options.retention_days (de 1 a 365). Una sesión que espera tu revisión conserva sus fotos al menos 7 días.

Para borrar antes los datos de una persona, redacta la sesión:

curl -X POST https://api.upsky.dev/v1/verify/sessions/$SESSION_ID/redact \
  -H "Authorization: Bearer $UPSKY_API_KEY"

Esto borra de inmediato las fotos, lo que se leyó de la identificación, los datos de expected, y tu reference, metadata y return_url. El estado, los motivos y las revisiones se quedan como tu registro, y redacted_at dice cuándo pasó. No se puede deshacer, solo funciona en una sesión que ya terminó, y envía un webhook verify.session.redacted.

Todo lo anterior sigue el mismo orden: lo que indica la solicitud, luego la configuración del proyecto, luego la de tu equipo. Cada sesión conserva las opciones con las que se creó, devueltas como options.

Estado de la sesiónCopiar enlace

Una sesión decidida tiene checks (prueba de vida, edad, documento, coincidencia de rostro y, cuando enviaste expected, coincidencia de datos, con sus puntajes) y, en el nivel de identidad, verified_outputs: el nombre, la fecha de nacimiento y los datos del documento leídos de la identificación.

Modo de pruebaCopiar enlace

Las sesiones creadas con una llave de prueba recorren todo el flujo con revisiones simuladas y nunca se cobran. En el último paso, la persona elige el resultado que quiere, para que pruebes aprobada, rechazada y requiere revisión sin identificaciones reales.

Modo realCopiar enlace

Las sesiones creadas con una llave real hacen revisiones reales y se cobran cuando llegan a una decisión. Las sesiones reales están abiertas para los niveles age e identity.

La persona tiene tres intentos para la prueba de vida en cada enlace. Después del tercero, el enlace ya no puede continuar: crea una sesión nueva para ella. Un enlace que se queda sin intentos y vence no se cobra.