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

# Criar assinatura incremental

> Cria e envia, em uma única chamada, a assinatura de PDFs que já chegam assinados, sem alterar o arquivo recebido.

Recebe um ou mais PDFs que já contêm assinaturas digitais, mais os signatários novos, e já envia o pedido de assinatura. Cada assinatura nova entra como revisão no fim do arquivo, e as assinaturas que já estavam dentro continuam válidas. Veja [Assinatura incremental](https://docs-platform.services-valid.com.br/plataforma/assinatura-digital/assinatura-incremental.md) para entender as regras.

Para montar o pedido em etapas, como numa tela de cadastro, use [`POST .../drafts`](https://docs-platform.services-valid.com.br/plataforma/assinatura-digital/api/post-incremental-draft).

## Parâmetros

**title** `string` *required*

Título da assinatura, ex.: `"CCB 2026-0001"`. Máximo 255 caracteres.

**dueDate** `string` *required*

Vencimento (ISO 8601). Precisa estar no futuro.

**reminderEveryHours** `number`

Frequência dos lembretes, em horas. Padrão: 24.

**signingMode** `enum`

`sequential` (na ordem da lista) ou `parallel` (todos ao mesmo tempo). Padrão: `parallel`.

**notificationChannel** `enum`

Por onde os signatários são avisados: `EMAIL`, `SMS` ou `NONE`. Com `EMAIL` ou `SMS` o portal envia o convite e os lembretes. Com `NONE` ninguém é avisado, os links voltam na resposta para você entregar, e `urlNotification` passa a ser obrigatória.

**urlNotification** `string`

URL HTTPS que recebe os eventos da assinatura (`SENT`, `SIGNED`, `REFUSED`, `FINISHED`, `CANCELLED` e `EXPIRED`). Obrigatória com `notificationChannel=NONE`.

**documents** `array` *required*

Os PDFs que já vêm assinados, ao menos um. Cada item:

* `filename` (string, obrigatório): nome do arquivo.
* `content` (string): o PDF em base64.
* `url` (string): URL de onde baixar o PDF.

Informe `content` ou `url`, não os dois.

**signers** `array` *required*

Os signatários novos. Cada item:

* `name` (string, obrigatório): nome completo.
* `email` (string, obrigatório): e-mail.
* `cpf` (string, obrigatório): CPF, com ou sem pontuação.
* `placementMode` (enum, obrigatório): `OPERATOR` ou `SIGNER`. Com `OPERATOR` você manda a posição da chancela agora, em `positions`. Com `SIGNER` o próprio signatário posiciona a chancela antes de assinar.
* `positions` (array): obrigatório com `OPERATOR`, uma posição para cada documento do pedido. Veja abaixo.
* `signatureType` (enum): `ICP_BRASIL`, `MFA_EMAIL`, `MFA_SMS`, `LIVENESS`, `MFA_EMAIL_LIVENESS` ou `MFA_SMS_LIVENESS`. Padrão: `ICP_BRASIL`.
* `qualification` (string): qualificação impressa na chancela, ex.: `"Tomador"`.
* `phoneCountryCode` (string): DDI, ex.: `"55"`.
* `phoneNumber` (string): celular com DDD. Obrigatório nos tipos por SMS.
* `queueOrder` (number): ordem na fila. Padrão: a posição na lista, a partir de 1.

### Cada item de `positions`

| Campo | Tipo | Descrição |
| :- | :- | :- |
| `documentIndex` | number, obrigatório | O documento, pelo índice em `documents`, a partir de 0. |
| `page` | number, obrigatório | Página, a partir de 1. |
| `left` | number, obrigatório | Distância da borda esquerda, na unidade de `unit`. |
| `top` | number, obrigatório | Distância da borda de `origin`, na unidade de `unit`. |
| `unit` | enum, obrigatório | `fraction`, `percent`, `px`, `pt`, `mm`, `cm` ou `in`. |
| `origin` | enum | `top-left` (padrão) ou `bottom-left`. |

## Respostas

**envelopeUuid** `string`

Identificador da assinatura incremental. Use-o em [`GET /signer/v1/envelopes/:uuid`](https://docs-platform.services-valid.com.br/plataforma/assinatura-digital/api/get-envelope-by-id).

**documents** `array`

Os documentos recebidos, na ordem do pedido. Cada item tem `index`, `filename` e `fileUuid`.

**signers** `array`

Os signatários, cada um com `signerUuid`, `email` e `signUrl`, o link da página de assinatura. Com `EMAIL` ou `SMS` o portal já enviou o link; com `NONE`, entregar é com você.

## Erros

Veja [Autenticação e erros](https://docs-platform.services-valid.com.br/plataforma/assinatura-digital/api/erros-e-autenticacao.md).

* **400**: Corpo inválido, vencimento no passado, posição faltando para algum documento, tipo de assinatura desconhecido ou PDF ilegível.
* **401**: Nem `x-api-key` nem `Authorization` válidos.
* **422**: O documento não aceita assinatura nova: certificado como "nenhuma alteração permitida" (DocMDP `/P 1`), protegido por senha ou com estrutura que impede a revisão incremental.

```json theme={"theme":"catppuccin-latte"}
HTTP/1.1 201 Created
Content-Type: application/json

{
  "envelopeUuid": "550e8400-e29b-41d4-a716-446655440000",
  "documents": [
    {
      "index": 0,
      "filename": "ccb-assinada-pela-credora.pdf",
      "fileUuid": "6ba7b810-9dad-11d1-80b4-00c04fd430c8"
    }
  ],
  "signers": [
    {
      "signerUuid": "6ba7b811-9dad-11d1-80b4-00c04fd430c8",
      "email": "maria@exemplo.com.br",
      "signUrl": "https://assinador.exemplo.com/envelopes/TOKEN"
    }
  ]
}
```

## Exemplo

```bash theme={"theme":"catppuccin-latte"}
curl -X POST "https://api.valid.com/signer/v1/incremental-signatures" \
  -H "x-api-key: YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "title": "CCB 2026-0001",
    "dueDate": "2026-12-31T23:59:59.000Z",
    "notificationChannel": "EMAIL",
    "documents": [
      { "filename": "ccb-assinada-pela-credora.pdf", "url": "https://exemplo.com/ccb.pdf" }
    ],
    "signers": [
      {
        "name": "Maria Souza",
        "email": "maria@exemplo.com.br",
        "cpf": "12345678909",
        "qualification": "Tomador",
        "placementMode": "OPERATOR",
        "positions": [
          { "documentIndex": 0, "page": 18, "left": 10, "top": 70, "unit": "percent" }
        ]
      },
      {
        "name": "João Lima",
        "email": "joao@exemplo.com.br",
        "cpf": "98765432100",
        "signatureType": "MFA_EMAIL",
        "placementMode": "SIGNER"
      }
    ]
  }'
```

## Importante

* **O arquivo recebido não muda.** Não há conversão para PDF/A nem página de manifesto.
* **Toda chancela precisa de lugar.** Com `OPERATOR`, mande uma posição para cada documento; com `SIGNER`, o signatário posiciona antes de assinar.
* **O portal assina no fim.** Quando o último signatário assina, o portal assina cada documento com o certificado do assinador, de forma invisível.

## Relacionado

* [Assinatura incremental](https://docs-platform.services-valid.com.br/plataforma/assinatura-digital/assinatura-incremental.md): regras e limitações
* [`POST .../drafts`](https://docs-platform.services-valid.com.br/plataforma/assinatura-digital/api/post-incremental-draft): criar em etapas
* [`GET /signer/v1/envelopes`](https://docs-platform.services-valid.com.br/plataforma/assinatura-digital/api/get-envelopes): listar, com `incremental=true`


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.