# Como a integração funciona

Quatro contratos mantêm autenticação, dados do negócio e documento editável em seus lugares certos.

[Abrir a versão HTML](https://rhizzalab.com/docs/concepts/how-it-works)

## O host mantém o contexto

RhizzaDocs é um widget, não uma aplicação paralela. Seu produto mantém login, autorização de negócio, rotas, breadcrumbs e a decisão de quando abrir ou fechar o editor.

* O backend do host afirma `userId` e, opcionalmente, `workspaceId`.

* O host escolhe o `reportType` permitido para aquele fluxo.

* O host carrega os dados e decide o significado de fechar, salvar ou navegar.

## A sessão usa acesso temporário

A troca server-to-server cria um JWT com usuário, tenant e acesso a relatórios específicos. O TTL padrão é 10 minutos e o teto do contrato é 15 minutos. Não existe refresh token: quando necessário, o host emite outro acesso.

`workspaceId` identifica o contexto de uso para auditoria e medição; ele não amplia permissões. Os escopos efetivos continuam sendo a interseção entre a credencial, a política do relatório e o grant do usuário.

## Dados e documento não são a mesma coisa

| Entrada       | Responsável     | Papel                                                         |
| ------------- | --------------- | ------------------------------------------------------------- |
| `data`        | Host            | Valores atuais, validados contra o schema do relatório        |
| `reportType`  | Host + cadastro | Seleciona definição, blocos, tema e modelos publicados        |
| `documentKey` | Host            | Identifica o documento de negócio para restauração e autosave |
| Documento     | Editor          | Árvore canônica com conteúdo e configuração editáveis         |

Sem `documentKey`, cada abertura parte deterministicamente do modelo aplicável. Com `documentKey`, alterações são salvas com concorrência otimista; o host recebe callbacks para resolver conflitos sem descartar trabalho silenciosamente.

## Uma árvore, três saídas

* **01: Editor** — O usuário reorganiza blocos e edita conteúdo sobre a árvore canônica.

* **02: Prévia** — A árvore atual vira uma saída paginada para revisão.

* **03: PDF** — O servidor renderiza o snapshot confirmado com o mesmo motor.

> **Nota: Sem renderização parcial**
>
> Se a versão do SDK não suporta uma primitiva exigida, a abertura falha com `PRIMITIVES_UNSUPPORTED` em vez de produzir um documento incompleto.