> ## Documentation Index
> Fetch the complete documentation index at: https://docs.dokstamp.com/llms.txt
> Use this file to discover all available pages before exploring further.

# Fluxo de Assinatura de Documentos

> Como funciona o fluxo de assinatura tripartite — assinantes externos e certificados digitais institucionais.

# 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).

```bash theme={null}
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

```bash theme={null}
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

```bash theme={null}
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"]
  }'
```

<Warning>
  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.
</Warning>

***

### 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).

```bash theme={null}
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.

```bash theme={null}
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:

```bash theme={null}
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:

```json theme={null}
{
  "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:

```bash theme={null}
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

```bash theme={null}
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:

```bash theme={null}
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"
```