> For AI agents: the complete documentation index is available at https://developers.orbita.nexxo.tec.br/llms.txt, the full documentation bundle is available at https://developers.orbita.nexxo.tec.br/llms-full.txt.

# Prévias e confirmações

## Quando o servidor pede confirmação

O catálogo marca operações destrutivas, administrativas ou irreversíveis como sensíveis. Exemplos incluem gerenciar workspaces, alterar membros e arquivar ou excluir issues. Uma execução sem commit retorna a prévia assinada para essas operações.

Nem toda escrita é automaticamente marcada como sensível. Consulte as capacidades e o contrato da operação. A interface pode pedir consentimento adicional, mas um botão visual não substitui a validação do servidor.

## Fluxo em duas etapas

1. Envie `work_execute` com a operação, o payload e `mode: "preview"`.
2. Apresente ao usuário a organização, o recurso, os argumentos e o impacto.
3. Se houver aprovação, envie o mesmo payload com `mode: "commit"` e o `confirmationToken` retornado.
4. Apresente o resultado real da execução; uma aprovação não é confirmação de que a API já executou a alteração.

Exemplo de prévia, com identificadores ilustrativos:

```json
{
  "operation": "archive_issue",
  "mode": "preview",
  "input": {
    "organizationId": "UUID_DA_ORGANIZACAO",
    "issueId": "UUID_DA_ISSUE"
  }
}
```

O commit usa o token recebido, sem mudar os argumentos:

```json
{
  "operation": "archive_issue",
  "mode": "commit",
  "input": {
    "organizationId": "UUID_DA_ORGANIZACAO",
    "issueId": "UUID_DA_ISSUE"
  },
  "confirmationToken": "TOKEN_RETORNADO_PELA_PREVIA"
}
```

## Vinculação e validade

O token é assinado e vinculado ao usuário, organização, operação e hash canônico do payload. O padrão atual expira em cinco minutos; use o `expiresAt` retornado como referência. Alterar o recurso ou o payload exige gerar outra prévia.

`confirmation_expired`, `confirmation_mismatch` e `invalid_confirmation` indicam que a confirmação não pode ser usada. `confirmation_not_configured` requer ajuste do segredo no servidor. Não remova a etapa de verificação para contornar esses erros.

Veja a [demonstração de interface com AI Elements](https://developers.orbita.nexxo.tec.br/ia/ferramentas-e-aprovacao.md).
