Publicado em: Junho 2026 | Categoria: API & Integrações | Tempo de leitura: ~14 min

Checkout Hospedado de Assinatura: Link Pronto sem Construir UI

Coletar uma assinatura por API não precisa significar construir telas de upload, posicionamento de campos, captura de assinatura e fluxo de autenticação. Com o checkout hospedado de assinatura, uma única chamada POST /v1/signing-sessions devolve um link pronto: você o compartilha por e-mail, WhatsApp ou qualquer canal, o signatário assina na página hospedada pelo SignDocs e um webhook confirma a conclusão. Zero interface do seu lado.

Esse é o caminho mais rápido para colocar assinatura digital com validade jurídica em produção. Toda a experiência de assinatura — responsiva, em pt-BR e em conformidade com a MP 2.200-2/2001 e a LGPD — é mantida pelo SignDocs. Seu time só implementa duas integrações de backend: a chamada que cria a sessão e o receptor de webhook que confirma o resultado.

Neste guia, mostramos exatamente como funciona o checkout hospedado, como montar corretamente o link de assinatura a partir da resposta da API, e quando preferir o checkout hospedado em vez do embed via SDK (popup) ou da Transaction API completa. Se você ainda está se situando, comece pelo panorama da API de assinatura digital do SignDocs.

O que é checkout hospedado de assinatura

"Checkout hospedado" é um termo emprestado dos meios de pagamento: em vez de implementar o formulário de cartão dentro do seu produto, você redireciona o cliente para uma página pronta, hospedada e mantida pelo provedor. O mesmo conceito se aplica à assinatura digital — e no SignDocs ele é entregue pela Assinatura Expressa (signing sessions).

A ideia central é simples: você não constrói nenhuma tela de assinatura. Em vez disso:

Seu backend faz uma chamada POST /v1/signing-sessions com o documento e o signatário.
A API responde com uma URL de sessão e um clientSecret.
Você combina os dois em um link pronto e o entrega ao signatário pelo canal que quiser.
O signatário abre o link e assina na página hospedada pelo SignDocs.
Um webhook avisa seu sistema quando a assinatura é concluída.

Diferente do iframe embutido — que mantém a assinatura dentro da sua aplicação — o checkout hospedado é ideal para fluxos assíncronos: você dispara o link e o signatário assina em outro momento, em outro dispositivo, sem precisar estar logado no seu sistema.

                    Resumo de uma frase: checkout hospedado = uma chamada de API → um link → o signatário assina na página do SignDocs → o webhook confirma. Nenhuma UI de assinatura para construir ou manter.
                

A chamada única: criando a signing session

Toda a mágica começa com um único request autenticado. Você precisa de um bearer token obtido via fluxo OAuth2 client-credentials e do documento que deseja coletar a assinatura. O exemplo abaixo cria uma signing session em modo hospedado:

# POST /v1/signing-sessions — cria a sessão de assinatura hospedada
curl -X POST "https://api.signdocs.com.br/v1/signing-sessions" \
  -H "Authorization: Bearer $ACCESS_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "purpose": "DOCUMENT_SIGNATURE",
    "policy": {
      "profile": "CLICK_PLUS_OTP"
    },
    "signer": {
      "name": "Maria Silva",
      "email": "maria@empresa.com.br",
      "userExternalId": "usr_12345",
      "cpf": "12345678901"
    },
    "document": {
      "content": "JVBERi0xLjcKJ...",
      "filename": "Contrato_Prestacao_Servicos.pdf"
    },
    "returnUrl": "https://seu-sistema.com.br/assinatura-concluida"
  }'

A resposta traz os dois campos que você vai usar para montar o link, além dos metadados da sessão:

// Resposta 201 Created — signing session
{
  "sessionId": "01JC9K6M8P0R2T4V6X8Z0B2D4F",
  "transactionId": "01JC9K6M8P0R2T4V6X8Z0B2D4G",
  "status": "ACTIVE",
  "url": "https://sign.signdocs.com.br/s/01JC9K6M8P0R2T4V6X8Z0B2D4F",
  "clientSecret": "ss_secret_a1b2c3d4e5f6g7h8",
  "expiresAt": "2026-06-27T18:00:00Z"
}

É isso. Sem upload de viewer, sem editor de campos, sem widget de captura de assinatura no seu frontend. A policy.profile define o rigor da autenticação — de CLICK_ONLY e CLICK_PLUS_OTP a BIOMETRIC_PLUS_OTP e DIGITAL_CERTIFICATE (certificado ICP-Brasil A1); as etapas correspondentes são geradas automaticamente e percorridas pelo signatário na página hospedada. Veja os perfis em detalhe no quickstart de 5 minutos.

Montando o link: url + clientSecret (?cs=)

Este é o detalhe que mais gera dúvida e o ponto onde integrações novas costumam tropeçar: a url sozinha não é o link de assinatura. Ela precisa ser combinada com o clientSecret como parâmetro de query cs. O link final tem o formato:

# Formato do link de assinatura pronto
{url}?cs={clientSecret}

# Exemplo, montado a partir da resposta acima:
https://sign.signdocs.com.br/s/01JC9K6M8P0R2T4V6X8Z0B2D4F?cs=ss_secret_a1b2c3d4e5f6g7h8

O clientSecret é a credencial daquela sessão específica: é ele que autoriza a abertura da página de assinatura. Sem ele, o signatário chega à página mas não consegue iniciar a assinatura. Por isso, sempre concatene os dois campos no momento de gerar o link — nunca armazene o link já montado para reuso indefinido.

Em código, a montagem é trivial:

// Node.js — montando o link a partir da resposta
const session = await createSigningSession(payload);

const signingLink = `${session.url}?cs=${encodeURIComponent(session.clientSecret)}`;

// Pronto para compartilhar por qualquer canal
console.log(signingLink);
// https://sign.signdocs.com.br/s/01JC9K6M...?cs=ss_secret_...

                    Atenção: trate o link completo como uma credencial — quem o possui pode abrir a sessão de assinatura. Compartilhe por canais privados ao destinatário (e-mail/WhatsApp pessoal) e não o exponha em URLs públicas ou logs de acesso.
                

Compartilhando o link: e-mail, WhatsApp e além

Como o checkout hospedado entrega um link comum, você é livre para distribuí-lo pelo canal mais conveniente para o seu fluxo. Alguns padrões comuns:

E-mail transacional: insira o link em um botão de call-to-action no seu próprio template de e-mail.
WhatsApp / SMS: envie o link via API de mensageria (Twilio, Meta, etc.) com uma chamada à ação curta.
Bot ou aplicativo: entregue o link dentro de uma conversa (por exemplo, um bot de atendimento) ou de uma área logada.
QR code: renderize o link como QR code para assinatura presencial em totem, balcão ou tablet.

O exemplo abaixo monta a sessão e dispara o link por WhatsApp logo em seguida:

// Node.js — cria a sessão e envia o link por WhatsApp
async function enviarParaAssinatura(documento, signatario) {
  // 1. Cria a signing session hospedada
  const session = await signdocs.signingSessions.create({
    purpose: 'DOCUMENT_SIGNATURE',
    policy: { profile: 'CLICK_PLUS_OTP' },
    signer: signatario,                // name, email, userExternalId, cpf
    document: documento,              // { content: base64, filename }
  });

  // 2. Monta o link pronto (url + clientSecret)
  const link = `${session.url}?cs=${encodeURIComponent(session.clientSecret)}`;

  // 3. Compartilha pelo canal de sua preferência
  await whatsapp.sendMessage({
    to: signatario.phone,
    body: `Olá, ${signatario.name}! Seu documento está pronto para assinatura: ${link}`
  });

  return session.sessionId;
}

Note que você controla a mensagem e o canal. O SignDocs também pode disparar o convite por e-mail automaticamente quando você informa um remetente diferente do signatário, mas no padrão de checkout hospedado é comum entregar o link você mesmo para manter sua identidade de marca na comunicação.

Confirmando a assinatura: o webhook fecha o ciclo

O link compartilhado é apenas metade da integração. A outra metade é saber quando e se o documento foi assinado — e isso vem por webhook, não pelo fechamento da aba do navegador.

Ao concluir a assinatura na página hospedada, o SignDocs envia um HTTP POST assinado com HMAC-SHA256 (cabeçalho X-SignDocs-Signature) para o endpoint que você registrou uma única vez via POST /v1/webhooks. Esse evento é o sinal autoritativo de conclusão:

# Registre o endpoint uma vez (escopo webhooks:write)
curl -X POST https://api.signdocs.com.br/v1/webhooks \
  -H "Authorization: Bearer $ACCESS_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "url": "https://seu-sistema.com.br/webhooks/signdocs",
    "events": ["SIGNING_SESSION.COMPLETED", "TRANSACTION.COMPLETED"]
  }'

// Webhook de conclusão recebido no seu endpoint
{
  "id": "01JC9K7N9Q1S3U5W7Y9A1C3E5G",
  "eventType": "SIGNING_SESSION.COMPLETED",
  "tenantId": "ten_a1b2c3",
  "transactionId": "01JC9K6M8P0R2T4V6X8Z0B2D4G",
  "timestamp": "2026-06-25T13:21:09Z",
  "data": { "status": "COMPLETED" }
}

De posse do evento, seu sistema usa o transactionId para baixar o documento assinado (via documents.download → URL temporária) e o respectivo evidence pack (.p7m) com a prova jurídica completa, e dá sequência ao seu fluxo de negócio (faturamento, onboarding, arquivamento). A mecânica completa de verificação HMAC, idempotência e retry está detalhada no nosso guia de webhooks e eventos da API de assinatura.

                    Boa prática: nunca trate o redirecionamento de "obrigado" no navegador como confirmação de assinatura. O navegador pode fechar, cair a conexão ou o usuário sair antes. A fonte da verdade é sempre o webhook SIGNING_SESSION.COMPLETED.
                

Checkout hospedado vs. iframe embutido vs. Transaction API

O SignDocs oferece três formas de coletar assinaturas, e a escolha certa depende de onde a assinatura precisa acontecer e de quão complexo é o fluxo. As três são modos da mesma plataforma e podem coexistir no mesmo produto.

Critério	Checkout hospedado	Embed (SDK / popup)	Transaction API
Onde o signatário assina	Página hospedada pelo SignDocs (link externo)	De dentro da sua aplicação (checkout em popup via SDK)	Onde você decidir (envelope flexível)
UI a construir	Nenhuma	Abrir o checkout via SDK `@signdocs-brasil/js`	Conforme o caso (hosted ou embed por sessão de signatário)
Chamada de criação	1 × `POST /v1/signing-sessions`	1 × `POST /v1/signing-sessions`	Envelope + uma sessão por signatário
Múltiplos signatários / ordem	1 signatário por sessão	1 signatário por sessão	Sim — até 100 signatários no mesmo documento, com ordem
Canal de entrega	Assíncrono (e-mail, WhatsApp, SMS, QR)	Síncrono (signatário já está na sua tela)	Flexível, por etapa do envelope
Esforço de integração	Mínimo (criar link + webhook)	Baixo (SDK no frontend + webhook)	Maior (modelar o ciclo de vida completo)
Ideal para	Enviar para assinar fora do seu app	Assinar sem sair do seu app	Contratos multipartes e fluxos corporativos

Resumindo a decisão:

Escolha checkout hospedado quando você dispara o documento e o signatário assina em outro momento/dispositivo, sem precisar estar no seu produto. É o caminho mais rápido para entrar em produção.
Escolha o embed via SDK quando o signatário já está dentro da sua aplicação e você quer que ele assine ali mesmo, sem redirecionar: o SDK oficial @signdocs-brasil/js abre o checkout em popup com o clientSecret e devolve callbacks de conclusão — veja a página da Assinatura Expressa.
Escolha a Transaction API quando precisa de envelopes com múltiplos signatários no mesmo documento, ordem de assinatura e controle total do ciclo de vida.

                    Importante: tanto o checkout hospedado quanto o embed via SDK usam a mesma chamada POST /v1/signing-sessions — a diferença está só em como você apresenta o resultado: redireciona para url?cs=clientSecret, ou entrega o clientSecret ao SDK para abrir o popup. Trocar entre os dois é uma mudança pequena, não uma reescrita.
                

Ambiente de homologação e validação jurídica

Antes de ir para produção, valide todo o fluxo em homologação. O host de sandbox é api-hml.signdocs.com.br (forma com hífen, não api.hml). Lembre-se de que entidades em homologação têm TTL de 7 dias — sessões de teste antigas desaparecem automaticamente, o que é ótimo para manter o ambiente limpo, mas significa que você não deve depender de IDs de sessão antigos em testes de longa duração.

Do ponto de vista jurídico, o documento assinado via checkout hospedado tem a mesma validade de qualquer assinatura coletada pela plataforma: amparado pela MP 2.200-2/2001 (ICP-Brasil), com evidence pack .p7m reunindo hash SHA-256 do documento, carimbo de hora do servidor e trilha de auditoria. Qualquer parte pode conferir a autenticidade no verificador público do SignDocs. A escolha do método de assinatura (certificado ICP-Brasil, OTP, biometria) define apenas o nível de garantia, não a validade do mecanismo.

O SignDocs opera em infraestrutura AWS multi-região (sa-east-1 e us-east-1), com produto e suporte nativos em pt-BR e abordagem LGPD-first. O acesso à API é contratado como plano sob medida com o time comercial, com sandbox gratuito — entenda os modelos do mercado em quanto custa uma API de assinatura.

Resumo: checkout hospedado em 4 passos

Crie a sessão: uma chamada POST /v1/signing-sessions com o documento, o signatário e a política (webhooks são registrados uma única vez, à parte).
Monte o link: combine url + clientSecret no formato {url}?cs={clientSecret}.
Compartilhe: entregue o link por e-mail, WhatsApp, SMS, bot ou QR code.
Confirme: aguarde o webhook SIGNING_SESSION.COMPLETED e baixe o documento assinado.

Nenhuma interface de assinatura para construir. Nenhum viewer de PDF para manter. Apenas uma chamada de API, um link e um webhook — com validade jurídica de ponta a ponta.

SignDocs: assinatura em produção sem construir UI. Com a Assinatura Expressa, uma chamada gera um link pronto que você compartilha por qualquer canal, enquanto o webhook confirma a conclusão. Fale com nossa equipe para receber as credenciais do sandbox gratuito e discutir o melhor modo de integração para o seu produto — o acesso à API é um plano sob medida.

Perguntas Frequentes

O que é checkout hospedado de assinatura?

Checkout hospedado é uma página de assinatura pronta, hospedada e mantida pelo próprio SignDocs, para a qual você apenas envia o signatário. Em vez de construir telas de upload, posicionamento de campos, coleta de assinatura e fluxo de autenticação, você faz uma única chamada POST /v1/signing-sessions, recebe um link e o compartilha por e-mail, WhatsApp ou qualquer canal. O signatário abre o link, é autenticado e assina na interface do SignDocs, que já é responsiva, em pt-BR e com validade jurídica pela MP 2.200-2/2001.

Preciso construir alguma interface para usar o checkout hospedado?

Não. Esse é exatamente o objetivo do checkout hospedado: zero UI de assinatura do seu lado. Toda a experiência de assinatura — visualização do documento, autenticação do signatário, coleta da assinatura e tela de conclusão — roda na página hospedada pelo SignDocs. Você só precisa de duas integrações simples no backend: a chamada que cria a signing session e o receptor de webhook que confirma a conclusão. Nenhum componente visual precisa ser desenvolvido.

Como montar o link de assinatura a partir da resposta da API?

A resposta da signing session traz dois campos que precisam ser combinados: a url da sessão e o clientSecret. O link final é a url acrescida do clientSecret como parâmetro de query cs, no formato {url}?cs={clientSecret}. A url sozinha não é suficiente — sem o clientSecret o signatário não consegue iniciar a assinatura. Sempre monte o link concatenando os dois campos antes de enviar ao signatário.

Quando usar checkout hospedado em vez de iframe embutido ou da Transaction API?

Use checkout hospedado quando você compartilha o link por canais assíncronos (e-mail, WhatsApp, SMS) e não precisa que a assinatura aconteça dentro do seu produto. Use o embed via SDK (popup aberto com o clientSecret) quando o signatário já está logado na sua aplicação e você quer manter a assinatura no seu contexto. Use a API de envelopes quando precisa de múltiplos signatários no mesmo documento, ordem de assinatura e controle total do ciclo de vida. Os três são modos da mesma plataforma e podem coexistir.

Como sei que o documento foi assinado no checkout hospedado?

Pela confirmação via webhook. Você registra seu endpoint uma única vez via POST /v1/webhooks; quando o signatário conclui a assinatura, o SignDocs envia um HTTP POST assinado com HMAC-SHA256 para esse endpoint com o evento SIGNING_SESSION.COMPLETED. Esse é o sinal autoritativo de que o documento está assinado — não confie no fechamento da aba do navegador. Com o evento recebido, você baixa o documento assinado e o evidence pack e dá sequência ao seu fluxo.

O link de assinatura expira? Posso reenviá-lo?

Sim, a signing session tem uma janela de validade definida na criação. Após a expiração, o link deixa de ser válido e é necessário criar uma nova sessão. Enquanto a sessão está ativa, você pode reenviar o mesmo link por outro canal sem custo adicional. Em ambiente de homologação (api-hml.signdocs.com.br), lembre-se de que as entidades têm TTL de 7 dias, então sessões de teste antigas desaparecem automaticamente.

Coloque assinatura digital em produção sem construir UI

Com o checkout hospedado da Assinatura Expressa, uma chamada de API devolve um link pronto que você compartilha por qualquer canal. O signatário assina na página do SignDocs e o webhook confirma a conclusão — tudo com validade jurídica ICP-Brasil.

Fale com o time comercial Conheça a plataforma grátis