Definir grupos de signatários

Grupos de signatários permitem definir diferentes conjuntos de pessoas que devem assinar um documento, com possibilidade de configurar uma ordem de assinatura entre os grupos. A definição de grupos agora é feita diretamente no payload do endpoint de criação de documentos, sem necessidade de chamadas adicionais. Como configurar grupos de signatários no payload de criação de documento Utilize os seguintes campos para configurar os grupos e a ordem de assinatura:

• signature_order_active : define se a ordem de assinatura será sequencial (true para ativar).

• order_group : número que representa a ordem de assinatura do grupo (ex: 1, 2, 3...).

Criar grupos de signatários

POST https://api.zapsign.com.br/api/v1/doc/

Name	Type	Description
Authorization*	string	Api token a frente do texto "Bearer". Ex: Bearer c7f35c84-7893-4087-b4fb-d1f06c23

Body

Name	Type	Description
name	string	Nome do documento
url_pdf	string	URL do PDF a ser assinado
external_id	string	ID externo para controle do cliente
signers	Array	Lista de signatários
send_automatic	boolean	Envia automaticamente após a criação
lang	string	Idioma do fluxo (pt, en, es, ...)
disable_signer_emails	boolean	Desativa o envio de e-mails aos signatários
brand_logo	string	URL do logotipo personalizado (opcional)
brand_primary_color	string	Cor principal personalizada (ex: #000000)
brand_name	string	Nome da marca exibido
created_by	string	E-mail de quem criou o documento
date_limit_to_sign	string (ISO8601)	Data limite para assinatura (YYYY-MM-DDTHH:mm:ssZ)
signature_order_active	boolean	Define se há ordem de assinatura entre grupos
observers	Array	Lista de e-mails de observadores
reminder_every_n_days	number	Envia lembrete a cada N dias (opcional)
allow_refuse_signature	boolean	Permite recusar assinatura
disable_signers_get_original_file	boolean	Impede que signatários acessem o PDF final

Propriedades de signers

Name	Type	Description
name	string	Nome do signatário
email	string	E-mail do signatário
auth_mode	string	Modo de autenticação (ex: assinaturaTela)
order_group	number	Número do grupo sequencial. Grupos com mesmo número assinam juntos
custom_message	string	Mensagem personalizada que será enviada ao signatário no corpo do e-mail
phone_country	string	Código do país do telefone (ex: "55")
phone_number	string	Número do telefone
require_cpf	boolean	Define se o CPF será obrigatório
cpf	string	CPF do signatário
send_automatic_email	boolean	Envia automaticamente e-mail de assinatura
send_automatic_whatsapp	boolean	Envia automaticamente WhatsApp (se suportado)
lock_email	boolean	Bloqueia edição do e-mail na interface do signatário

Exemplo de payload:

// Grupo 1: Signatário 1, Signatário 2
// Grupo 2: Signatário 3

{
  "name": "Contrato Teste",
  "url_pdf": "https://zapsign.s3.amazonaws.com/exemplo.pdf",
  "external_id": "TESTE_CENARIO_A",
  "signers": [
    {
      "name": "Signatário 1",
      "email": "[email protected]",
      "auth_mode": "assinaturaTela",
      "order_group": 1,
      "custom_message": "Você é o primeiro do grupo. Assine assim que possível.",
      "phone_country": "55",
      "phone_number": "11999999999",
      "require_cpf": true,
      "cpf": "12345678900",
      "send_automatic_email": true,
      "send_automatic_whatsapp": false,
      "lock_email": false
    },
    {
      "name": "Signatário 2",
      "email": "[email protected]",
      "auth_mode": "assinaturaTela",
      "order_group": 1,
      "custom_message": "Você está junto com o Signatário 1. Assine quando puder.",
      "phone_country": "55",
      "phone_number": "11888888888",
      "require_cpf": true,
      "cpf": "66778899001",
      "send_automatic_email": true,
      "send_automatic_whatsapp": false,
      "lock_email": false
    },
    {
      "name": "Signatário 3",
      "email": "[email protected]",
      "auth_mode": "assinaturaTela",
      "order_group": 2,
      "custom_message": "Assine apenas após os dois primeiros signatários completarem.",
      "phone_country": "55",
      "phone_number": "11777777777",
      "require_cpf": true,
      "cpf": "99887766554",
      "send_automatic_email": true,
      "send_automatic_whatsapp": false,
      "lock_email": false
    }
  ],
  "send_automatic": true,
  "lang": "pt",
  "disable_signer_emails": false,
  "brand_logo": "",
  "brand_primary_color": "#000000",
  "brand_name": "Minha Empresa",
  "created_by": "[email protected]",
  "date_limit_to_sign": "2025-12-31T23:59:59Z",
  "signature_order_active": true,
  "observers": ["[email protected]"],
  "reminder_every_n_days": 3,
  "allow_refuse_signature": true,
  "disable_signers_get_original_file": false
}

Respostas

200 OK

{
    "message": "OK"
}

400 Bad Request

Exemplos de erros:

• Quando a numeração dos grupos não for contínua:

{
    "message": "A numeração dos grupos deve ser contínua. Valores esperados: [0, 1, 2], valores fornecidos: [0, 2, 3]"
}

• Quando os grupos não começarem pelo valor 0:

{
    "message": "A ordem dos grupos de signatários deve começar por 0. Primeiro grupo encontrado: 1"
}

• Quando faltarem signatários do documento a serem associados a algum grupo:

{
    "message": "Há signatários neste documento que não foram incluídos em nenhum grupo."
}