> For the complete documentation index, see [llms.txt](https://devcenter.unico.io/unico-sign/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://devcenter.unico.io/unico-sign/guia-das-apis/assinatura-em-massa.md). # Assinatura em Massa ## Assinatura em massa ### Sobre este guia Através deste guia, demonstraremos como configurar a assinatura em massa (também chamada de assinatura em lote) através de nossas APIs REST. Ao seguir os passos deste guia, em poucos minutos você será capaz de: * Indicar, na criação do envelope, qual assinante irá assinar em massa; * Conferir se o assinante foi efetivamente registrado como assinante em massa; * Habilitar um contato para ser indicado como assinante em massa também pelo nosso painel. {% hint style="warning" %} Vale ressaltar que esta funcionalidade somente está disponível para clientes do **Unico People** {% endhint %} Este fluxo utiliza os seguintes endpoints de nossa API REST: | Endpoint | Papel neste fluxo | | ------------------------- | --------------------------------------------------------------------------- | | `POST /service/envelope` | Indica qual assinante do envelope irá assinar em massa | | `POST /service/envelopes` | Confere como o assinante foi registrado | | `POST /service/contact` | Habilita (ou desabilita) o contato para ser indicado pelo painel — opcional | A URL base utilizada nos exemplos deste guia é: ``` https://sign.hr.uat.unico.app/ ``` ### O que você vai precisar Antes de iniciar sua integração: 1. Certifique-se que você possui credenciais válidas para utilizar o Unico Sign; 2. Gere um token de acesso válido. Todas as rotas deste guia são autenticadas: envie o token no cabeçalho `Authorization: Bearer {{ACCESS_TOKEN}}` de cada requisição; 3. Certifique-se que o usuário utilizado na integração possui as permissões das rotas que você for chamar, listadas abaixo; 4. Entenda como criar envelopes, já que a assinatura em massa é configurada durante a criação de um envelope. #### Permissões por rota | Rota | Permissão necessária | | ------------------------- | -------------------------------------- | | `POST /service/envelope` | Enviar Documentos (`senddocument`) | | `POST /service/envelopes` | Visualizar Documentos (`viewdocument`) | | `POST /service/contact` | Administrar Contatos (`admcontact`) | Um token sem a permissão correspondente recebe `403 Forbidden`. > **Conceda apenas o que for usar** > > A permissão de Administrar Contatos só é necessária para o passo opcional de habilitar o contato para o painel. Uma integração que apenas cria envelopes não precisa dela. ### Funcionamento básico Normalmente, um assinante precisa abrir e assinar cada envelope individualmente. Com a assinatura em massa, ele assina de uma só vez, em uma única sessão, todos os envelopes pendentes em que foi indicado como assinante em massa. É o caso típico de um gestor, representante legal ou responsável de RH que recebe um grande volume de documentos destinados a diferentes pessoas — por exemplo, uma empresa que envia holerites para centenas de colaboradores e precisa que o mesmo gestor assine todos eles. Pela API, a configuração é feita em um único lugar: a indicação no assinante do envelope (`IsBatchSigner`), que define que, naquele envelope, aquela pessoa irá assinar em massa. Não é necessário nenhum cadastro prévio. > **E a permissão do contato (`AllowBatchSigning`)?** > > O cadastro de contatos possui a permissão `AllowBatchSigning`, que habilita a pessoa a ser indicada como assinante em massa pelo nosso painel. Ela não é exigida na criação de envelopes pela API — quando o assinante é indicado com `IsBatchSigner`, ele é registrado como assinante em massa independentemente do contato. Veja a seção [Habilitando o contato para o painel](https://claude.ai/chat/902e7496-eb08-465b-93ca-c6f21fcf25fb#habilitando-o-contato-para-o-painel). #### Quais envelopes entram na sessão de assinatura em massa Ao acessar sua área de assinaturas, o assinante verá a opção de assinar em massa quando existir ao menos um envelope elegível. São elegíveis os envelopes que: * Indicaram aquela pessoa como assinante em massa (`IsBatchSigner`); * Estão com o status `1 - Pendente`; * Não estão expirados; * Não utilizam o fluxo de autenticação `1 - Código de acesso`. ### Passo a passo #### 1. Criando o envelope Na criação do envelope (`POST /service/envelope`), indique qual assinante irá assinar em massa através do campo `IsBatchSigner` dentro de `Subscribers`. | Parâmetro | Obrigatório | Descrição | | ------------------------ | --------------------------------- | ----------------------------------------------------------------------------------------------------------------------------------- | | `IsBatchSigner` | Não | Indica que o assinante é um signatário em massa. Booleano, assume `false` quando não enviado. | | `SubscriberRole` | Sim, quando `IsBatchSigner: true` | Função do assinante. O assinante em massa deve ser `2 - Representante legal` ou `3 - Testemunha`. | | `SubscriberCPF` | Sim, quando `IsBatchSigner: true` | CPF do assinante, sem formatação, apenas os 11 números. É o que reúne os envelopes daquela pessoa na sessão de assinatura em massa. | | `SubscriberOrganization` | Não | Empresa que o assinante representa legalmente. Informe quando o papel for `2 - Representante legal`. | > **Função e CPF são obrigatórios para o assinante em massa** > > Diferente dos demais assinantes, o assinante em massa exige `SubscriberRole` igual a `2 - Representante legal` ou `3 - Testemunha` e exige `SubscriberCPF` — inclusive quando o envelope utiliza o fluxo `5 - Sem CPF`. Requisições fora dessas regras são recusadas com `400 Bad Request`. Abaixo um exemplo de envelope com dois assinantes, onde o segundo é o assinante em massa: ```bash curl -X 'POST' \ 'https://sign.hr.uat.unico.app/api/v1/service/envelope' \ -H 'accept: application/json' \ -H 'Content-Type: application/json' \ -H 'Authorization: Bearer {{ACCESS_TOKEN}}' \ -d '{ "EnvelopeFlow": [ { "ID_Flow": 3 } ], "IsFrame": "false", "UrlCallback": "https://callback.com", "Documents": [ { "EmitterUserUUID": "", "EmitterUserName": "Nome do Emissor", "DocumentType": "Holerite - Janeiro", "FileBase64": "Base64File", "Subscribers": [ { "SubscriberName": "Colaborador Um", "SubscriberCPF": "12345678901", "SubscriberEmail": "colaborador@email.com", "SubscriberOrder": 1 }, { "SubscriberName": "Margaria Clara", "SubscriberCPF": "10000000019", "SubscriberEmail": "test@test.com", "SubscriberOrder": 2, "SubscriberRole": 2, "SubscriberOrganization": "Empresa Exemplo", "IsBatchSigner": true } ] } ] }' ``` **Regras validadas na criação do envelope** As regras a seguir recusam a requisição quando desrespeitadas: | Regra | Mensagem retornada | | ------------------------------------------------------------------------------------------------------------ | ------------------------------------------------------------------------------------------------------------------------- | | É permitido apenas um assinante em massa por documento | Não é permitido mais de um assinante em lote por documento | | Quando o documento é gerado a partir de um modelo (template), o assinante em massa não pode ser o de ordem 1 | Assinante em lote não pode ser o assinante de ordem 1 quando o documento é um modelo. | | O assinante em massa deve ser representante legal ou testemunha | O assinante em lote do documento: {DocumentType} deve ter o SubscriberRole "2 - Representante legal" ou "3 - Testemunha". | | O assinante em massa deve ter CPF | O assinante em lote do documento: {DocumentType} deve ter o SubscriberCPF informado. | A requisição recusada retorna `400 Bad Request` com a lista de erros encontrados: ```json { "errors": [ { "key": "IsBatchSigner", "message": "O assinante em lote do documento: Holerite - Janeiro deve ter o SubscriberRole \"2 - Representante legal\" ou \"3 - Testemunha\"." } ] } ``` > **Ordem do assinante em massa** > > Fora do caso do modelo (template), o assinante em massa pode estar em qualquer ordem. No modelo, a ordem 1 é reservada a quem preenche os campos do documento. **Quando o assinante em massa é registrado como assinante comum** Diferente das regras acima, as situações a seguir não recusam a requisição. O envelope é criado normalmente, porém `IsBatchSigner` volta a ser `false` e aquele assinante deverá assinar o envelope individualmente: | Situação | Motivo | | ------------------------------------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------- | | O envelope utiliza o fluxo `1 - Código de acesso` no `EnvelopeFlow` | A sessão de assinatura em massa autentica o assinante uma única vez, o que é incompatível com um código de acesso por envelope. | > **Demais fluxos de autenticação** > > Os fluxos `2 - Biometria` e `3 - Desenho da assinatura` são compatíveis com a assinatura em massa. No caso do desenho, a assinatura é desenhada uma única vez e aplicada a todos os envelopes da sessão. #### 2. Conferindo o resultado Como a situação da seção anterior não retorna erro, recomendamos conferir o resultado ao integrar pela primeira vez ou ao diagnosticar um caso em que a assinatura em massa não ficou disponível para o assinante. O campo `IsBatchSigner` é retornado nos assinantes na consulta de envelopes (`POST /service/envelopes`). Se ele voltar como `false` no assinante que você marcou, verifique se o `EnvelopeFlow` do envelope inclui o fluxo `1 - Código de acesso`. ### Habilitando o contato para o painel Este passo é opcional e não interfere na criação de envelopes pela API. Ele existe para quem também envia envelopes pelo nosso painel: lá, a opção de marcar alguém como assinante em massa só aparece para contatos com a permissão `AllowBatchSigning`. A permissão é concedida ao contato através do campo `AllowBatchSigning` do endpoint `POST /service/contact`. O mesmo endpoint atende os dois casos: quando o CPF informado ainda não existe, o contato é criado; quando já existe, o contato é atualizado. > **Permissão necessária** > > Esta rota exige que o usuário do token tenha a permissão de Administrar Contatos (`admcontact`). Ela não é exigida pelas demais rotas deste guia — se sua integração apenas cria envelopes, não conceda esta permissão. > **Contatos criados junto com o envelope** > > Quando o CPF do assinante em massa ainda não possui contato cadastrado, a criação do envelope registra o contato já com `AllowBatchSigning` habilitado — de modo que ele também fique disponível para indicação pelo painel, sem nenhuma chamada extra. > **Nota** > > Esta permissão também pode ser concedida pelo cadastro de contatos de nosso painel. Os dois caminhos configuram exatamente a mesma permissão. #### Parâmetros | Parâmetro | Obrigatório | Descrição | | ------------------- | ----------- | -------------------------------------------------------------------------------------------------------------------------------------------------------- | | `ContactName` | Sim | Nome do assinante. | | `ContactCPF` | Sim | CPF do assinante, sem formatação, apenas os 11 números. É a chave que identifica o contato. | | `ContactEmail` | Não | E-mail do assinante. | | `ContactPhone` | Não | Telefone do assinante com DDD, sem formatação e contendo apenas 10 ou 11 números. | | `ContactIdentifier` | Não | Campo livre, não único, para identificação do contato do lado do cliente. | | `TenantID` | Não | Identificador único da empresa. | | `Units` | Não | Identificadores únicos das unidades/filiais do contato. | | `AllowBatchSigning` | Não | Habilita o contato a assinar em massa. Quando omitido, um contato novo é criado sem a permissão e um contato já existente mantém a permissão que possui. | > **Não é possível alterar o CPF de um contato** > > O CPF é a chave do contato. Caso seja fornecido um CPF diferente, um novo contato será registrado em vez de o existente ser atualizado. #### Habilitando a assinatura em massa Envie `AllowBatchSigning` como `true`. Se o contato ainda não existir, ele será criado já com a permissão: ```bash curl -X 'POST' \ 'https://sign.hr.uat.unico.app/api/v1/service/contact' \ -H 'accept: application/json' \ -H 'Content-Type: application/json' \ -H 'Authorization: Bearer {{ACCESS_TOKEN}}' \ -d '{ "ContactName": "Margaria Clara", "ContactCPF": "10000000019", "ContactEmail": "test@test.com", "ContactPhone": "1192345678", "ContactIdentifier": "test-123-test", "AllowBatchSigning": true }' ``` Resposta em caso de sucesso — a mensagem indica qual operação foi realizada: ```json { "Success": true, "Message": "Contato inserido com sucesso" } ``` ```json { "Success": true, "Message": "Contato atualizado com sucesso" } ``` #### Desabilitando a assinatura em massa Para retirar a permissão de um contato existente, envie o mesmo CPF com `AllowBatchSigning` como `false`: ```json { "ContactName": "Margaria Clara", "ContactCPF": "10000000019", "AllowBatchSigning": false } ``` #### Atualizando apenas dados cadastrais Como `AllowBatchSigning` é opcional e a omissão preserva a permissão atual, você pode atualizar nome, e-mail ou telefone sem se preocupar em reenviar a permissão. O exemplo abaixo atualiza o telefone e mantém a permissão que o contato já possui, tenha ela sido concedida por API ou pelo painel: ```json { "ContactName": "Margaria Clara", "ContactCPF": "10000000019", "ContactPhone": "1198765432" } ``` > **Por que a omissão preserva a permissão** > > Integrações que utilizam esta rota apenas para manter dados cadastrais em sincronia não desabilitam, sem intenção, contatos que foram habilitados no painel. Para alterar a permissão, envie o campo explicitamente com `true` ou `false`. #### Erros comuns O endpoint retorna `400 Bad Request` com a lista de erros encontrados: ```json { "errors": [ { "key": "ContactCPF", "message": "CPF nulo ou vazio." } ] } ``` ```json { "errors": [ { "key": "ContactEmail", "message": "Email do contato não é válido." } ] } ``` ### Resumo das regras * Pela API, a indicação no envelope (`IsBatchSigner`) basta — a permissão do contato (`AllowBatchSigning`) não é exigida; * O assinante em massa deve ter `SubscriberRole` igual a `2 - Representante legal` ou `3 - Testemunha`; * O `SubscriberCPF` é obrigatório no assinante em massa, inclusive no fluxo `5 - Sem CPF`; * Apenas um assinante em massa por documento; * Em documentos gerados a partir de modelos (templates), o assinante em massa não pode ser o de ordem 1; * O fluxo `1 - Código de acesso` é incompatível com a assinatura em massa; * Entram na sessão de assinatura em massa os envelopes pendentes e não expirados; * `AllowBatchSigning` governa a indicação pelo painel; omiti-lo no `POST /service/contact` preserva a permissão de um contato existente.