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 utilizando um certificado digital armazenado na plataforma.

Visão geral

Instituição                          Terceiro (Assinante)
     │                                       │
     │  1. Criar Tipo de Documento           │
     │  2. Carregar PDF (/files)             │
     │  3. Criar Documento                   │
     │  4. Registar Assinante                │
     │  5. Associar Assinante → Documento ──►│
     │                                       │  6. Assinante recebe email
     │                                       │  7. Assinante clica no link e assina
     │  8. Verificar estado da assinatura ◄──│
     │  9. Assinar institucionalmente (cert) │
     │ 10. Transferir 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 — Carregar o 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"

Guarde o uuid devolvido 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 mapeia-os posicionalmente para os campos configurados.

4 — Registar o Assinante

Os assinantes são terceiros que precisam de assinar o documento. São identificados por nome, email e CPF (número de identificação fiscal brasileiro).

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"
  }'

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

5 — Associar o Assinante ao Documento

Esta etapa associa o assinante e desencadeia 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 Estado da Assinatura

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

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 estado 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 a sua assinatura. false significa pendente.

7 — Assinar Institucionalmente

Após recolher 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 — Transferir 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. Partilhe o UUID com o assinante ou armazene o link no seu sistema.

Operações em lote

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

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

Ficheiros

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 — Carregar o PDF

3 — Criar o Documento

4 — Registar o Assinante

5 — Associar o Assinante ao Documento

6 — Verificar Estado da Assinatura

7 — Assinar Institucionalmente

8 — Transferir 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 — Carregar o PDF

​3 — Criar o Documento

​4 — Registar o Assinante

​5 — Associar o Assinante ao Documento

​6 — Verificar Estado da Assinatura

​7 — Assinar Institucionalmente

​8 — Transferir 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 — Carregar o PDF

3 — Criar o Documento

4 — Registar o Assinante

5 — Associar o Assinante ao Documento

6 — Verificar Estado da Assinatura

7 — Assinar Institucionalmente

8 — Transferir o PDF Assinado

Operações em lote

Reenviar solicitações de assinatura