Pular para o conteúdo principal

Aprovação por link

Tools destrutivas (excluir, cancelar, falar com o devedor, negativar, protestar, aceitar acordo, decidir disputa, mexer em webhook) só rodam com a sua confirmação. Um cliente na revisão 2026-07-28 que declara formulários de elicitation pergunta no próprio chat — veja Recursos e prompts. Muitos clientes não declaram (o app Claude no celular, por exemplo). Para eles, a confirmação acontece por link.

Como funciona​

  1. O assistente chama a tool destrutiva. O servidor confere tudo o que conferiria para executá-la: argumentos, workspace, escopo do token e a sua permissão. Uma chamada que seria recusada é recusada na hora, sem link.
  2. Em vez de executar, o servidor grava a operação como pendente e responde ao assistente um link de aprovação. Nada é executado nesse momento.
  3. O assistente mostra o link. Você abre, logado no Dunning (se não estiver, faz login e volta para o link).
  4. A tela mostra o que vai acontecer ("Cancelar cobranças em lote", "Enviar mensagem ao devedor"), o valor em destaque logo abaixo, quando a operação tem um, Pedido por (o identificador do aplicativo conectado, verificado pelo token; o nome que o aplicativo declara sobre si aparece à parte, marcado como não verificado), quando, a organização e o workspace, e os registros afetados como estão agora, com os campos que importam (nome, devedor, situação, valores, vencimento). Em Tudo o que vai rodar estão todos os argumentos, abertos, e todos os itens de um lote. Um dado enviado para o qual o Dunning não tem descrição aparece em Outros dados enviados, com o nome cru ao lado — e, quando está dentro de um argumento descrito (uma chave de custom_data, por exemplo), sai dele e aparece lá pelo caminho completo (custom_data.origem) —, e um aviso diz quantos são — confira antes de continuar. Os argumentos crus ficam em Detalhes técnicos.
  5. Continuar executa a operação na hora e mostra o resultado. Cancelar encerra sem executar nada. Depois da decisão, a tela mostra o que foi aprovado ou recusado, como estava quando você decidiu — uma cobrança excluída ou paga depois não muda o que aparece ali. Se a operação falha, a tela diz por quê no seu idioma, com o código ao lado.
  • Vale por 15 minutos e decide uma vez só: dois cliques em Continuar executam uma vez. Depois do prazo, o link mostra que expirou e nada é executado; peça de novo ao assistente.
  • Só abre para você, logado na organização em que pediu. Para qualquer outra pessoa, inclusive da mesma organização, o link responde como inexistente. Se você participa de mais de uma organização, troque para a certa e abra o link de novo.
  • Ao Continuar, a sua permissão é conferida de novo: se ela foi retirada, ou o seu acesso ao workspace, a execução falha e nada é alterado. Plano e regras de negócio valem como em qualquer chamada.
  • Se o registro mudou entre abrir a tela e clicar em Continuar (a cobrança foi paga, o valor mudou), nada é executado: a tela avisa que os dados mudaram. Peça a operação de novo ao assistente, abra o novo link e revise.
  • O assistente não deve chamar a tool de novo depois de receber o link: cada chamada cria uma aprovação nova.

O que o assistente recebe​

Um resultado comum (não é erro), com um único conteúdo de texto em JSON:

{
"status": "approval_required",
"approval": {
"id": "9a8b7c6d-…",
"url": "https://<app do 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…"
}

A message pede ao assistente que mostre o link, não repita a chamada e, depois que você disser que decidiu, consulte o resultado uma vez com dunning_operation_approvals_get passando o approval.id — sem ficar consultando em laço.

Consultar o resultado pelo assistente​

Duas tools só de leitura contam ao assistente o que aconteceu depois do link:

ToolEntradaDevolve
dunning_operation_approvals_getid (o approval.id)uma aprovação
dunning_operation_approvals_liststatus, created_after, created_before, page, per_page (todos opcionais)as suas aprovações, da mais recente para a mais antiga, com meta de paginação

Cada aprovação traz id, status (pending, approved = em processamento, executed, failed, declined = cancelada, expired — a pendente vencida já sai como expired), action (a tool pedida), title (o título da tela, no idioma do pedido), resource, operation, amount (quando há), requested_at, expires_at, decided_at, executed_at, error ({ code, message } quando falhou) e result (o retorno da operação executada, com segredos mascarados: um segredo novo aparece só uma vez, na tela). Nunca trazem o link nem o token dele.

  • Só as suas aprovações, na organização do token e no workspace da chamada. A de outra pessoa ou de outra organização responde como inexistente (NOT_FOUND), igual a um id que não existe.
  • Qualquer conexão sua chega a elas, sem permissão de papel nem escopo de recurso próprio: basta o nível de leitura. O desfecho (result, error e o valor lido do registro) só vem quando a conexão lê o recurso da operação e você ainda tem permissão para ler esse recurso; senão vem nulo, com result_hidden: true.
  • Nenhuma tool aprova, cancela ou reabre uma aprovação: decidir é só pela tela do link.
  • Na API, as mesmas consultas são GET /v1/operation-approvals e GET /v1/operation-approvals/{id}.

Histórico​

Em Conta → Aprovações ficam as operações que você pediu por um assistente, no workspace atual, com abas por situação (pendentes, executadas, que falharam, canceladas e expiradas), o valor de cada uma, quem pediu e quando. Dá para ordenar pelas colunas, filtrar por recurso e por período do pedido (hoje, últimos 7, 30 ou 90 dias), escolher as colunas e atualizar a lista; a lista vem de 20 em 20, com Anterior e Próxima. No celular cada aprovação vira um cartão. Clicar numa aprovação abre o que foi decidido.

Se o token não tem uma pessoa por trás, não há quem abra o link: a tool destrutiva continua recusada com confirmation_required. Se o servidor não consegue gravar a aprovação naquele momento, a resposta é confirmation_unavailable; tente de novo depois. Veja Erros.