Posicionamento assistido

Nem todo mundo que envia um contrato sabe — ou precisa saber — o que é coordenada percentual. Quando quem escolhe o lugar da assinatura é o usuário do seu sistema, e não o seu código, use o posicionamento assistido: o SignXP devolve uma tela pronta onde ele abre o documento, clica onde cada assinatura vai e confirma.

Enquanto ninguém confirma, nenhum signatário é convidado.

Como funciona

1. seu sistema ──POST /documents (placement: interactive)──▶ SignXP
                                          │
                    placement_url ◀───────┘   status: awaiting_placement

2. usuário do seu sistema abre a placement_url, clica e confirma

3. SignXP ──convite──▶ signatário (por e-mail, se ele tiver um)
              ──callback document.placed──▶ seu sistema

1. Crie o documento sem os campos

{
  "external_id": "contrato-2026-0001",
  "title": "Contrato de Prestação de Serviços",
  "callback_url": "https://meu-sistema.com.br/webhooks/signxp",
  "placement": "interactive",
  "pdf_base64": "JVBERi0xLjcK...",
  "signers": [
    { "key": "contratante", "name": "Maria Souza", "email": "maria@empresa.com.br" }
  ]
}

placement: "interactive" troca o fields por uma tela. As duas coisas são mutuamente exclusivas: enviar fields junto devolve 422 — recusar é melhor do que aceitar e ignorar, que faria você achar que posicionou.

Resposta

{
  "id": 128,
  "status": "draft",
  "status_url": "https://api.signxp.com.br/api/v1/documents/128",
  "placement_url": "https://app.signxp.com.br/posicionar/9f2c7a1b..."
}

A placement_url é o que você entrega ao seu usuário. Ela também aparece na consulta de status enquanto o documento estiver em awaiting_placement, então não precisa ser guardada.

2. Leve o usuário até a tela

Opção A — abrir a URL

O caminho mais simples: abra a placement_url em uma nova aba (ou redirecione). Não exige nenhuma linha de JavaScript.

<a href="{{ placement_url }}" target="_blank">Posicionar assinaturas</a>

Opção B — widget dentro do seu sistema

O usuário não sai da sua tela. Carregue o widget e abra o posicionador em uma janela modal:

<script src="https://app.signxp.com.br/embed/positioner.js"></script>
<script>
  SignXP.openPositioner({
    url: placementUrl,
    onPlaced: function () {
      // Campos confirmados e convite enviado. Atualize sua tela.
    },
    onCancel: function () {
      // Usuário fechou sem confirmar. O documento continua esperando.
    }
  });
</script>

Para embutir sem modal, dentro de um elemento seu:

SignXP.mountPositioner({
  url: placementUrl,
  container: '#area-do-posicionador',
  onPlaced: function () { /* ... */ }
});

Método	Parâmetros
SignXP.openPositioner	url (obrigatório), onPlaced, onCancel. Devolve { close() }.
SignXP.mountPositioner	url e container (obrigatórios), onPlaced, onCancel. Devolve { destroy() }.

O endereço https://app.signxp.com.br/embed/positioner.js é fixo e versionado por nós — não copie o arquivo para o seu servidor, ou você deixará de receber correções.

Libere o seu domínio. Por padrão a tela pode ser embutida em qualquer site (o segredo é o token da URL). Se quiser restringir ao seu domínio — recomendado —, cadastre as origens autorizadas em Configurações, no portal da sua conta; o navegador passa a recusar o iframe em qualquer outro lugar. A mesma lista vale para a assinatura embutida.

3. Saiba quando terminou

Três formas, use a que couber:

• Callback document.placed, se você informou callback_url. É o caminho recomendado — chega no momento exato.
• onPlaced do widget, quando estiver usando a opção B.
• Consulta de status: o documento sai de awaiting_placement e entra em pending.

O corpo do callback é o mesmo dos demais eventos, com event: "document.placed" e status: "pending".

O que o usuário vê

A tela lista os signatários do documento, mostra o PDF página a página e pede um clique no lugar da assinatura de cada um. Ele pode arrastar para definir o tamanho ou apenas clicar — nesse caso o campo entra no tamanho padrão. O botão de confirmação só libera quando todos os signatários têm ao menos um campo, então é impossível concluir deixando alguém sem lugar para assinar.

Quando a licença inclui rúbrica, aparece também a opção de posicionar rúbricas.

Limites

Situação	O que acontece
Documento já posicionado	Nova confirmação devolve 409; a tela passa a exibir o estado concluído.
Campo fora da página	422 com a mensagem para o usuário corrigir; nada é gravado.
Página inexistente no PDF	422.
Ninguém confirma	O documento fica em awaiting_placement indefinidamente e não consome nada além da quota já contada no envio.

A placement_url é pessoal e intransferível como o link de assinatura: quem a tem pode definir onde as assinaturas ficam. Trate-a com o mesmo cuidado.