Guias de Desenvolvimento

Política e Conformidade

Signing Sessions

Guias dos SDKs

Assinatura Simples (CLICK_ONLY)

O fluxo mais básico de assinatura. Utiliza o perfil CLICK_ONLY, que gera uma única etapa CLICK_ACCEPT — o signatário aceita o documento com um clique.

Etapas geradas: CLICK_ACCEPT

Passo 1: Criar transação com documento inline

Cria a transação já com o documento embutido em base64. O status resultante será DOCUMENT_UPLOADED.

import { SignDocsBrasilClient } from '@signdocs-brasil/api';

const tx = await client.transactions.create({
  purpose: 'DOCUMENT_SIGNATURE',
  policy: { profile: 'CLICK_ONLY' },
  signer: {
    name: 'João Silva',
    email: 'joao@example.com',
    userExternalId: 'user-001',
  },
  document: {
    content: documentBase64,
    filename: 'contrato.pdf',
  },
});
console.log(tx.transactionId, tx.status); // DOCUMENT_UPLOADED

from signdocs_brasil import SignDocsBrasilClient, ClientConfig
from signdocs_brasil.models import (
    CreateTransactionRequest, Policy, Signer, InlineDocument,
)

tx = client.transactions.create(CreateTransactionRequest(
    purpose='DOCUMENT_SIGNATURE',
    policy=Policy(profile='CLICK_ONLY'),
    signer=Signer(
        name='João Silva',
        email='joao@example.com',
        user_external_id='user-001',
    ),
    document=InlineDocument(
        content=document_base64,
        filename='contrato.pdf',
    ),
))
print(tx.transaction_id, tx.status)  # DOCUMENT_UPLOADED

tx, err := client.Transactions.Create(ctx, &signdocs.CreateTransactionRequest{
    Purpose: signdocs.TransactionPurposeDocumentSignature,
    Policy:  signdocs.Policy{Profile: signdocs.PolicyProfileClickOnly},
    Signer: signdocs.Signer{
        Name:           "João Silva",
        Email:          "joao@example.com",
        UserExternalID: "user-001",
    },
    Document: &signdocs.DocumentInline{
        Content:  documentBase64,
        Filename: "contrato.pdf",
    },
})
if err != nil {
    log.Fatal(err)
}
fmt.Println(tx.TransactionID, tx.Status) // DOCUMENT_UPLOADED

CreateTransactionRequest request = new CreateTransactionRequest();
request.purpose = "DOCUMENT_SIGNATURE";
request.policy = new Policy("CLICK_ONLY");
request.signer = new Signer("João Silva", "joao@example.com", "user-001");
request.document = new CreateTransactionRequest.InlineDocument(documentBase64, "contrato.pdf");

Transaction tx = client.transactions().create(request);
System.out.println(tx.transactionId + " " + tx.status); // DOCUMENT_UPLOADED

use SignDocsBrasil\Api\Models\CreateTransactionRequest;
use SignDocsBrasil\Api\Models\Policy;
use SignDocsBrasil\Api\Models\Signer;

$tx = $client->transactions->create(new CreateTransactionRequest(
    purpose: 'DOCUMENT_SIGNATURE',
    policy: new Policy(profile: 'CLICK_ONLY'),
    signer: new Signer(
        name: 'João Silva',
        email: 'joao@example.com',
        userExternalId: 'user-001',
    ),
    document: ['content' => $documentBase64, 'filename' => 'contrato.pdf'],
));
echo $tx->transactionId . ' ' . $tx->status; // DOCUMENT_UPLOADED

using SignDocsBrasil.Api.Models;

var tx = await client.Transactions.CreateAsync(new CreateTransactionRequest
{
    Purpose = "DOCUMENT_SIGNATURE",
    Policy = new Policy { Profile = "CLICK_ONLY" },
    Signer = new Signer
    {
        Name = "João Silva",
        Email = "joao@example.com",
        UserExternalId = "user-001",
    },
    Document = new InlineDocument
    {
        Content = documentBase64,
        Filename = "contrato.pdf",
    },
});
Console.WriteLine($"{tx.TransactionId} {tx.Status}"); // DOCUMENT_UPLOADED

Passo 2: Listar etapas

A transação CLICK_ONLY gera uma única etapa CLICK_ACCEPT com status PENDING.

const steps = await client.steps.list(tx.transactionId);
const clickStep = steps[0];
console.log(clickStep.type);   // CLICK_ACCEPT
console.log(clickStep.status); // PENDING

steps = client.steps.list(tx.transaction_id)
click_step = steps[0]
print(click_step.type)    # CLICK_ACCEPT
print(click_step.status)  # PENDING

steps, err := client.Steps.List(ctx, tx.TransactionID)
if err != nil {
    log.Fatal(err)
}
clickStep := steps[0]
fmt.Println(clickStep.Type)   // CLICK_ACCEPT
fmt.Println(clickStep.Status) // PENDING

List<Step> steps = client.steps().list(tx.transactionId);
Step clickStep = steps.get(0);
System.out.println(clickStep.type);   // CLICK_ACCEPT
System.out.println(clickStep.status); // PENDING

$steps = $client->steps->list($tx->transactionId);
$clickStep = $steps[0];
echo $clickStep->type;   // CLICK_ACCEPT
echo $clickStep->status; // PENDING

var steps = await client.Steps.ListAsync(tx.TransactionId);
var clickStep = steps[0];
Console.WriteLine(clickStep.Type);   // CLICK_ACCEPT
Console.WriteLine(clickStep.Status); // PENDING

Passo 3: Iniciar etapa CLICK_ACCEPT

const startResp = await client.steps.start(tx.transactionId, clickStep.stepId);
console.log(startResp.status); // STARTED

start_resp = client.steps.start(tx.transaction_id, click_step.step_id)
print(start_resp.status)  # STARTED

startResp, err := client.Steps.Start(ctx, tx.TransactionID, clickStep.StepID, nil)
if err != nil {
    log.Fatal(err)
}
fmt.Println(startResp.Status) // STARTED

StartStepResponse startResp = client.steps().start(tx.transactionId, clickStep.stepId);
System.out.println(startResp.status); // STARTED

$startResp = $client->steps->start($tx->transactionId, $clickStep->stepId);
echo $startResp->status; // STARTED

var startResp = await client.Steps.StartAsync(tx.TransactionId, clickStep.StepId);
Console.WriteLine(startResp.Status); // STARTED

Passo 4: Completar etapa CLICK_ACCEPT

O signatário aceita o documento enviando accepted: true.

const completed = await client.steps.complete(tx.transactionId, clickStep.stepId, {
  accepted: true,
});
console.log(completed.status); // COMPLETED

from signdocs_brasil.models import CompleteClickRequest

completed = client.steps.complete(
    tx.transaction_id,
    click_step.step_id,
    CompleteClickRequest(accepted=True),
)
print(completed.status)  # COMPLETED

completed, err := client.Steps.Complete(ctx, tx.TransactionID, clickStep.StepID,
    &signdocs.CompleteClickRequest{Accepted: true},
)
if err != nil {
    log.Fatal(err)
}
fmt.Println(completed.Status) // COMPLETED

Step completed = client.steps().complete(tx.transactionId, clickStep.stepId,
    Map.of("accepted", true));
System.out.println(completed.status); // COMPLETED

$completed = $client->steps->complete($tx->transactionId, $clickStep->stepId, [
    'accepted' => true,
]);
echo $completed->status; // COMPLETED

var completed = await client.Steps.CompleteAsync(tx.TransactionId, clickStep.StepId,
    new { Accepted = true });
Console.WriteLine(completed.Status); // COMPLETED

Passo 5: Finalizar transação

Após todas as etapas concluídas, finalize a transação. O status muda para COMPLETED.

const finalized = await client.transactions.finalize(tx.transactionId);
console.log(finalized.status); // COMPLETED

finalized = client.transactions.finalize(tx.transaction_id)
print(finalized.status)  # COMPLETED

finalized, err := client.Transactions.Finalize(ctx, tx.TransactionID)
if err != nil {
    log.Fatal(err)
}
fmt.Println(finalized.Status) // COMPLETED

Transaction finalized = client.transactions().finalize(tx.transactionId);
System.out.println(finalized.status); // COMPLETED

$finalized = $client->transactions->finalize($tx->transactionId);
echo $finalized->status; // COMPLETED

var finalized = await client.Transactions.FinalizeAsync(tx.TransactionId);
Console.WriteLine(finalized.Status); // COMPLETED

Passo 6: Obter evidências

O pacote de evidências contém todas as informações da operação: signatário, etapas, resultados e hash do documento.

const evidence = await client.evidence.get(tx.transactionId);
console.log(evidence.evidenceId);
console.log(evidence.signer.name);
console.log(evidence.steps.map(s => s.type)); // ['CLICK_ACCEPT']

evidence = client.evidence.get(tx.transaction_id)
print(evidence.evidence_id)
print(evidence.signer.name)

evidence, err := client.Evidence.Get(ctx, tx.TransactionID)
if err != nil {
    log.Fatal(err)
}
fmt.Println(evidence.EvidenceID)
fmt.Println(evidence.Signer.Name)

Evidence evidence = client.evidence().get(tx.transactionId);
System.out.println(evidence.evidenceId);
System.out.println(evidence.signer.name);

$evidence = $client->evidence->get($tx->transactionId);
echo $evidence->evidenceId;
echo $evidence->signer['name'];

var evidence = await client.Evidence.GetAsync(tx.TransactionId);
Console.WriteLine(evidence.EvidenceId);
Console.WriteLine(evidence.Signer.Name);

Passo 7: Download do documento assinado

Obtém uma URL pré-assinada para download do documento com assinaturas embutidas.

const download = await client.documents.download(tx.transactionId);
console.log(download.downloadUrl);
console.log(download.filename);
// Use a URL para baixar o arquivo (expira em poucos minutos)

download = client.documents.download(tx.transaction_id)
print(download.download_url)
print(download.filename)

download, err := client.Documents.Download(ctx, tx.TransactionID)
if err != nil {
    log.Fatal(err)
}
fmt.Println(download.DownloadURL)
fmt.Println(download.Filename)

DownloadResponse download = client.documents().download(tx.transactionId);
System.out.println(download.downloadUrl);
System.out.println(download.filename);

$download = $client->documents->download($tx->transactionId);
echo $download->downloadUrl;
echo $download->filename;

var download = await client.Documents.DownloadAsync(tx.TransactionId);
Console.WriteLine(download.DownloadUrl);
Console.WriteLine(download.Filename);

Resumo do fluxo

Criar transação (CLICK_ONLY + documento)
    │
    ▼
Listar etapas → [CLICK_ACCEPT]
    │
    ▼
Iniciar CLICK_ACCEPT
    │
    ▼
Completar CLICK_ACCEPT (accepted: true)
    │
    ▼
Finalizar transação
    │
    ▼
Obter evidências / Download documento