Saltar para o conteúdo principal

​
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:
EndpointFinalidade
POST /documents/signatures/batch/resendReenviar 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"