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

API de Assinatura para E-commerce e Marketplaces

Em e-commerce e marketplaces, o gargalo raramente é vender — é cadastrar vendedores rápido o suficiente para acompanhar o crescimento. Cada novo seller precisa aceitar termos de adesão, assinar um contrato de lojista, concordar com políticas antifraude e, muitas vezes, firmar acordos de entrega e logística. Uma API de assinatura bem integrada transforma esse processo manual e demorado em um onboarding self-service que ativa o vendedor em segundos, sem time comercial no meio do caminho.

Este guia mostra como usar uma API de assinatura digital para construir um fluxo de onboarding de sellers em escala: aceite por clickwrap combinado com OTP, assinatura incorporada dentro do próprio portal do lojista e webhooks que ativam o vendedor automaticamente assim que a assinatura é concluída. Se você está avaliando uma plataforma, comece pela visão geral da API de assinatura digital e volte aqui para o recorte de e-commerce.

O público é claro: desenvolvedores, tech leads e CTOs de plataformas de varejo digital, marketplaces verticais, ERPs de e-commerce e operações de fulfillment que precisam coletar muitos contratos, com baixo atrito e validade jurídica sólida.

Os documentos que um marketplace precisa assinar

Antes de desenhar a integração, vale mapear quais documentos circulam no ciclo de vida de um vendedor. Cada um tem um perfil de risco diferente, e isso determina o nível de autenticação que você vai exigir.

Documento	Quando ocorre	Perfil de autenticação típico
Termos de adesão ao marketplace	No primeiro acesso, antes de criar a loja	`CLICK_ONLY` (clickwrap com evidências)
Contrato de seller / lojista	Ao concluir o cadastro do vendedor	`CLICK_PLUS_OTP` (aceite + código por e-mail/SMS)
Contrato de comissionamento / intermediação	Sellers PJ de maior volume	`BIOMETRIC_PLUS_OTP` ou `DIGITAL_CERTIFICATE` (ICP-Brasil)
Contrato de entrega e logística	Onboarding de transportadoras / fulfillment	`CLICK_PLUS_OTP`; `DIGITAL_CERTIFICATE` (e-CNPJ) quando exigido
Termos antifraude e uso aceitável	Anexo do cadastro ou aceite avulso	`CLICK_ONLY`
Aditivos e reajustes de comissão	Ao longo da relação	`CLICK_PLUS_OTP` (re-aceite versionado)

O ponto central: você não precisa do mesmo rigor para tudo. Termos de adesão de baixo risco podem fluir por um simples clickwrap, enquanto um contrato de comissionamento relevante pode exigir biometria ou certificado ICP-Brasil. A API SignDocs permite definir esse profile por transação, então a mesma integração suporta várias trilhas de onboarding. Para entender os perfis disponíveis, veja a seção de métodos de autenticação em o que é uma API de assinatura digital.

Clickwrap: validade jurídica do aceite eletrônico

O coração de um onboarding self-service de e-commerce é o clickwrap — o aceite eletrônico de termos por meio de uma ação afirmativa, tipicamente marcar uma caixa "Li e concordo" e clicar em "Aceitar". Na API SignDocs, isso corresponde ao step CLICK_ACCEPT.

Uma dúvida recorrente de quem está construindo o fluxo: o clique tem mesmo valor jurídico? Sim. O ordenamento brasileiro adota a liberdade das formas (Código Civil) e a MP 2.200-2/2001 reconhece a assinatura eletrônica entre as partes. O que torna o aceite defensável não é o clique isolado, mas o conjunto de evidências capturado no exato momento da ação.

O que precisa ser capturado no aceite

Identidade do aceitante: nome, e-mail e, idealmente, CPF/CNPJ do seller.
Metadados de contexto: endereço IP, user-agent do navegador e geolocalização quando disponível.
Carimbo de hora do servidor: data e hora de cada evento registradas pelos servidores da SignDocs em ISO-8601 e seladas na trilha de auditoria.
Versão exata dos termos: o hash SHA-256 do documento aceito, para provar que aquele texto específico foi apresentado.
Trilha de auditoria: sequência de eventos que mostra que o aceitante visualizou o conteúdo antes de aceitar.

A SignDocs empacota tudo isso em um evidence pack assinado (.p7m), um contêiner PKCS#7/CMS append-only que amarra o hash SHA-256 do documento, as evidências e o carimbo de hora do servidor de forma inviolável. Em uma eventual disputa, esse pacote é a prova de que o seller, em tal data, daquele IP, aceitou aquela versão dos termos.

                    Reforço de identidade: Para sellers de maior risco, use o perfil CLICK_PLUS_OTP. Um código de uso único enviado por SMS ou e-mail vincula o aceite a um canal sob controle do vendedor, elevando a robustez probatória sem comprometer a fluidez do cadastro.
                

Duas superfícies de API para dois cenários

A SignDocs expõe duas superfícies de API, e a escolha depende da complexidade do documento que o seller vai assinar.

Assinatura Expressa (Signing Sessions) — o caminho do onboarding

Para a maioria dos cadastros de e-commerce, a Assinatura Expressa é ideal. Uma única chamada a POST /v1/signing-sessions cria a sessão e devolve, na mesma resposta, um widget incorporável ou um link de checkout hospedado. É o melhor encaixe para termos de adesão e contratos de seller padronizados, em que um único vendedor assina um documento.

API Transacional — fluxos multi-signatário

Quando o documento exige várias assinaturas — por exemplo, um contrato de logística com seller, transportadora e a plataforma —, a API Transacional de envelopes gerencia o ciclo de vida completo: múltiplos signatários, ordem de assinatura e finalização. Para entender o modelo de estados, consulte o fluxo transacional da API.

Critério	Assinatura Expressa	API Transacional
Signatários	Tipicamente um (o seller)	Múltiplos, com ordem definível
Chamadas para iniciar	Uma (`POST /v1/signing-sessions`)	Criar envelope + uma sessão por signatário
Entrega da assinatura	Widget embutido ou checkout hospedado	Convites por e-mail / link por signatário
Caso de uso de e-commerce	Termos de adesão, contrato de lojista	Contrato de logística tripartite, comissionamento PJ

Fluxo de onboarding de seller com assinatura incorporada

Vamos amarrar tudo num fluxo concreto. O objetivo é cadastrar um vendedor e ativá-lo sem que ele saia do seu portal e sem intervenção humana.

O seller preenche o cadastro no portal do lojista (dados da loja, CNPJ, dados bancários).
Seu backend cria a sessão de assinatura chamando a Assinatura Expressa com o contrato de seller e o perfil de autenticação escolhido.
Você incorpora o widget retornado dentro de um iframe na própria tela de cadastro.
O seller lê e assina ali mesmo, com clickwrap + OTP, sem trocar de site.
A SignDocs dispara um webhook TRANSACTION.COMPLETED para o seu endpoint.
Seu backend ativa a loja: muda o status para ativo, libera o catálogo e envia o e-mail de boas-vindas.

O passo 2, a criação da sessão, é o coração técnico. Veja uma requisição típica:

# Criar a sessão de assinatura do contrato de seller (cURL)
curl -X POST https://api.signdocs.com.br/v1/signing-sessions \
  -H "Authorization: Bearer $ACCESS_TOKEN" \
  -H "Content-Type: application/json" \
  -H "X-Idempotency-Key: seller-sel_8a7b6c5d-onboarding" \
  -d '{
    "purpose": "DOCUMENT_SIGNATURE",
    "policy": { "profile": "CLICK_PLUS_OTP" },
    "signer": {
      "name": "Maria Silva",
      "email": "maria@lojamodelo.com.br",
      "userExternalId": "sel_8a7b6c5d",
      "cnpj": "12345678000190"
    },
    "document": {
      "content": "JVBERi0xLjQK...",
      "filename": "Contrato_Seller_LojaModelo.pdf"
    },
    "metadata": {
      "seller_id": "sel_8a7b6c5d",
      "marketplace": "loja-modelo"
    }
  }'

A resposta traz a url da sessão e o clientSecret de embarque. Lembre que esses dois valores precisam ser combinados para montar o link real do widget — a URL sozinha não basta. O embed usa o SDK oficial @signdocs-brasil/js, um checkout em popup aberto de dentro do seu portal — veja também a página da Assinatura Expressa.

// Resposta (simplificada)
{
  "sessionId": "01JC9G4J6L8N0Q2S4U6W8Y0A2C",
  "transactionId": "01JC9G4J6L8N0Q2S4U6W8Y0A2D",
  "status": "ACTIVE",
  "url": "https://sign.signdocs.com.br/s/01JC9G4J6L8N0Q2S4U6W8Y0A2C",
  "clientSecret": "ss_secret_a1b2c3d4e5f6",
  "expiresAt": "2026-06-27T18:00:00Z"
}

// Abrir o checkout de dentro do portal do seller (SDK oficial)
import { SignDocsBrasil } from '@signdocs-brasil/js';

const sd = SignDocsBrasil.init({ locale: 'pt-BR' });

// clientSecret vem do seu backend (nunca crie a sessão no navegador)
sd.checkout({
  clientSecret: 'ss_secret_a1b2c3d4e5f6',
  onComplete: () => mostrarSucessoEAvancarCadastro(),
  onClose: () => registrarAbandono(),
});

                    Atenção de segurança: a URL de assinatura é portadora de credencial. Quem cria a sessão (a plataforma) não deve abrir esse link automaticamente — ele só pode ser apresentado ao próprio seller. Gate sempre na condição de que o e-mail de quem está vendo o widget seja o do signatário, ou você corre o risco de a plataforma assinar no lugar do vendedor.
                

O checkout abre em popup e cuida sozinho das permissões de câmera quando o perfil inclui biometria facial. Se preferir não usar o SDK, o mesmo url (combinado com ?cs= + clientSecret) funciona como checkout hospedado, aberto em nova aba ou enviado ao seller por e-mail.

SignDocs: onboarding de sellers pronto para escalar. Crie sessões de assinatura com uma única chamada, embarque o widget no seu portal e ative vendedores automaticamente via webhook. SDKs oficiais em Node, Python, Go, Java, PHP e C#/.NET, ambiente de homologação gratuito e suporte em pt-BR. Fale com nossa equipe para receber as credenciais do sandbox e a proposta sob medida.

Ativação automática de vendedores via webhooks

O que diferencia um onboarding self-service de verdade de um cadastro "quase automático" é a ativação sem intervenção humana. Assim que o seller assina, a loja precisa ir ao ar — não no dia seguinte, quando alguém checar uma planilha. É exatamente para isso que servem os webhooks.

Em vez de seu backend ficar consultando a API repetidamente para saber se o contrato foi assinado, a SignDocs avisa proativamente seu endpoint quando o evento ocorre. O mergulho profundo no mecanismo está no guia de webhooks e eventos da API; aqui focamos no fluxo de e-commerce.

Os eventos que ativam o seller

SIGNING_SESSION.COMPLETED — o vendedor concluiu sua sessão de assinatura.
TRANSACTION.COMPLETED — a transação foi concluída e selada; o contrato está fechado.
SIGNING_SESSION.CANCELLED — a sessão foi cancelada; dispare um fluxo de recuperação.
SIGNING_SESSION.EXPIRED — o prazo venceu sem assinatura; recrie a sessão (antes disso, TRANSACTION.DEADLINE_APPROACHING avisa que o prazo aperta).

Veja um receptor de webhook que ativa o seller ao receber TRANSACTION.COMPLETED:

const express = require('express');
const crypto = require('crypto');
const app = express();

const WEBHOOK_SECRET = process.env.SIGNDOCS_WEBHOOK_SECRET;

app.use(express.json({
  verify: (req, res, buf) => { req.rawBody = buf.toString(); }
}));

app.post('/webhooks/signdocs', (req, res) => {
  const signature = req.headers['x-signdocs-signature'];

  // 1. Verificar HMAC-SHA256 (timing-safe)
  const expected = crypto.createHmac('sha256', WEBHOOK_SECRET)
    .update(req.rawBody).digest('hex');
  if (!crypto.timingSafeEqual(Buffer.from(expected), Buffer.from(signature))) {
    return res.status(401).end();
  }

  // 2. Idempotência: ignore eventos já processados
  //    payload = { id, eventType, tenantId, transactionId, timestamp, data }
  if (alreadyProcessed(req.body.id)) {
    return res.status(200).json({ status: 'duplicate' });
  }

  // 3. Ativar o seller de forma assíncrona (o worker busca a transação
  //    pelo transactionId e lê metadata.seller_id)
  if (req.body.eventType === 'TRANSACTION.COMPLETED') {
    enqueue('activate-seller', { transactionId: req.body.transactionId });
  }

  // 4. Responder 200 imediatamente
  res.status(200).json({ status: 'received' });
});

app.listen(3000);

Três regras de ouro para webhooks em produção, válidas para qualquer marketplace de alto volume:

Valide a assinatura HMAC-SHA256 sempre, com comparação timing-safe. Um endpoint de ativação sem verificação é um convite para que terceiros ativem lojas falsas.
Seja idempotente. Webhooks têm entrega "pelo menos uma vez"; o mesmo id de evento pode chegar duas vezes após um retry. Ativar a loja duas vezes não deve causar efeito colateral.
Responda rápido e processe depois. Retorne 200 OK e jogue a ativação para uma fila. Processamento pesado dentro do handler causa timeout e dispara retentativas desnecessárias.

Projetando para escala: alto volume e self-service

Marketplaces crescem em ondas — uma campanha de recrutamento de vendedores ou uma data sazonal pode multiplicar os cadastros em horas. Sua integração precisa absorver esses picos sem degradar.

Idempotência na criação de sessões

Assim como no receptor de webhooks, a criação de sessões deve ser idempotente. Use o header X-Idempotency-Key derivado do seller_id para que, se o cadastro for reenviado por um clique duplo ou um retry de rede, você não gere dois contratos para o mesmo vendedor.

Respeite os rate limits

A API impõe limites de taxa por conta. Em um onboarding em lote, encaminhe as requisições por uma fila com controle de concorrência, trate respostas 429 com backoff e nunca dispare todas as criações de sessão de uma vez. A criação de sessão é stateless, então paraleliza bem dentro do orçamento de rate limit.

Autenticação e ambiente

O acesso à API usa OAuth2 client-credentials: você troca suas credenciais por um bearer token (JWT assinado em ES256). Detalhes em autenticação OAuth2. Para clientes enterprise ou regulados, há suporte a mTLS. Valide todo o fluxo no ambiente de homologação (api-hml.signdocs.com.br) antes de produção — lembrando que as entidades de HML expiram em 7 dias, então é um sandbox, não um arquivo.

                    Antifraude no cadastro: ao escalar o self-service, eleve a barra de autenticação para sellers de maior risco. Um OTP_CHALLENGE dificulta cadastros automatizados, e exigir biometria ou certificado ICP-Brasil (profile: DIGITAL_CERTIFICATE) em contratos de comissionamento relevante adiciona uma camada de identidade forte sem travar o varejo de baixo ticket.
                

Versionamento de termos e re-aceite

Marketplaces revisam termos com frequência: muda a comissão, muda a política de devolução, muda a regra antifraude. Cada revisão exige um novo aceite, e a prova precisa apontar para a versão exata que cada seller aceitou.

A boa prática é versionar o documento de termos e registrar, em cada aceite, o hash da versão correspondente. Quando os termos mudam, você cria uma nova sessão de aceite (CLICK_ONLY ou CLICK_PLUS_OTP) para a base de sellers, mantendo o histórico de qual vendedor aceitou qual versão e quando. Isso é decisivo em disputas: você consegue provar que aquele seller, naquela data, concordou com aquela cláusula específica.

Qualquer assinatura emitida pela SignDocs pode ser conferida de forma independente no verificador público, o que dá ao próprio vendedor — e a terceiros — um meio de auditar a integridade do contrato sem depender da plataforma.

Verticais vizinhas: onde a mesma arquitetura se aplica

O padrão "onboarding self-service com clickwrap + assinatura incorporada + ativação por webhook" não é exclusivo de e-commerce. Se você opera em mais de um segmento, vale conhecer as variações:

Em fintechs, o mesmo fluxo cadastra clientes em contratos de crédito e abertura de conta, normalmente com biometria e camadas de identidade mais fortes.
Em plataformas imobiliárias, contratos de locação multi-signatário usam a API Transacional com ordem de assinatura entre locador, locatário e fiador.
Em saúde e telemedicina, o mesmo padrão coleta o consentimento do paciente com identidade forte e a prescrição com certificado ICP-Brasil.
Se você é uma plataforma que oferece a assinatura como recurso do próprio produto, o modelo de assinatura white-label para SaaS embarca tudo sob a sua marca.

O denominador comum é a Assinatura Expressa de uma chamada, o widget incorporável e os webhooks. Você desenha a integração uma vez e a reaproveita entre verticais, ajustando apenas o profile de autenticação e o conteúdo dos documentos.

Padrões brasileiros e validade jurídica

Para um marketplace que opera no Brasil, a aderência aos padrões nacionais é o que dá tranquilidade jurídica ao volume de contratos. A SignDocs é nativa em ICP-Brasil e LGPD-first:

MP 2.200-2/2001: base legal da assinatura eletrônica e da infraestrutura ICP-Brasil. Cobre tanto o aceite simples (clickwrap) quanto a assinatura qualificada com certificado.
PAdES / CAdES: as assinaturas são geradas no nível baseline desses padrões — PAdES para PDF e CAdES para qualquer arquivo — combinando assinatura, hash SHA-256, carimbo de hora do servidor e trilha de auditoria, mais a cadeia de certificados ICP-Brasil nas assinaturas com certificado. Os níveis com carimbo de tempo de uma ACT e validação de longo prazo (LTV) não são gerados atualmente pela API.
LGPD: o tratamento dos dados dos sellers é desenhado para conformidade desde a coleta do aceite, com trilha de consentimento auditável.

Vale uma ressalva honesta: a SignDocs roda em infraestrutura multi-região na AWS, então a força brasileira do produto está em ser ICP-Brasil-native, com produto e suporte em pt-BR e postura LGPD-first — e não na promessa de que "os dados nunca saem do Brasil". Para o que importa num contrato de seller — validade jurídica e prova robusta —, essa é a combinação que sustenta a operação em escala.

Perguntas Frequentes

O aceite por clickwrap (CLICK_ACCEPT) tem validade jurídica para contratos de seller?

Sim. No Brasil, o aceite eletrônico de termos de adesão é uma assinatura eletrônica simples, expressamente reconhecida pela MP 2.200-2/2001 e pelo Código Civil, que adota o princípio da liberdade das formas. O que dá força probatória ao clickwrap não é o clique isolado, mas o conjunto de evidências capturado no ato: identidade do aceitante, e-mail, IP, user-agent, carimbo de hora do servidor e o hash SHA-256 exato da versão dos termos aceita. A SignDocs reúne tudo isso em um evidence pack assinado, então um aceite por CLICK_ACCEPT é defensável em juízo. Para reforçar a vinculação a uma pessoa, use o perfil CLICK_PLUS_OTP, que soma ao aceite um código de uso único por SMS ou e-mail.

Como ativar um seller automaticamente assim que ele assina o contrato?

Use webhooks. Quando o vendedor conclui a assinatura, a API SignDocs envia um POST para o seu endpoint com o evento TRANSACTION.COMPLETED (ou SIGNING_SESSION.COMPLETED), contendo o transactionId. Seu backend valida a assinatura HMAC-SHA256 do webhook, confirma a idempotência pelo id do evento, busca os metadados da transação (como o seller_id) e então muda o status do vendedor para ativo, libera o catálogo e dispara o e-mail de boas-vindas. Todo o fluxo de ativação acontece em segundos, sem intervenção manual, o que é essencial para onboarding self-service em escala.

Dá para incorporar a assinatura dentro do meu portal de sellers, sem redirecionar para outro site?

Sim. A Assinatura Expressa da SignDocs (POST /v1/signing-sessions) retorna em uma única chamada o clientSecret que o SDK oficial @signdocs-brasil/js usa para abrir o checkout de assinatura como popup de dentro do próprio portal do lojista — ou a URL de checkout hospedado, se preferir não embarcar. O vendedor lê e assina o contrato sem nunca sair da sua marca, o que reduz o atrito e aumenta a conversão do onboarding. Lembre-se de não abrir automaticamente a URL de assinatura no navegador de quem está enviando: o link de assinatura é portador de credencial e só deve ser apresentado ao próprio signatário.

A API aguenta o volume de um marketplace com milhares de cadastros por dia?

Sim. A arquitetura da SignDocs roda em infraestrutura multi-região na AWS e a criação de sessões de assinatura é uma operação stateless de uma única chamada, o que permite paralelizar o onboarding. Para volumes altos, projete o cliente respeitando os rate limits da API, use idempotency keys para evitar duplicar cadastros em caso de retry, e processe os webhooks de forma assíncrona via fila. Assim o portal continua responsivo mesmo em picos como campanhas de recrutamento de vendedores ou datas sazonais.

Que tipos de documento de e-commerce eu posso enviar para assinatura via API?

Praticamente qualquer documento do ciclo de vida do vendedor: contrato de seller ou lojista, termos de adesão ao marketplace, contratos de intermediação e comissionamento, contratos de entrega e logística (transportadoras e operadores fulfillment), termos antifraude e de uso aceitável, aditivos de reajuste e instrumentos de distrato. A SignDocs gera assinaturas no nível baseline dos padrões PAdES (para PDF) e CAdES (para qualquer arquivo) — assinatura, hash SHA-256, carimbo de hora do servidor e trilha de auditoria, mais a cadeia de certificados ICP-Brasil nas assinaturas com certificado —, então o documento final tem a mesma força jurídica independentemente do tipo.

Como escolher o nível de autenticação certo para cada tipo de seller?

Ajuste o atrito ao risco. Para um vendedor pessoa física de baixo ticket aceitando termos de adesão padrão, o perfil CLICK_PLUS_OTP costuma ser suficiente e mantém o cadastro rápido. Para um seller pessoa jurídica com contrato de comissionamento relevante, adote um perfil biométrico (BIOMETRIC ou BIOMETRIC_PLUS_OTP, com prova de vida) ou exija a assinatura com certificado ICP-Brasil via o profile DIGITAL_CERTIFICATE quando houver assinatura do representante legal. A API permite definir o profile por transação, então você pode ter trilhas distintas de onboarding na mesma integração.

Cadastre sellers em escala com assinatura incorporada e ativação automática

A API SignDocs oferece Assinatura Expressa de uma chamada, checkout embutível no seu portal via SDK, clickwrap + OTP com validade jurídica e webhooks que ativam vendedores automaticamente. ICP-Brasil-native, LGPD-first e SDKs em Node, Python, Go, Java, PHP e C#/.NET. O acesso é um plano sob medida, com sandbox de homologação gratuito.

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