Política Transaccional y Esquemas de Aprobación

La política transaccional de Koywe es la capa que decide qué sucede cuando un usuario o un API key intenta realizar un movimiento sensible de dinero. Funciona como la mayoría de las políticas de wallets empresariales: defines una lista ordenada de reglas, gana la primera que coincide, y esa regla decide si la operación se permite o requiere aprobación de uno o más aprobadores designados.

Esta página explica los bloques de construcción a alto nivel. Está pensada para la persona que decide quién puede hacer qué dentro de la organización — no para quien implementa las librerías de firma. Para los detalles criptográficos de firma, consulta Passkeys y Aprobaciones.

Qué Operaciones Están Sujetas a la Política

La política transaccional aplica a operaciones que mueven fondos, cambian un destino guardado, o modifican la configuración de la política o de seguridad. En la práctica, esto cubre:

• Movimientos de dinero que tienen un destino — payouts, offramps, onramps y transferencias entre balances.
• Cambios de destino — agregar, editar o eliminar una cuenta bancaria o dirección de wallet guardada.
• Gestión de la política — cambios sobre la política misma (agregar reglas, reordenarlas, cambiar aprobadores).

Si una operación queda fuera de ese conjunto, la política no se consulta y la operación corre con normalidad.

Las Tres Piezas

Una configuración funcional tiene tres piezas:

1. La política — un contenedor único que agrupa las reglas de tu organización.
2. Las reglas — una lista ordenada. Cada regla describe una situación (“cualquier payout de USD 10.000 o más”) y un desenlace.
3. Los aprobadores — los usuarios humanos (con passkeys enroladas) a quienes se les pedirá aprobar cuando una regla así lo indique.

Gestionas estas piezas desde el dashboard, la CLI o la API REST.

Cómo se Evalúa una Regla

Cada operación sujeta a política se compara con las reglas antes de ejecutarse. La política recorre las reglas en orden y se detiene en la primera que coincida. El desenlace de esa regla determina lo que pasa a continuación.

Si ninguna regla definida por ti coincide, una regla catch-all implícita en la posición 99999 deniega la operación. No existe un “permitir” implícito — el comportamiento por defecto de una política es rechazar todo aquello para lo que no hayas escrito una regla explícita. Las organizaciones nuevas no parten vacías: vienen con una política inicial cuyas reglas cubren al primer super admin; una vez que creces más allá de eso, tus propias reglas deben dejar al menos un camino abierto para las operaciones que quieras soportar.

Qué Puede Filtrar una Regla

Una regla es un conjunto de filtros combinados con un desenlace. Todos los filtros de una misma regla se combinan con AND: deben coincidir todos para que la regla aplique. Para que un filtro coincida con cualquier cosa, pásale el comodín "*" — así se expresa “cualquier valor” a nivel de la API (el dashboard lo muestra como una opción “Cualquiera” en cada selector).

Los filtros soportados son:

• Tipo de operación — qué se está intentando. Los valores canónicos vienen directo del enum de la política: PAYOUT_FIAT, PAYOUT_CRYPTO, BALANCE_TRANSFER, DESTINATION_EDIT, POLICY_MANAGE (además de operaciones de enrolamiento/seguridad como PASSKEY_ENROLL, API_USER_MFA_ENROLL, API_USER_MFA_REVOKE, EMBEDDED_WALLET_ACCESS_GRANT, USER_INVITE). A nivel de política no existen tokens ONRAMP u OFFRAMP — un offramp se gatilla como PAYOUT_FIAT (el fiat sale hacia el destino) y un onramp se gatilla como PAYOUT_CRYPTO (el cripto sale hacia el destino). Es el punto de partida más común: la mayoría de las políticas se organizan primero por tipo de operación.
• Iniciador — quién está actuando. Los valores típicos son * (cualquier usuario o API key), un rol específico (por ejemplo un super admin), o un usuario o API user en particular. Sirve para reglas como “solo los super admins pueden gestionar la política” o “este API user puede auto-aprobar payouts hasta USD 1.000”.
• Umbral de monto — un monto mínimo, siempre normalizado a USD. La regla aplica a toda operación cuyo equivalente en USD sea mayor o igual al umbral. Un umbral de 0 aplica a cualquier monto (es decir, a todas las operaciones de ese tipo); un umbral de 10000 aplica a toda operación de USD 10.000 o más en equivalente. No hay un campo de máximo — para expresar una banda como “entre USD 1.000 y USD 10.000”, se ordenan las reglas de mayor a menor umbral y se deja que el “primera regla que coincide gana” haga el resto (ver Orden y Precedencia de las Reglas más abajo). Para operaciones no monetarias (ediciones de destino, gestión de política), el monto se ignora — déjalo en 0.
• Origen — desde dónde sale el dinero dentro de tu organización. Tiene dos partes: un merchant específico (uno de los merchants bajo tu organización) y un balance específico dentro de ese merchant (es decir, un balance en una moneda dada, fiat o cripto). Sirve para escribir reglas como “los payouts desde el balance USDC del Merchant A requieren aprobación” mientras dejas al Merchant B sin tocar.
• Destino / contraparte — quién está al otro lado: una cuenta bancaria específica, un contacto específico, una dirección de wallet guardada, o cualquier destino fuera de la whitelist. Así expresas reglas como “los payouts a cuentas en la whitelist se aprueban automáticamente, lo demás requiere revisión”. Todo destino referenciado por una transacción debe estar previamente creado en Koywe antes de poder usarse — no puedes enviar a una dirección ad-hoc. La política filtra por cuál de esos destinos pre-creados se está usando (y por si está en whitelist).

Una regla con todos los filtros en "*" coincide con cualquier operación sujeta a política excepto la gestión de la política. A veces resulta útil como fallback explícito por encima del 99999 implícito.

Los Desenlaces Posibles

Una regla termina en uno de estos desenlaces:

• Permitir — la operación se ejecuta de inmediato. Ningún aprobador es notificado. Es el desenlace adecuado para movimientos rutinarios y de bajo riesgo (payouts pequeños a cuentas en whitelist, rebalanceos internos, etc.).
• Requerir aprobación — la operación queda como aprobación pendiente. No se ejecuta hasta que los aprobadores actúen. Aquí entran los esquemas de aprobación que siguen.
• Denegar — la regla implícita 99999 rechaza la operación por anticipado. No escribes reglas de denegación a mano; expresas “esto nunca debería pasar” no escribiendo una regla de permitir o de aprobación para ese caso y dejando que el catch-all haga su trabajo.

Esquemas de Aprobación

Cuando el desenlace de una regla es requerir aprobación, la regla también define quiénes deben aprobar y cuántos de ellos. Koywe soporta tres esquemas, en orden creciente de estrictez:

Auto-aprobación

Es esencialmente el desenlace permitir anterior — no hay ningún humano en el medio. Lo listamos aquí porque, al diseñar una política, la pregunta “¿esto debería auto-aprobarse?” es la primera que te haces para cada tipo de operación.

Aprobador único

La operación se envía a un grupo designado de aprobadores (típicamente listando a los usuarios de forma explícita). Cualquiera de ellos puede aprobarla. La primera aprobación libera la operación; cualquier aprobador también puede rechazarla, lo que cancela la solicitud.

Es el esquema más común para controles operacionales del día a día — por ejemplo: “los payouts por sobre USD 1.000 requieren la aprobación de un super admin”.

Quórum M-de-N

La operación se envía a un grupo de N aprobadores y requiere M aprobaciones distintas antes de poder ejecutarse (por ejemplo, 2-de-3 o 3-de-5). Cada aprobador aporta un solo voto. Un único rechazo de cualquier miembro del grupo cancela la solicitud.

Úsalo para las operaciones más sensibles: payouts grandes, cambios en la whitelist de destinos, cualquier cosa que sería catastrófica si un único aprobador estuviera comprometido. El objetivo es que el único modo de falla sea la colusión.

Quiénes Pueden Ser Aprobadores

Por defecto, los aprobadores son usuarios humanos con passkey enrolada en Koywe Platform.

Los API users también pueden listarse como aprobadores en una política. Por defecto, la aprobación de un API user es simplemente una llamada API autenticada — no se requiere MFA ni firma criptográfica. Esto es útil cuando quieres que un servicio participe en aprobaciones (por ejemplo, una automatización interna que verifica un payout contra un libro contable externo).

Si quieres garantías más fuertes sobre esas aprobaciones automatizadas, puedes activar la firma MFA para el API user. Eso requiere dos cosas:

1. Que Koywe habilite la funcionalidad de firma para API users en tu cuenta — es un flag manual, no self-service. Contacta a Koywe para activarlo.
2. Que el API user registre una llave pública (PEM) con Koywe. Desde ese momento, toda aprobación de ese API user debe ir firmada con la llave privada correspondiente; una llamada sin firma es rechazada.

Úsalo cuando un aprobador-API user proteja algo material — por ejemplo, cuando actúa como uno de los votos en un quórum M-de-N de un flujo de alto valor. Para automatización de menor importancia, el comportamiento por defecto “sin MFA” está bien. Consulta el Tutorial de Firma para API Users para el flujo de onboarding de la llave.

Un Ejemplo Concreto

Imagina un equipo de tesorería que quiere el siguiente comportamiento:

1. Movimientos de dinero (payouts fiat, payouts cripto incluyendo offramps/onramps, transferencias entre balances) de USD 5.000 o más: dos de tres oficiales de tesorería deben aprobar.
2. Movimientos de dinero bajo USD 5.000: pasan automáticamente.
3. Cualquier edición de destino (cambiar una cuenta bancaria o dirección de wallet guardada): dos de tres oficiales de tesorería deben aprobar.
4. El super admin puede gestionar la política misma.
5. Cualquier otra cosa: queda implícitamente denegada por la regla 99999.

Fíjate cómo las necesidades verbales se reducen a una lista de reglas más corta una vez que dejas de pensar en prosa y empiezas a pensar en filtros. Esta es la lista de reglas que implementa el comportamiento anterior, en orden. Los valores separados por coma en la columna Tipo de operación son condiciones OR — la Regla 1 coincide si la operación es PAYOUT_FIAT o PAYOUT_CRYPTO o BALANCE_TRANSFER y el monto es al menos USD 5.000. Una regla con varios tipos de operación sigue siendo una sola regla, no tres.

Cosas a notar:

• La regla 1 debe ir antes de la regla 2. Los umbrales son mínimos, así que el 0 de la regla 2 capturaría cualquier monto si la pones primero; la regla 1 nunca dispararía.
• La regla 3 tiene que ser una regla propia porque DESTINATION_EDIT no es un movimiento de dinero y no está en la lista explícita de tipos de operación de las reglas 1 y 2 — esas reglas solo cubren PAYOUT_FIAT, PAYOUT_CRYPTO y BALANCE_TRANSFER. Como nota al margen, si la regla 2 hubiera usado el comodín * en lugar de la lista explícita, habría capturado DESTINATION_EDIT bajo USD 5.000 primero y lo habría auto-aprobado — por eso listamos los tipos de operación explícitamente. El comodín * incluye DESTINATION_EDIT pero no POLICY_MANAGE, así que la regla 4 también debe ser explícita.
• La regla 4 es la regla de gestión de política. Suele ser la regla que las orgs nuevas reciben por defecto, asociada al primer super admin. No la borres sin un reemplazo, o nadie podrá editar la política.
• El 99999 implícito queda al final, sin tocar. Todo lo que no coincida con las reglas 1–4 es rechazado. Así es como esta política expresa “cualquier otra cosa: denegado” — simplemente no escribiendo una regla para ello.

Si invirtieras el orden — por ejemplo, poniendo la regla 2 sobre la regla 1 — todo payout, sin importar el monto, caería en el caso de auto-aprobación, porque el umbral 0 de la regla 2 coincide primero. El orden es la política.

Una vez que esta base funciona, puedes superponer reglas adicionales — por ejemplo, una regla de “auto-aprobar” arriba de la regla 1 que apunta a payouts hacia un contacto específico en whitelist, o una regla más estricta que apunta al balance USDC de un merchant en particular.

Flujo de Aprobación de Extremo a Extremo

Cuando una regla requiere aprobación, el ciclo de vida de la operación se ve así:

Hay tres detalles que vale la pena destacar:

• La solicitud original recibe de inmediato un pendingApprovalId. Tu aplicación debe tratarlo como una respuesta normal y esperada — no como un error — y mostrársela al solicitante.
• Los aprobadores no necesitan estar conectados en el momento del disparo. Se les notifica y actúan sobre la cola de aprobaciones (koywe policy approvals list o el dashboard) cuando puedan.
• Un único rechazo termina la solicitud, sin importar cuántas aprobaciones ya se hayan reunido. No hay “gana la mayoría”: quórum significa M votos positivos sin ningún voto negativo.

Orden y Precedencia de las Reglas

Tres guías prácticas:

• Los umbrales más altos primero. Como los umbrales son mínimos y un umbral de 0 aplica a cualquier monto, una regla con umbral 0 colocada encima de una con umbral 10000 se traga toda operación y la de umbral más alto nunca se ejecuta. Ordena las reglas de mayor umbral a 0 dentro de cada tipo de operación.
• Filtros más específicos arriba, fallbacks amplios abajo. La regla “payouts iguales o mayores a USD 5.000 a destinos fuera de la whitelist requieren 2-de-3” debe estar sobre “payouts iguales o mayores a USD 5.000 requieren un aprobador”, que a su vez debe estar sobre cualquier catch-all que escribas. El 99999 implícito siempre cierra al final.
• Reordenar es una operación privilegiada. Usa el dashboard o koywe policy rules reorder para cambiar el orden. Todo reordenamiento queda registrado en el log de auditoría de la política; puedes revisarlo después con koywe policy audit.

Cuando no estés seguro de cómo se va a enrutar una operación, el log de auditoría es el mejor lugar para mirar: registra qué regla coincidió y cuál fue el desenlace, en cada evaluación.

Playbook para Operadores

Una checklist pragmática para quien implemente esto:

• Trata la política por defecto como un punto de partida, no como una configuración permanente. Las orgs nuevas se onboardean con una política por defecto que funciona para un super admin solitario. En cuanto agregas otros operadores, más merchants, o quieres controles por monto, diséñala y reemplázala de forma deliberada — no acumules reglas encima de la default sin entender qué permite ya.
• Enrola passkeys primero. Las reglas de aprobación no sirven si tus aprobadores no pueden firmar. Asegúrate de que cada aprobador previsto tenga su passkey enrolada en Koywe Platform antes de encender cualquier regla que requiera aprobación. Consulta Passkeys y Aprobaciones.
• Decide si los aprobadores-API user deben firmar con MFA. Los API users pueden ser aprobadores sin configuración extra — su aprobación es solo una llamada API autenticada. Si un determinado API user aprobador protege algo material (un voto de quórum sobre un payout grande, por ejemplo), súbelo a firma MFA: pide a Koywe que habilite la funcionalidad de firma para API users en tu cuenta, y haz que ese API user registre una llave pública PEM. Ambos pasos son manuales, así que planifícalo con tiempo.
• Empieza permisivo, ajusta con el tiempo. Comienza con un número pequeño de reglas de alto valor (por ejemplo, solo los payouts sobre un umbral alto requieren aprobación). Mira el log de auditoría durante una semana. Después agrega especificidad. Siempre puedes agregar reglas — pero no puedes deshacer fácilmente operaciones que ya fueron rechazadas.
• Prueba siempre primero en sandbox. Construye la misma política en sandbox, corre operaciones reales contra ella, y confirma que la regla correcta dispara. Los bugs de política son mucho más baratos de encontrar antes de que bloqueen movimientos en producción.
• Ten al menos tres aprobadores para las reglas con quórum. Un 2-de-3 con solo dos passkeys enroladas se vuelve un 2-de-2 en la práctica, lo que significa que un aprobador ausente bloquea todas las operaciones críticas. Para 2-de-3, enrola al menos a cuatro personas si puedes.
• No metas humanos en el camino de auto-aprobación de flujos de alto volumen. Si tu negocio hace cientos de payouts pequeños al día, no requieras aprobación en esos — tus aprobadores empezarán a aprobar mecánicamente, lo que vacía el propósito del control. Reserva las aprobaciones para eventos raros y materiales.
• Revisa el log de auditoría con frecuencia. koywe policy audit (o su equivalente en el dashboard) muestra cada match de regla, cada aprobación y cada rechazo. Trátalo como un feed de SIEM para tesorería.
• Documenta la política en lenguaje natural fuera de Koywe. Los aprobadores deberían saber qué están aprobando y por qué. Un documento interno de una página que explique “tenemos estas reglas porque…” hace que los aprobadores sean reflexivos en lugar de mecánicos.

Errores Comunes

• Reemplazar el default por una política sin camino para tus operaciones. Las orgs nuevas vienen con una política por defecto funcional, pero apenas la reescribes pasas a ser dueña de los desenlaces. Una política sin ninguna regla que coincida con una operación determinada — o donde borraste la única regla de permitir para esa operación — cae al catch-all 99999 y rechaza toda operación de ese tipo. Si los movimientos de producción empiezan a fallar de pronto con un error de política después de editar la política, este es el primer lugar para revisar.
• Borrar la regla de POLICY_MANAGE. La política por defecto incluye una regla que permite al super admin gestionar la política misma. Como el comodín * en tipo de operación no incluye POLICY_MANAGE, ninguna otra regla “amplia” la cubre. Bórrala sin reemplazo y nadie — ni siquiera el super admin — podrá editar la política. Tendrás que contactar a Koywe para recuperarla.
• Esperar que * en tipo de operación cubra la gestión de política. No la cubre. Siempre escribe POLICY_MANAGE como su propia regla explícita.
• Bugs de orden con el umbral 0. Una regla con umbral 0 aplica a cualquier monto. Si la pones encima de una regla con umbral mayor, esa regla más alta nunca correrá. Ordena siempre por umbral descendente dentro de un mismo tipo de operación.
• Bugs de orden en general. Agregar una regla estricta al final de la lista no logra nada — una regla permisiva más arriba ya habrá coincidido. Verifica siempre el orden resultante con koywe policy info.
• Aprobadores faltantes. Una regla de quórum 2-de-3 con un grupo donde solo una persona tiene passkey enrolada deja en deadlock toda operación que la dispare. Agrega los aprobadores antes de activar la regla.
• Tratar los errores de política como bugs. Cuando una solicitud queda en espera de aprobación, tu aplicación recibe un pendingApprovalId, no el recurso final. Código que espera éxito inmediato se verá roto. Modela este estado de forma explícita.
• Editar la política bajo carga. Reordenar o eliminar reglas tiene efecto en la siguiente evaluación. Evita editar la política durante un batch de payouts — termina el batch primero, después cambia la política.

Siguientes Pasos

• Passkeys y Aprobaciones — el lado criptográfico: cómo encajan passkeys, tokens MFA y firmas de aprobación.
• Referencia de la CLI — Política y Aprobaciones — los comandos exactos para crear políticas, agregar reglas, listar aprobaciones pendientes y revisar el log de auditoría.
• Mejores Prácticas de Seguridad — endurecimiento de credenciales y verificación de webhooks, ambos complementan los controles de política.