Aprobación por enlace
Las tools destructivas (eliminar, cancelar, hablar con el deudor, reportar a un buró, protestar, aceptar un acuerdo, decidir una disputa, cambiar un webhook) solo se ejecutan con tu confirmación. Un cliente en la revisión 2026-07-28 que declara elicitation de formulario pregunta en el propio chat — ve Recursos y prompts. Muchos clientes no lo declaran (la app Claude en el celular, por ejemplo). Para ellos, la confirmación ocurre por enlace.
Cómo funciona
- El asistente llama a la tool destructiva. El servidor verifica todo lo que verificaría para ejecutarla: argumentos, workspace, scopes del token y tu permiso. Una llamada que sería rechazada se rechaza en el momento, sin enlace.
- En lugar de ejecutarla, el servidor guarda la operación como pendiente y responde al asistente con un enlace de aprobación. No se ejecuta nada en ese momento.
- El asistente muestra el enlace. Lo abres con sesión iniciada en Dunning (si no la tienes, inicias sesión y vuelves al enlace).
- La pantalla muestra lo que va a pasar ("Cancelar cobros en lote", "Enviar un mensaje al deudor"), el monto destacado justo debajo cuando la operación tiene uno, Pedido por (el identificador de la aplicación conectada, verificado por el token; el nombre que la aplicación declara de sí misma aparece aparte, marcado como no verificado), cuándo, la organización y el workspace, y los registros afectados tal como están ahora, con los campos que importan (nombre, deudor, estado, montos, vencimiento). En Todo lo que se ejecutará están todos los argumentos, abiertos, y todos los ítems de un lote. Un dato enviado para el que Dunning no tiene descripción aparece en Otros datos enviados, con su nombre en bruto al lado — y, cuando está dentro de un argumento descrito (una clave de
custom_data, por ejemplo), sale de él y aparece allí por su ruta completa (custom_data.origem) — y un aviso dice cuántos son — revísalos antes de continuar. Los argumentos en bruto quedan en Detalles técnicos. - Continuar ejecuta la operación en el momento y muestra el resultado. Cancelar la cierra sin ejecutar nada. Después de la decisión, la pantalla muestra lo que se aprobó o rechazó, tal como estaba cuando decidiste — un cobro eliminado o pagado después no cambia lo que aparece ahí. Si la operación falla, la pantalla dice por qué en tu idioma, con el código al lado.
Reglas del enlace
- Vale 15 minutos y decide una sola vez: dos clics en Continuar la ejecutan una vez. Pasado el plazo, el enlace muestra que expiró y no se ejecuta nada; pídelo de nuevo al asistente.
- Solo se abre para ti, con sesión iniciada en la organización donde lo pediste. Para cualquier otra persona, incluso de la misma organización, el enlace responde como inexistente. Si participas en más de una organización, cambia a la correcta y abre el enlace de nuevo.
- Al Continuar, tu permiso se verifica de nuevo: si fue retirado, o tu acceso al workspace, la ejecución falla y no se cambia nada. El plan y las reglas de negocio valen como en cualquier llamada.
- Si el registro cambió entre abrir la pantalla y hacer clic en Continuar (el cobro se pagó, el monto cambió), no se ejecuta nada: la pantalla avisa que los datos cambiaron. Pide la operación de nuevo al asistente, abre el nuevo enlace y revísala.
- El asistente no debe llamar a la tool de nuevo después de recibir el enlace: cada llamada crea una aprobación nueva.
Lo que recibe el asistente
Un resultado común (no es error), con un único contenido de texto en JSON:
{
"status": "approval_required",
"approval": {
"id": "9a8b7c6d-…",
"url": "https://<app de Dunning>/approvals/<token>",
"expires_at": "2026-10-31T12:15:00.000Z"
},
"message": "This operation was NOT executed. It needs the user's approval: show this URL to the user…"
}
El message le pide al asistente que muestre el enlace, que no repita la llamada y, después de que digas que decidiste, que consulte el resultado una vez con dunning_operation_approvals_get y el approval.id — sin consultarlo en bucle.
Consultar el resultado desde el asistente
Dos tools de solo lectura le cuentan al asistente qué pasó después del enlace:
| Tool | Entrada | Devuelve |
|---|---|---|
dunning_operation_approvals_get | id (el approval.id) | una aprobación |
dunning_operation_approvals_list | status, created_after, created_before, page, per_page (todos opcionales) | tus aprobaciones, de la más reciente a la más antigua, con meta de paginación |
Cada aprobación trae id, status (pending, approved = en proceso, executed, failed, declined = cancelada, expired — la pendiente vencida ya sale como expired), action (la tool pedida), title (el título de la pantalla, en el idioma del pedido), resource, operation, amount (cuando hay), requested_at, expires_at, decided_at, executed_at, error ({ code, message } cuando falló) y result (lo que devolvió la operación ejecutada, con los secretos enmascarados: un secreto nuevo aparece una sola vez, en la pantalla). Nunca traen el enlace ni su token.
- Solo tus aprobaciones, en la organización del token y el workspace de la llamada. La de otra persona o de otra organización responde como inexistente (
NOT_FOUND), igual que un id que no existe. - Cualquier conexión tuya llega a ellas, sin permiso de rol ni alcance de recurso propio: basta el nivel de lectura. El resultado (
result,errory el monto leído del registro) solo viene cuando la conexión lee el recurso de la operación y todavía tienes permiso para leerlo; si no, viene nulo, conresult_hidden: true. - Ninguna tool aprueba, cancela ni reabre una aprobación: decidir es solo en la pantalla del enlace.
- En la API, las mismas consultas son
GET /v1/operation-approvalsyGET /v1/operation-approvals/{id}.
Historial
En Cuenta → Aprobaciones quedan las operaciones que pediste a un asistente, en el workspace actual, con pestañas por estado (pendientes, ejecutadas, fallidas, canceladas y expiradas), el monto de cada una, quién la pidió y cuándo. Puedes ordenar por las columnas, filtrar por recurso y por período del pedido (hoy, últimos 7, 30 o 90 días), elegir las columnas y actualizar la lista; la lista viene de 20 en 20, con Anterior y Siguiente. En el celular cada aprobación es una tarjeta. Al hacer clic en una aprobación se abre lo que se decidió.
Cuando no hay enlace
Si el token no tiene una persona detrás, no hay quién abra el enlace: la tool destructiva sigue rechazada con confirmation_required. Si el servidor no puede guardar la aprobación en ese momento, la respuesta es confirmation_unavailable; inténtalo de nuevo más tarde. Ve Errores.