Publicado em: Fevereiro 2026 | Categoria: Arquitetura | Tempo de leitura: ~20 min

Arquitetura de Fluxos Transacionais em APIs de Assinatura Digital

Quando uma empresa decide integrar assinatura digital diretamente em seus sistemas, o primeiro conceito que precisa dominar e o de fluxo transacional. Diferente de plataformas com interface grafica onde o usuario clica em botoes para enviar documentos, uma API de assinatura digital expoe esse processo como uma sequencia de chamadas programaticas, cada uma representando uma etapa atomica do ciclo de vida de uma transacao de assinatura.

Um modelo transacional em APIs de assinatura digital define como um documento percorre todas as fases desde a criacao inicial ate a finalizacao com evidencias juridicas. Esse modelo e projetado para ser deterministico, rastreavel e resiliente a falhas. Cada chamada de API muda o estado da transacao de forma previsivel, e cada transicao de estado pode ser monitorada via webhooks ou polling.

Para desenvolvedores e arquitetos de software, compreender essa arquitetura e fundamental para construir integracoes robustas. Nao se trata apenas de "enviar um PDF e coletar assinaturas" -- e sobre modelar um workflow que lida com multiplos signatarios, diferentes metodos de autenticacao, uploads de documentos grandes, rastreamento em tempo real, tratamento de erros e geracoes de evidence packs com validade juridica.

Se voce ainda esta explorando os fundamentos de APIs de assinatura digital, recomendamos comecar pelo artigo O que e uma API de Assinatura Digital antes de mergulhar nos detalhes de arquitetura transacional abordados aqui.

Visão geral do modelo transacional

Na API do SignDocs, a unidade básica é a transação: um documento, um signatário e uma política de autenticação que gera as etapas a cumprir. O ciclo de vida completo segue seis passos bem definidos, cada um correspondendo a endpoints REST e a uma transição de estado:

Criar a transação (POST /v1/transactions) — define finalidade, política e signatário; as etapas são geradas automaticamente
Enviar o documento (POST /v1/transactions/{id}/document, inline ou via presign) — o hash SHA-256 é calculado no servidor
Executar as etapas (GET .../steps, POST .../steps/{stepId}/start e /complete) — aceite, OTP, biometria ou certificado, em ordem
Finalizar (POST /v1/transactions/{id}/finalize) — gera o evidence pack .p7m e aplica o carimbo no PDF
Rastrear (webhooks + GET /v1/transactions/{id}) — cada evento em tempo real
Evidência e verificação (GET .../evidence, GET /v1/verify/{evidenceId}) — download do pacote e conferência pública

A tabela abaixo resume os endpoints envolvidos, os estados de transição e os códigos HTTP esperados:

Etapa	Endpoint	Método	Estado resultante	HTTP
Criar transação	`/v1/transactions`	POST	`CREATED`	201
Upload do documento (inline)	`/v1/transactions/{id}/document`	POST	`DOCUMENT_UPLOADED`	200
Upload direto (arquivos maiores)	`/v1/transactions/{id}/document/presign` + PUT na URL + `/document/confirm`	POST/PUT/POST	`DOCUMENT_UPLOADED`	200
Listar etapas	`/v1/transactions/{id}/steps`	GET	—	200
Iniciar / concluir etapa	`.../steps/{stepId}/start` e `.../complete`	POST	`IN_PROGRESS`	200
Finalizar	`/v1/transactions/{id}/finalize`	POST	`COMPLETED`	200
Consultar status	`/v1/transactions/{id}`	GET	(varia)	200
Baixar evidence pack	`/v1/transactions/{id}/evidence`	GET	`COMPLETED`	200

Diagrama de estados da transação:
CREATED → DOCUMENT_UPLOADED → IN_PROGRESS → COMPLETED

Estados alternativos: CANCELLED, EXPIRED, FAILED

As transições são para a frente e auditáveis — não há como "voltar" uma transação concluída, o que garante integridade do fluxo, essencial para conformidade com a legislação brasileira de assinatura digital.

Passo 1: Criar a transação (POST /v1/transactions)

A primeira chamada cria a transação: você declara a finalidade (purpose), a política de autenticação (policy.profile) e o signatário. Um detalhe importante do modelo do SignDocs: as etapas de assinatura são geradas automaticamente a partir do perfil da política — CLICK_PLUS_OTP, por exemplo, gera as etapas CLICK_ACCEPT, OTP_CHALLENGE e OTP_VERIFY, já na ordem correta.

// Passo 1: Criar uma nova transação de assinatura

const response = await fetch('https://api.signdocs.com.br/v1/transactions', {
  method: 'POST',
  headers: {
    'Authorization': `Bearer ${accessToken}`,
    'Content-Type': 'application/json',
    'X-Idempotency-Key': 'contrato-2026-0455'
  },
  body: JSON.stringify({
    purpose: 'DOCUMENT_SIGNATURE',
    policy: { profile: 'CLICK_PLUS_OTP' },
    signer: {
      name: 'Maria Silva',
      email: 'maria@empresa.com.br',
      userExternalId: 'usr_12345',
      cpf: '12345678901'
    },
    metadata: {
      crm_deal_id: 'deal_789',
      department: 'comercial'
    }
  })
});

const tx = await response.json();

// Resposta (201 Created):
// {
//   "transactionId": "01JC8Z3M9QK4T2V7X1B5N6P8R0",
//   "status": "CREATED",
//   "steps": [
//     { "stepId": "01JC...", "type": "CLICK_ACCEPT", "status": "PENDING", "order": 0 },
//     { "stepId": "01JC...", "type": "OTP_CHALLENGE", "status": "PENDING", "order": 1 },
//     { "stepId": "01JC...", "type": "OTP_VERIFY",   "status": "PENDING", "order": 2 }
//   ]
// }

Campos importantes na criação

purpose: a finalidade da operação — DOCUMENT_SIGNATURE para assinar um documento.
policy.profile: o nível de autenticação, de CLICK_ONLY a DIGITAL_CERTIFICATE — é ele que determina as etapas geradas.
signer: nome, e-mail, CPF (ou CNPJ) e o userExternalId — o identificador do signatário no seu sistema.
metadata: objeto chave-valor para dados do seu sistema (IDs de CRM/ERP), retornado nas consultas para correlação.
X-Idempotency-Key (header): garante que retries não criem transações duplicadas.

Passo 2: Enviar o documento

Com a transação criada, o próximo passo é o documento. Há dois caminhos:

Upload inline (o mais simples): envie o PDF codificado em base64 no corpo de POST /v1/transactions/{id}/document, até 10 MB. O hash SHA-256 é calculado no servidor e devolvido na resposta.
Upload direto (presign): para evitar trafegar o arquivo pelo seu backend, solicite uma URL temporária via POST /v1/transactions/{id}/document/presign, faça o PUT do arquivo diretamente no storage e confirme com POST /v1/transactions/{id}/document/confirm.

// Passo 2 (inline): enviar o PDF em base64

const pdfBase64 = fs.readFileSync('contrato.pdf').toString('base64');

const docRes = await fetch(
  `https://api.signdocs.com.br/v1/transactions/${txId}/document`,
  {
    method: 'POST',
    headers: {
      'Authorization': `Bearer ${accessToken}`,
      'Content-Type': 'application/json'
    },
    body: JSON.stringify({ content: pdfBase64 })
  }
);

// Resposta:
// { "status": "DOCUMENT_UPLOADED", "documentHash": "sha256:a1b2c3d4e5f6..." }

A partir daqui, o hash é a identidade criptográfica do documento: é a ele que as assinaturas e as evidências ficarão amarradas. Qualquer alteração no arquivo produziria outro hash — e é isso que torna adulterações detectáveis.

Passo 3: Executar as etapas de assinatura

As etapas geradas pela política devem ser executadas em ordem — a API valida que as anteriores estejam concluídas antes de permitir o início da próxima. O ciclo de cada etapa é: listar (GET .../steps), iniciar (POST .../steps/{stepId}/start) e concluir (POST .../steps/{stepId}/complete).

// Passo 3: listar, iniciar e concluir etapas

// 3a. Listar
const { steps } = await get(`/v1/transactions/${txId}/steps`);
// [{ stepId, type: "CLICK_ACCEPT", status: "PENDING", order: 0,
//    attempts: 0, maxAttempts: 10 }, ...]

// 3b. Iniciar a próxima etapa pendente
await post(`/v1/transactions/${txId}/steps/${stepId}/start`, {});

// 3c. Concluir (payload varia por tipo de etapa)
await post(`/v1/transactions/${txId}/steps/${stepId}/complete`, {
  accepted: true          // CLICK_ACCEPT
  // otp: "123456"        // OTP_VERIFY
});

Cada tipo de etapa tem sua semântica: CLICK_ACCEPT registra o aceite; OTP_CHALLENGE dispara o código por e-mail ou SMS e OTP_VERIFY o valida (para reenviar o código, chame start novamente na etapa de challenge); BIOMETRIC_LIVENESS e BIOMETRIC_MATCH cuidam da prova de vida e comparação facial; DIGITAL_SIGN_A1 executa a assinatura com certificado ICP-Brasil em duas fases (prepare + complete), sem que a chave privada saia da infraestrutura do cliente. As etapas expõem attempts/maxAttempts e o status evolui por PENDING → STARTED → COMPLETED (ou FAILED/SKIPPED).

Quem executa as etapas? Este artigo mostra a orquestração direta — sua aplicação chamando start/complete — que é útil para fluxos embutidos e canais próprios. Na maioria das integrações, porém, quem percorre as etapas é o próprio signatário em uma página hospedada: a Assinatura Expressa cria a transação, o documento e as etapas em uma única chamada e devolve o link de checkout. O modelo transacional por baixo é exatamente o mesmo — veja o caminho rápido no quickstart de 5 minutos.

Passo 4: Finalizar a transação

Com todas as etapas concluídas, a finalização fecha o ciclo: o servidor valida o estado, gera o evidence pack — um arquivo .p7m assinado com certificado ICP-Brasil A1 da plataforma — e aplica o carimbo visual no PDF. A resposta traz o evidenceId, a chave pública de verificação da transação:

// Passo 4: finalizar

const result = await post(`/v1/transactions/${txId}/finalize`);

// {
//   "status": "COMPLETED",
//   "evidenceId": "01JC8Z9...",
//   "evidenceHash": "sha256:f7e6d5..."
// }

Passo 5: Rastrear progresso via webhooks e polling

Webhooks (recomendado)

Registre um endpoint via POST /v1/webhooks (escopo webhooks:write) e receba um POST HTTPS assinado com HMAC-SHA256 (cabeçalho X-SignDocs-Signature) a cada transição: TRANSACTION.CREATED, STEP.COMPLETED, STEP.FAILED, TRANSACTION.COMPLETED, TRANSACTION.EXPIRED, TRANSACTION.DEADLINE_APPROACHING, entre outros.

// Exemplo de handler de webhook (Express.js)

app.post('/webhooks/signdocs', (req, res) => {
  // 1. Verificar a assinatura HMAC antes de confiar no evento
  if (!verifyHmac(req.headers['x-signdocs-signature'], req.rawBody)) {
    return res.status(401).end();
  }

  // 2. Responder 200 rápido; processar de forma assíncrona
  res.status(200).end();

  // 3. Despachar por tipo de evento (com deduplicação pelo id)
  const event = req.body;
  // event = { id, eventType, tenantId, transactionId, timestamp, data }
  switch (event.eventType) {
    case 'TRANSACTION.COMPLETED':
      onCompleted(event.transactionId);
      break;
    case 'STEP.FAILED':
      onStepFailed(event.transactionId, event.data);
      break;
  }
});

Os detalhes de verificação HMAC, retries com backoff e deduplicação estão no guia dedicado de webhooks e eventos da API.

Polling (fallback)

// Polling de reconciliação com backoff exponencial

async function waitForCompletion(txId, maxAttempts = 8) {
  let delay = 2000;
  for (let i = 0; i < maxAttempts; i++) {
    const tx = await get(`/v1/transactions/${txId}`);
    if (['COMPLETED', 'CANCELLED', 'EXPIRED', 'FAILED'].includes(tx.status)) {
      return tx;
    }
    await sleep(delay);
    delay = Math.min(delay * 2, 60000);  // teto de 60s
  }
  throw new Error('Timeout aguardando conclusão');
}

Passo 6: Evidência e verificação pública

Com a transação em COMPLETED, dois artefatos interessam ao seu sistema:

// Baixar o evidence pack (.p7m) — escopo evidence:read
GET /v1/transactions/{transactionId}/evidence
// → metadados + URL temporária do arquivo .p7m

// Verificação pública, sem autenticação, pelo evidenceId
GET /v1/verify/{evidenceId}

O .p7m deve ser baixado e arquivado no seu repositório documental (a URL é temporária). Já a verificação pelo evidenceId é pública e permanente: qualquer parte — inclusive um juízo — pode conferir a autenticidade no verificador da SignDocs, sem precisar de conta. A anatomia completa do pacote está no guia do evidence pack .p7m como prova jurídica.

Múltiplos signatários e alto volume

O modelo transacional escala em duas direções, com mecanismos diferentes:

Vários signatários no mesmo documento: use um envelope (POST /v1/envelopes + uma sessão por signatário), com modo sequencial ou paralelo e até 100 signatários — cada um com sua própria política. O guia completo é o de ordem de assinatura com múltiplos signatários.
Muitos documentos independentes: não há endpoint de lote — o padrão é um laço no seu backend criando uma transação por documento, cada uma com seu X-Idempotency-Key, com controle de concorrência para respeitar os limites de taxa. Cada transação emite seus próprios webhooks, então o rastreamento não muda.

Tratamento de erros e casos extremos

1. URL de upload expirada

As URLs de presign têm vida curta por segurança. Se expirar antes do PUT, solicite outra — a transação permanece em CREATED e nada é perdido. Para arquivos de até 10 MB, o upload inline em base64 elimina esse cenário.

2. Prazo se aproximando e expiração

O evento TRANSACTION.DEADLINE_APPROACHING avisa antes de o prazo vencer — é o gatilho ideal para reenviar o link ao signatário (em sessões hospedadas, POST /v1/signing-sessions/{sessionId}/resend-invite reenvia o convite por e-mail). Se o prazo vence, a transação expira (EXPIRED) e a recuperação é criar uma nova — os erros seguem o formato RFC 7807 (application/problem+json), o que facilita o tratamento programático.

3. Cancelamento

Transações e sessões podem ser canceladas antes da conclusão (POST /v1/signing-sessions/{sessionId}/cancel nas sessões hospedadas; envelopes têm POST /v1/envelopes/{id}/cancel). O estado vira CANCELLED, o evento correspondente é emitido e as assinaturas já concluídas permanecem com suas evidências preservadas.

4. Etapa reprovada

Uma verificação biométrica reprovada ou um OTP errado repetidas vezes geram STEP.FAILED. As etapas expõem attempts/maxAttempts; esgotadas as tentativas, trate o caso no seu backend — oferecendo outro método (os perfis com fallback documental existem exatamente para isso) ou encerrando a transação como FAILED.

5. Erros de rede e retries

Todo POST de criação deve carregar X-Idempotency-Key. Com ela, o retry de um timeout devolve a resposta original em vez de duplicar a operação. Combine com backoff exponencial e trate 401 renovando o token OAuth2 (ele expira em 15 minutos) antes de reprocessar a fila.

Perguntas frequentes

O que acontece se a URL de upload (presign) expirar antes do envio?

Nada de irreversível: a transação permanece no estado CREATED. As URLs de upload direto obtidas via POST /v1/transactions/{id}/document/presign têm vida curta por segurança — se expirar, basta solicitar uma nova e repetir o envio. Para documentos de até 10 MB, a alternativa mais simples é o upload inline em base64 via POST /v1/transactions/{id}/document, que dispensa a presigned URL. Em ambos os casos, implemente retry no seu cliente HTTP.

Posso alterar a ordem dos signatários depois de criar o envelope?

A posição de cada signatário é definida pelo signerIndex no momento em que a sessão é adicionada ao envelope (POST /v1/envelopes/{id}/sessions) e não é editável depois. Se a ordem mudou antes de as assinaturas começarem, cancele a sessão afetada (POST /v1/signing-sessions/{sessionId}/cancel) e crie outra com o índice correto — ou, em mudanças maiores, cancele o envelope e recrie. Uma alternativa flexível é adicionar as sessões de forma tardia: crie cada sessão apenas quando chegar a vez daquele signatário, decidindo a ordem em tempo real no seu backend.

Qual a diferença entre polling e webhooks para rastrear o status?

Polling consiste em consultar periodicamente o endpoint GET /v1/transactions/{id} para verificar mudanças de status. É simples de implementar, mas consome banda e tem latência. Webhooks são notificações push assinadas com HMAC-SHA256 que a API envia ao seu servidor quando eventos ocorrem (TRANSACTION.COMPLETED, STEP.FAILED, ENVELOPE.ALL_SIGNED etc.), com latência praticamente zero. A recomendação é usar webhooks como método principal e manter um polling de reconciliação como rede de segurança.

Existe um limite de signatários ou de documentos por operação?

Sim. Cada transação carrega um documento e um signatário; para vários signatários no mesmo documento, o envelope aceita até 100 sessões (limite validado pela API com erro 400 acima disso). Não existe endpoint de criação em lote de transações: para alto volume — como 500 contratos independentes — o padrão é um laço no seu backend criando uma transação por documento, com X-Idempotency-Key por item e controle de concorrência para respeitar os limites de taxa.

Como garantir idempotência ao criar transações via API?

Envie o cabeçalho X-Idempotency-Key com um valor único por operação lógica (por exemplo, o ID do contrato no seu sistema) em cada POST /v1/transactions. Se um retry reenviar a mesma chave, a API devolve a resposta original em vez de criar uma transação duplicada. Isso é essencial em cenários de timeout de rede e em integrações distribuídas, onde a mesma operação pode ser tentada mais de uma vez.

O evidence pack inclui quais informações exatamente?

O evidence pack é um arquivo .p7m (PKCS#7/CMS) assinado com certificado ICP-Brasil A1 da plataforma, gerado na finalização. Ele amarra o hash SHA-256 do documento, a identificação do signatário, o registro de cada etapa de autenticação concluída (aceite, OTP, biometria, certificado), endereço IP e geolocalização, e os carimbos de hora do servidor de cada evento em trilha de auditoria append-only. Quando há assinatura com certificado ICP-Brasil, a cadeia de certificados também é preservada. É essa amarração criptográfica que sustenta a prova nos termos da MP 2.200-2/2001.

É necessário manter o documento original após receber o documento assinado?

É uma boa prática, embora a verificação não dependa disso: o hash SHA-256 do documento fica registrado na transação e no evidence pack, e o evidenceId permite conferir a autenticidade a qualquer momento no verificador público. Guarde o PDF carimbado e o .p7m no seu repositório documental (o link de download do pacote é temporário) e trate o original como parte do seu arquivo de contrato — em disputas, apresentar original, versão assinada e evidências juntos simplifica a perícia.

Pronto para implementar fluxos transacionais de assinatura digital?

O modelo que você acabou de ver — estados previsíveis, etapas auditáveis, evidência criptográfica ao final — está disponível no sandbox de homologação gratuito da SignDocs. O acesso à API é contratado como plano sob medida com o time comercial.

Fale com o time comercial Siga o quickstart de 5 minutos