Integrações (API e embed)

Como embutir o Desconflite na sua solução: API em api.desconflite.com, keys e origins em Configurações → Integrações.

Objetivo

Abrir desconflitos e sessões de embed a partir do app da organização, sem exigir que o parceiro use o painel B2B.

Deixar claro que a API é JSON-only em api.desconflite.com e que keys, origins e webhook se gerenciam em Configurações → Integrações.

Quando usar

Quando a organização quer criar casos a partir de outro sistema (ocorrências, CRM, app interno).

Quando a sala ou o caso precisa aparecer em iframe no produto do parceiro.

Pré-requisitos

  • Papel Proprietário na organização (só o owner gerencia Integrações).
  • Backend do parceiro para guardar a API key — nunca no frontend.

Passo a passo na interface

  1. Abra Configurações (`/configuracoes?secao=integracoes`) e crie uma API key. A secret aparece uma vez (`dk_live_…` ou `dk_test_…`); copie imediatamente.
  2. Chame a API em `api.desconflite.com` com `Authorization: Bearer dk_…`. Base: `/v1`. Endpoints: `GET /v1/health`, `POST /v1/cases` (scope `cases:write`), `POST /v1/embed-sessions` (scope `embed:write`).
  3. Para criar um desconflito: `POST /v1/cases` com `title`, `category`, `subcategory` e ao menos uma parte. Use `Idempotency-Key` se o parceiro puder reenviar o mesmo pedido.
  4. Para embed: cadastre a origin do app parceiro (ex.: `https://app.parceiro.com`) na mesma tela. Sem origin, o iframe é bloqueado (`frame-ancestors`).
  5. Gere a sessão com `POST /v1/embed-sessions` (`case_id` obrigatório). A resposta traz `embed_url` em empresas (`/embed/cases/:id?token=…`) com TTL curto.
  6. Opcional: cadastre um webhook (eventos `case.created`, `case.party_joined`, `case.closed`, `mediation.light_started`). Valide `Desconflite-Signature` com o segredo exibido na criação.

Resultado esperado

O backend do parceiro cria casos e sessões de embed sem expor a key no browser.

O iframe só carrega em origins allowlisted; a API responde só em api.desconflite.com.

Erros comuns e como resolver

  • Key no frontend ou no iframe.

    A secret fica só no servidor do parceiro. O embed usa o token curto da embed-session, não a API key.

  • Iframe em branco ou recusado pelo navegador.

    Cadastre a origin exata em Configurações → Integrações e use um embed-session token ainda válido.

  • Chamada em empresas.desconflite.com em vez de api.

    JSON `/v1/*` vive em api.desconflite.com. O host empresas serve o painel e a UI de embed, não a API.