Exportar / Importar organização (molde cifrado)

Leve a configuração inteira de uma organização entre ambientes (ou clone uma organização nova já montada) num único arquivo cifrado por senha (ADR-029). O molde carrega os segredos e chaves de API junto, de forma segura.

O que entra — e o que NÃO entra

O bundle é um molde de configuração, não um backup de dados.

Entra (definições)	NÃO entra (dados operacionais)
Papéis/permissões (RBAC), cargos	Colaboradores, clientes/PDVs, produtos, endereços
Integrações (data sources, conectores, credenciais, agendamentos)	Pedidos + linhas + histórico
Pipelines (grafo de nós)	Execuções de pipeline / sync / outbox / entregas de webhook
Webhooks de entrada e de saída	Log de uso de API keys
Definição das API keys	—

Exemplo

A listagem de clientes sincronizada a partir de um data source não é exportada — só a definição do data source que a produz. O molde não referencia nenhum dado operacional, então o import não precisa reconstruir integridade referencial.

Como o arquivo é protegido

• Arquivo inteiro cifrado, senha obrigatória. Fora dos campos criptográficos mínimos, nada é legível sem a senha — nem nomes de conector ou URLs. Não existe modo "molde aberto".
• A senha deriva uma chave de 32 bytes via scrypt (nativo, sem dependência), que cifra o molde em AES-256-GCM. O envelope é versionado (enc: "v1") para permitir rotação de algoritmo.
• GCM autentica o conteúdo: senha incorreta ou arquivo adulterado falham na mesma verificação (indistinguíveis por construção — o correto) e retornam 400.

O arquivo é um bearer secret

Quem tiver o arquivo + a senha tem as credenciais de integração e webhook. Trate o arquivo como confidencial e guarde a senha com segurança — não há como recuperá-la.

Segredos e chaves de API

• Credenciais de integração e segredos de webhook viajam no molde e são recifrados no destino com a chave do servidor de destino (INTEGRATION_SECRET_KEY) — nunca ficam em texto plano em repouso.
• API keys da organização (ADR-028): o token não é exportável — guardamos só o hashedKey (SHA-256 de mão única). O molde leva a definição (nome, prefixo, validade); no import o destino regenera um token novo, revelado uma única vez, que você redistribui aos sistemas externos. É o comportamento seguro: não se reverte um hash.

Fluxo

Na tela Exportar / Importar (RBAC org:export / org:import; owner da org — platform/master admin têm acesso):

Exportar

1. Marque as seções desejadas (padrão: todas).
2. Defina a senha do arquivo (mínimo 12 caracteres).
3. Exportar e baixar → salva organizacao-AAAA-MM-DD.sfaorg.json.

Importar

1. Escolha o arquivo e informe a senha.
2. Pré-visualizar (dryRun) roda a importação numa transação e faz rollback, mostrando o que seria criado/atualizado sem gravar nada.
3. Importar aplica de verdade. O upsert é idempotente por chave natural (papéis por nome, cargos por externalCode/nome, integrações/webhooks/pipelines por key), então reimportar é seguro. Tudo roda numa transação única (tudo-ou-nada).
4. Se o molde trouxe API keys, os tokens regenerados aparecem uma única vez — copie e redistribua.

Avisos não bloqueiam

Permissão ausente no catálogo do destino, ou um connectorKey que não existe, viram avisos por item (a assinatura é importada sem o filtro, o papel sem a permissão) — o restante do molde é aplicado normalmente.

API (Scalar)

Sob /api/organizations (RBAC org:export/org:import):

• POST /organizations/export — body { password, sections? } → envelope cifrado.
• POST /organizations/import — body { password, bundle, dryRun? } → resultado por seção + totais
  • tokens regenerados.

Esquemas na Referência da API (tag Organização — Bundle).