Fluxo de Assinatura de Documentos

O DokStamp suporta um fluxo de assinatura tripartite: um documento pode ser assinado por terceiros externos (via link por email) e/ou assinado institucionalmente usando um certificado digital armazenado na plataforma.

Visão geral

Instituição                          Terceiro (Assinante)
     │                                       │
     │  1. Criar Tipo de Documento           │
     │  2. Upload PDF (/files)               │
     │  3. Criar Documento                   │
     │  4. Cadastrar Assinante               │
     │  5. Vincular Assinante → Documento ──►│
     │                                       │  6. Assinante recebe email
     │                                       │  7. Assinante clica no link e assina
     │  8. Verificar status da assinatura ◄──│
     │  9. Assinar institucionalmente (cert) │
     │ 10. Baixar PDF assinado               │

Passo a passo

1 — Criar um Tipo de Documento

Os tipos de documento definem o template para uma categoria de documentos, incluindo os campos indexadores (campos de metadados para classificação).

curl -X POST https://api.dokstamp.com/document-types \
  -H "Authorization: Bearer {TOKEN}" \
  -H "X-Tenant: {TENANT}" \
  -H "Accept: application/json" \
  -H "Content-Type: application/json" \
  -d '{
    "description": "Service Agreement",
    "signed_by_third": true,
    "multiples_third_signers": false,
    "indexers": [
      { "indexer": "Client Name", "rule": "Outro" },
      { "indexer": "Client CPF",  "rule": "CPF" },
      { "indexer": "Client Email","rule": "E-mail" }
    ]
  }'

O array indexers define campos de metadados personalizados para documentos deste tipo. O campo rule valida a entrada: "Outro" (qualquer texto), "CPF" (CPF brasileiro), "E-mail" (endereço de email).

2 — Fazer Upload do PDF

curl -X POST https://api.dokstamp.com/files \
  -H "Authorization: Bearer {TOKEN}" \
  -H "X-Tenant: {TENANT}" \
  -H "Accept: application/json" \
  -F "files[]=@contract.pdf"

Salve o uuid retornado como file_uuid.

3 — Criar o Documento

curl -X POST https://api.dokstamp.com/documents \
  -H "Authorization: Bearer {TOKEN}" \
  -H "X-Tenant: {TENANT}" \
  -H "Accept: application/json" \
  -H "Content-Type: application/json" \
  -d '{
    "description": "Service Agreement — Acme Corp",
    "document_type_id": 1,
    "module_id": 2,
    "department_id": 3,
    "file_uuid": "{FILE_UUID}",
    "indexers": ["Acme Corp", "123.456.789-00", "contact@acme.com"]
  }'

Os valores do array indexers devem estar na mesma ordem dos indexadores definidos no Tipo de Documento. A API os mapeia posicionalmente para seus campos configurados.

4 — Cadastrar o Assinante

Assinantes são terceiros que precisam assinar o documento. Eles são identificados por nome, email e CPF.

curl -X POST https://api.dokstamp.com/signers \
  -H "Authorization: Bearer {TOKEN}" \
  -H "X-Tenant: {TENANT}" \
  -H "Accept: application/json" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "Carlos Oliveira",
    "document": "12345678900",
    "email": "carlos@acme.com"
  }'

Use GET /signers?where[user][email]=carlos@acme.com primeiro para evitar criar registros duplicados.

5 — Vincular o Assinante ao Documento

Esta etapa vincula o assinante e dispara automaticamente o email de solicitação de assinatura. Este endpoint é público — nenhum header Authorization é necessário.

curl -X POST https://api.dokstamp.com/documents/{doc_id}/signers/{signer_id}

O assinante recebe um email com um link seguro para visualizar e assinar o documento eletronicamente.

6 — Verificar Status da Assinatura

Consulte o endpoint de detalhe do documento para verificar se todas as assinaturas foram coletadas:

curl https://api.dokstamp.com/documents/{doc_id}?includes[signatures]=1 \
  -H "Authorization: Bearer {TOKEN}" \
  -H "X-Tenant: {TENANT}" \
  -H "Accept: application/json"

O array signatures na resposta mostra o status de cada assinante:

{
  "data": {
    "uuid": "d4e5f6a7-b8c9-0123-defg-234567890123",
    "description": "Service Agreement — Acme Corp",
    "signatures": [
      {
        "user": { "name": "Carlos Oliveira" },
        "signed": true
      }
    ]
  }
}

"signed": true significa que o assinante concluiu sua assinatura. false significa pendente.

Tipos de assinatura por parte

Enquanto o documento estiver em rascunho (draft), cada parte pode ter apenas as coordenadas da assinatura configuradas. O tipo de assinatura visível é escolhido pela parte no momento da assinatura.

Tipo	Valor	Descrição
Carimbo	`stamp`	Renderiza o carimbo digital DokStamp no estilo gov.br nas coordenadas da parte.
Imagem	`image`	Usa uma imagem enviada pela parte como assinatura visível nas coordenadas da parte.

Configurar coordenadas na criação ou atualização (somente em draft)

PATCH /v1/documents/{document_uuid}/parties/{party_uuid}
{
  "signature_coordinates": {
    "x": 30,
    "y": 400,
    "width": 250,
    "height": 52,
    "page": 2
  }
}

signature_type e signature_image_file_uuid não são aceitos neste endpoint.
A confirmação exige apenas que todas as partes tenham coordenadas válidas.

Escolher o tipo no momento da assinatura

A parte envia o tipo junto com o código de segurança no endpoint público de assinatura:

POST /v1/documents/sign?token={ACCESS_TOKEN}
Content-Type: multipart/form-data

security_token=ABC1234
signature_type=image
signature_image=@assinatura.png

Para carimbo (stamp), use application/json ou multipart/form-data sem o arquivo:

POST /v1/documents/sign?token={ACCESS_TOKEN}
Content-Type: application/json

{
  "security_token": "ABC1234",
  "signature_type": "stamp"
}

signature_type é obrigatório (stamp ou image).
signature_image é obrigatório quando signature_type é image (PNG, JPEG ou WebP).
signature_image não pode ser enviado quando signature_type é stamp.
O endpoint faz o upload da imagem internamente; não é necessário usar POST /files.

7 — Assinar Institucionalmente

Após coletar as assinaturas de terceiros, assine o documento com o certificado digital da instituição:

curl -X POST https://api.dokstamp.com/documents/{doc_id}/sign/{cert_id} \
  -H "Authorization: Bearer {TOKEN}" \
  -H "X-Tenant: {TENANT}" \
  -H "Accept: application/json" \
  -H "Content-Type: application/json" \
  -d '{ "pin": "123456" }'

O cert_id refere-se ao certificado digital institucional configurado na plataforma. O pin é o código de proteção PIN do certificado.

8 — Baixar o PDF Assinado

curl https://api.dokstamp.com/files/{file_uuid}/download \
  --output signed-contract.pdf

Este endpoint é público — sem necessidade de autenticação. Compartilhe o UUID com o assinante ou armazene o link no seu sistema.

Operações em lote

Para cenários de alto volume, endpoints de lote estão disponíveis:

Endpoint	Finalidade
`POST /documents/signatures/batch/resend`	Reenviar emails de solicitação de assinatura para múltiplos assinantes
`POST /documents/batch/sign/{cert_id}`	Assinar múltiplos documentos de uma vez com o certificado institucional

Reenviar solicitações de assinatura

Se um assinante não recebeu ou perdeu o email:

curl -X POST https://api.dokstamp.com/documents/{doc_id}/signers/{signer_id}/signatures/resend \
  -H "Authorization: Bearer {TOKEN}" \
  -H "X-Tenant: {TENANT}" \
  -H "Accept: application/json"

Primeiros Passos

Conceitos Fundamentais

Autenticação

Instituições

Organizações

Cursos

Módulos

Estudantes

Matrículas

Certificados

Modelos de Certificado

Arquivos

Guias

Guia de Integração

Fluxo de Assinatura de Documentos

Fluxo de Assinatura de Documentos

Visão geral

Passo a passo

1 — Criar um Tipo de Documento

2 — Fazer Upload do PDF

3 — Criar o Documento

4 — Cadastrar o Assinante

5 — Vincular o Assinante ao Documento

6 — Verificar Status da Assinatura

Tipos de assinatura por parte

Configurar coordenadas na criação ou atualização (somente em draft)

Escolher o tipo no momento da assinatura

7 — Assinar Institucionalmente

8 — Baixar o PDF Assinado

Operações em lote

Reenviar solicitações de assinatura

​Fluxo de Assinatura de Documentos

​Visão geral

​Passo a passo

​1 — Criar um Tipo de Documento

​2 — Fazer Upload do PDF

​3 — Criar o Documento

​4 — Cadastrar o Assinante

​5 — Vincular o Assinante ao Documento

​6 — Verificar Status da Assinatura

​Tipos de assinatura por parte

​Configurar coordenadas na criação ou atualização (somente em draft)

​Escolher o tipo no momento da assinatura

​7 — Assinar Institucionalmente

​8 — Baixar o PDF Assinado

​Operações em lote

​Reenviar solicitações de assinatura

Fluxo de Assinatura de Documentos

Visão geral

Passo a passo

1 — Criar um Tipo de Documento

2 — Fazer Upload do PDF

3 — Criar o Documento

4 — Cadastrar o Assinante

5 — Vincular o Assinante ao Documento

6 — Verificar Status da Assinatura

Tipos de assinatura por parte

Configurar coordenadas na criação ou atualização (somente em draft)

Escolher o tipo no momento da assinatura

7 — Assinar Institucionalmente

8 — Baixar o PDF Assinado

Operações em lote

Reenviar solicitações de assinatura