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

# Definir lista de signatários

> Substitui completamente a lista de signatários do envelope. Use em vez de adicionar um a um.

Define a lista completa de signatários para o envelope. A operação **substitui** a lista anterior inteira (soft-deleta os antigos, insere os novos). Use quando quiser redefinir a fila de signatários no assistente.

**Autenticação**: `x-api-key` no header. Também aceita `Authorization: Bearer` com headers de projeto/organização.

## Parâmetros

<ParamField path="uuid" type="string" required>
  UUID do envelope rascunho.
</ParamField>

<ParamField body="signers" type="array" required>
  Array de signatários (mínimo 1). Cada item é um objeto com:

  * `cpf` (string, obrigatório) — CPF do signatário (com ou sem máscara).
  * `name` (string, obrigatório) — Nome completo.
  * `email` (string, obrigatório) — E-mail para convite e notificações.
  * `signatureType` (enum, obrigatório) — Tipo de assinatura: `MFA_EMAIL`, `MFA_SMS`, `LIVENESS`, `ICP_BRASIL`, `MFA_EMAIL_LIVENESS`, ou `MFA_SMS_LIVENESS`.
  * `qualification` (string, opcional) — Qualificação (ex.: "Contratante", "Testemunha").
  * `birthDate` (string, opcional) — Data de nascimento (formato AAAA-MM-DD).
  * `phoneCountryCode` (string, opcional) — Código de país do telefone (ex.: "55").
  * `phoneNumber` (string, opcional) — Número de celular (obrigatório se `signatureType` inclui `MFA_SMS`).
  * `queueOrder` (integer, opcional) — Posição na fila (apenas para `signingMode: sequential`).
</ParamField>

## Respostas

<ResponseField name="signers" type="array">
  Lista atualizada de signatários confirmados. Cada item contém: `signerUuid`, `cpf` (só dígitos), `name`, `email`, `signatureType`, `signatureTypeName`.
</ResponseField>

## Erros

Veja [Autenticação e erros](/plataforma/assinatura-digital/api/erros-e-autenticacao).

* **400**: Lista vazia, CPF duplicado na mesma lista (mensagem: `"O CPF X aparece mais de uma vez na lista."`), CPF/e-mail/data inválidos, ou tipo SMS sem `phoneNumber`.
* **404**: Envelope não encontrado ou não pertence ao seu projeto.
* **409**: Envelope não está em rascunho.

<ResponseExample>
  ```json theme={"theme":"catppuccin-latte"}
  HTTP/1.1 200 OK
  Content-Type: application/json

  {
    "signers": [
      {
        "signerUuid": "6ba7b810-9dad-11d1-80b4-00c04fd430c8",
        "cpf": "12345678901",
        "name": "João Silva",
        "email": "joao@empresa.com",
        "signatureType": "MFA_EMAIL",
        "signatureTypeName": "Verificação por e-mail"
      },
      {
        "signerUuid": "6ba7b811-9dad-11d1-80b4-00c04fd430c8",
        "cpf": "98765432109",
        "name": "Maria Santos",
        "email": "maria@empresa.com",
        "signatureType": "ICP_BRASIL",
        "signatureTypeName": "Certificado ICP-Brasil"
      }
    ]
  }
  ```

  ```json theme={"theme":"catppuccin-latte"}
  HTTP/1.1 400 Bad Request
  Content-Type: application/json

  {
    "statusCode": 400,
    "message": "O CPF 123.456.789-01 aparece mais de uma vez na lista."
  }
  ```
</ResponseExample>

## Exemplo

```bash theme={"theme":"catppuccin-latte"}
curl -X PUT "https://api.valid.com/signer/v1/envelopes/550e8400-e29b-41d4-a716-446655440000/signers" \
  -H "x-api-key: YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "signers": [
      {
        "cpf": "123.456.789-01",
        "name": "João Silva",
        "email": "joao@empresa.com",
        "signatureType": "MFA_EMAIL",
        "qualification": "Contratante"
      },
      {
        "cpf": "987.654.321-09",
        "name": "Maria Santos",
        "email": "maria@empresa.com",
        "signatureType": "ICP_BRASIL",
        "birthDate": "1990-05-15",
        "phoneCountryCode": "55",
        "phoneNumber": "11987654321"
      }
    ]
  }'
```

## Tipos de assinatura

| Tipo | Requisito | Caso de uso |
| :- | :- | :- |
| `MFA_EMAIL` | Verificação por código em e-mail | Rápido, sem certificado |
| `MFA_SMS` | Código por SMS (exige `phoneNumber`) | Verificação adicional |
| `LIVENESS` | Prova de vida (captura biométrica) | Anti-fraude, LOAs maiores |
| `ICP_BRASIL` | Certificado digital (local ou nuvem) | Conformidade regulatória, documentos legais |
| `MFA_EMAIL_LIVENESS` | Código e-mail + liveness | Combinado |
| `MFA_SMS_LIVENESS` | Código SMS + liveness | Combinado |

## Importante

* **Substitui completamente**: os signatários anteriores são substituídos (soft-deletados). Não é adição incremental.
* **CPF único**: o mesmo CPF não pode aparecer duas vezes na mesma lista.
* **Sem notificação ainda**: ninguém é convidado nesta etapa. Invites são disparados apenas em [`POST .../:uuid/send`](/plataforma/assinatura-digital/api/post-envelope-send).
* **Validação de e-mail**: e-mails são validados; inválidos retornam 400.

## Próximas etapas

1. Defina todos os signatários.
2. Chame [`POST .../:uuid/advance`](/plataforma/assinatura-digital/api/post-envelope-advance) para ir à conferência.
3. Depois, chame [`POST .../:uuid/send`](/plataforma/assinatura-digital/api/post-envelope-send) para enviar aos signatários.

## Relacionado

* [`POST .../:uuid/advance`](/plataforma/assinatura-digital/api/post-envelope-advance) — avançar para a conferência
* [`POST .../:uuid/send`](/plataforma/assinatura-digital/api/post-envelope-send) — enviar aos signatários
* [`PATCH .../:uuid/signers/:signerUuid`](/plataforma/assinatura-digital/api/patch-envelope-signer) — editar um signatário (após envio)


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