Integración de una API KYC: lo que un resultado Approved deja a tu aplicación

El problema: llega Approved y alguien quiere publicar

Imagina un pequeño marketplace B2B. Un nuevo vendedor termina el onboarding de identidad alojado, el proveedor informa Approved y el manejador tentador activa un indicador de publicación en el mismo paso. Ese atajo mezcla tres preguntas: si pasó la verificación, si el resultado corresponde a la cuenta correcta y si tu política permite la acción ahora. La decisión que enfrentas como integrador es dónde vive cada respuesta. La guía lo dice claramente: vincula el evento verificado al tenant, al usuario y a la sesión, y luego aplica la política del cliente. Approved por sí solo no es permiso para publicar. El ejemplo verificado te permite probar esa separación localmente antes de decidir si una integración en sandbox encaja con tu tarea.

Lo que implementa el ejemplo verificado

El ejemplo descargable persiste sesiones de fixture en SQLite. Cada fila guarda tenant, subject, status, deadline, granted, grants, policy_version y allow_action. La función event solo acepta mode synthetic_fixture y source fixture_callback; cualquier otra cosa lanza PRODUCTION_SIGNATURE_VERIFIER_NOT_IMPLEMENTED, porque no existe un verificador de firmas de producción. Los identificadores de evento deben empezar por fixture-. Solo se concede un permiso cuando el estado es Approved, el llamador pasa policy exactamente como True y allow_action está activo. Cada evento procesado se registra por sesión e ID de evento, así que una repetición devuelve el estado actual sin cambiarlo. La lectura siempre informa live_permission_changed false. La función recover marca localmente como expired las sesiones pending, review o unknown vencidas e informa provider_polled false: nunca contacta a un proveedor.

Un escenario hipotético con salidas esperadas

Hipotético: fixture-tenant incorpora a fixture-user en fixture-session con un plazo de 60 segundos. La creación devuelve state simulated, link_executable false y next send_real_provider_link_only_after_authorization; hosted_link apunta a un dominio de ejemplo inválido y no recoge ningún documento. Un evento Approved con policy True devuelve status approved, deadline 60, permission_granted true, grant_count 1, policy_version 1, allow_action true. Enviar de nuevo el mismo ID de evento devuelve el registro idéntico: grant_count sigue en 1. Un Declined posterior, como corrección, devuelve status declined, permission_granted false, grant_count 1; el contador registra historia y el indicador refleja el acceso actual. En otra sesión que quedó pending después del plazo, recover devuelve status expired, permission_granted false, grant_count 0, next review_or_authorized_provider_refresh y provider_polled false.

Manejo de fallos a cargo del llamador

Vinculación incorrecta: un evento con un tenant o subject que no coincide con la fila guardada, o una sesión desconocida, lanza BINDING_MISMATCH; leer una sesión desconocida lanza SESSION_NOT_FOUND. Política ausente: un Approved sin policy True registra el estado approved pero no concede nada, lo que mantiene separadas verificación y permiso. Eventos tardíos: pasado el plazo, el evento marca la sesión como expired en lugar de conceder. Los estados no reconocidos pasan a unknown. Los cambios de política usan revise_policy con una versión esperada; una discrepancia lanza STALE_POLICY_VERSION y una revisión correcta borra granted. Las nuevas concesiones explícitas pasan por decide, que exige evidencia approved vigente, plazo no vencido, allow_action y approve True; si no, lanza CURRENT_EVIDENCE_AND_EXPLICIT_APPROVAL_REQUIRED. En el diseño propuesto para tu aplicación, envía cada caso a una cola revisada, no a un aprobado o rechazo silencioso.

Diseño propuesto frente a comportamiento implementado

Implementado: la lógica de fixture descrita, su persistencia en SQLite y sus pruebas unitarias sobre transiciones simuladas, vinculaciones, duplicados, reinicio y plazos. Propuesto para tu aplicación: un verificador real de callbacks firmados mediante un adaptador autorizado, un almacén de políticas propio de tu equipo y un registro de auditoría que vincule cada concesión con un ID de evento y una versión de política. La descripción de producción de GridZen indica que se verifican notificaciones firmadas y se vuelven a consultar las decisiones autoritativas, mientras que los permisos del cliente requieren su propia integración y reglas; la acción en vivo de extremo a extremo sigue sin verificarse y una persona nueva completando todo el recorrido alojado sigue sin probarse. El permiso de fixture sintético no es permiso de negocio real y las pruebas superadas no demuestran éxito en producción.

Lista de aceptación antes de una solicitud de sandbox

Confirma que puedes demostrar: un tenant o subject distinto produce BINDING_MISMATCH; Approved sin policy True deja permission_granted false; un evento duplicado no cambia grant_count; una corrección a Declined pone permission_granted false; un evento tardío o recover produce expired con provider_polled false; una versión de política obsoleta se rechaza; toda salida muestra live_permission_changed false. Si todo se cumple y tu equipo sabe quién es responsable de la política y del verificador de firmas, una solicitud opcional de sandbox guardada es un siguiente paso razonable. Si no, sigue iterando localmente; el fixture es el lugar más barato para encontrar huecos.

Ejecutar el ejemplo sintético comprobado

Descargue y extraiga https://gridzen.ai/downloads/verification-delivery.zip, entre en verification_delivery y ejecute con Python 3.10+. El ejemplo local no hace llamadas de red. Use una base nueva para otra prueba de identidad.

python3 delivery.py identity --db /tmp/gridzen-article-fixture.sqlite

Fuentes y alcance

https://gridzen.ai/guides/approved-seller-permissions/ https://gridzen.ai/guides/current-capabilities/ Basado en las fuentes comprobadas y el ejemplo local; las reglas propuestas son recomendaciones de diseño, no comportamiento de producción demostrado. Redacción asistida por IA con revisión independiente.