Solicitando assinaturas

Sobre este guia

Através deste guia, demonstraremos como solicitar assinaturas eletrônicas de documentos através de nossas APIs REST. Ao seguir os passos deste guia, em poucos minutos você será capaz de:

• Solicitar assinaturas através da criação de envelopes;
• Obter envelopes já criados;

Este fluxo está disponível através de nosso endpoint para a criação de envelopes: POST/service/envelope

Documentos e envelopes

Os documentos para assinatura sempre estarão contidos dentro de envelopes. Entenda um pouco mais sobre envelopes em nosso guia de conceitos básicos.

O que você vai precisar

Antes de iniciar sua integração:

1. Certifique-se que você possui credenciais válidas para utilizaro Unico Sign. Se você ainda não possui suas credenciais, siga nosso guia de Primeiros Passos para configurar sua conta de teste e obter sua chaves de API.
2. Entenda os conceitos básicos sobre nosso produto. É extremamente importante que você entenda estes conceitos para fazer uma boa utilização das APIs do Unico Sign. Você pode encontrar nossos conceitos básicos neste guia.

Funcionamento básico

Como explicamos em nosso guia de conceitos básicos, Envelopes são uma representação virtual de envelopes onde documentos são enviados e armazenados na vida real. Este tipo de objeto agrupa todos os documentos (Documents) assim como seus assinantes (Subscribers).

Ao criar um envelope, os usuários que devem assinar o documento (Subscriber) serão notificados através de um email, SMS ou uma notificação do aplicativo Unico | You.

• Enviaremos uma notifiação por email quando o email do assinante for informado no momento do envio do envelope.
• Enviaremos uma notificações por SMS quando o número de telefone do assinante for informado no momento do envio do envelope.
• Enviaremos uma notifiação por push quando o assinante possua o aplicativo Unico | You instalado.

Um email será enviado quando: seja cadastrado o email do assinante no momento do envio do envelope. Um SMS Será enviado quando: SMS caso seja cadastrado o número de telefone do assinante no momento do envio de envelope. Uma notifiação será senSerá enviada a notificação para o Unico | You caso o assinante tenha o aplicativo instalado.

Caso as três opções sejam possíveis simultaneamente para um envelope, o email não será enviado, o assinante receberá apenas o SMS e a notificação no aplicativo.

info

• Um envelope deve conter pelo menos um documento.
• A quantidade de documentos em um envelope é ilimitada, no entando, o tamanho do envelope não pode exceder 20Mb.
• O tamanho de cada documento não pode exceder 10Mb.

Os elementos básicos para a criação de um Envelope são:

1. Informações do emissor (Emmiter);
2. Tipo de documento (Um PDF em base64 ou um template pré estabelecido);
3. Informações de quem irá assinar o documento (Subscriber);
4. Algumas informações adicionais, como por exemplo uma URL de callback;

Entenda a seguir, como montar requisições para nosso end-point de criação de envelopes com os elementos relacionados acima.

1. Definindo o emissor do envelope

   O emissor é o agente responsável pela criação do envelope e suas respectivas configurações. As seguintes informações do emissor são obrigatórias em sua requisição para a criação de um envelope:

   Parâmetro	Descrição
   EmitterUUID	Identificação única do emissor. Possui o seguinte formato de um UUID padrão. Caso não exista deve ser informado vazio no request ("EmitterUserUUID": "",)
   EmitterUserName	Nome completo do emissor do envelope. Esta informação é exibida para os assinantes do envelope. Não possui restrições formato ou tamanho
   EmitterEmail	E-mail do emissor. Esta informação é exibida para os assinantes do envelope.

   Exemplo:

   "Documents": [
           {
               
               ...
               "EmitterUserUUID": "",
               "EmitterUserName": "Nome do Emissor",
               ...
           }
   ]

2. Definindo o tipo de documento

   A criação de documentos em envelopes pode ser feita utilizando um template pré-estabelecido ou um documento PDF (convertido em base64). Entenda a seguir como utilizar ambos formatos em nossa API:

   Utilizando um arquivo PDF/Base64

   Para criar um documento através de um PDF, basta converter e enviar o arquivo PDF através de nossa API. Para isto, o conteúdo de seu arquivo PDF deverá ser enviado através do campo FileBase64, codificado em em Base64.

   Arquivos Base64

   Base64 é um método para codificação de dados para transferência na Internet (codificação MIME para transferência de conteúdo). É utilizado frequentemente para transmitir dados binários por meios de transmissão que lidam apenas com texto, como por exemplo para enviar arquivos anexos por e-mail ou API. Saiba mais neste link

   Abaixo um exemplo utilizando o campo FileBase64:

    "Documents": [
       {
           "EmitterUserUUID": "",
           "EmitterUserName": "Nome do Emissor",
           "DocumentType": "Nome do Documento",
           "FileBase64": "JVBERi0xLjMKJbrfrOAKMyAwIG9iago8......PgplbmRvYmoKMTEgMCBvYmoKPDwKL1R5cGUgL0ZvbnQKL0Jhc2VGb250IC9Db3Vy",
           "Subscribers": [
               {
                   "SubscriberName": "Assinante Um",
                   "SubscriberCPF": "12345678901",
                   "SubscriberEmail": "assinante@email.com",
                   "SubscriberPhone": "5511999999999",
                   "SubscriberOrder": 1,
                   "AuthCode": "CódigoDeAcessoWeb"
               }
           ]
       }
   ]
   Campos de templates

   Caso utilize um arquivo PDF codificado em Base64 para a criação de seu documento, os campos de template não devem ser preenchidos.

   Utilizando um modelo (template pré-definido)

   Templates representam modelos de documentos que normalmente são utilizados em casos de envios recorrentes, como por exemplo holerites ou folhas de ponto. Além disso, estes modelos podem conter formulários para que o assinante preencha informações relevantes no momento da assinatura do documento. Entenda como utilizar modelos (templates) em suas requisições:

   Para criar um documento através de um Template, basta informar seu UUID em sua requisição. Para isto, o UUID deverá ser enviado através do campo TemplateUUID”.

   Template UUID

   Por enquanto não disponibilizamos os UUID dos templates por API ou em nosso painel. Para obter o UUID do template desejado, entre em contato com nosso suporte técnico através de nossa central de ajuda.

   Caso o assinante necessite preencher algum campo do modelo, utilize o parâmetro TemplateFields informando os campos a serem preenchidos através dor de parâmetros FieldCode e FieldValue da seguinte forma:

   • O campo FieldCode deverá conter exatamente o mesmo nome especificado no template;
   • Caso deseje enviar o campo pré-preenchido no modelo, informe o valor desejado no parâmetro FieldValue correspondente ao campo;
   • Caso não deseje enviar o campo pré-preenchido no modelo:
     • Não envie o campo em questão em sua requisição;
     • Envie null no parâmetro FieldValue correspondente ao campo;

   No exemplo abaixo, o formulário viria com o nome de a idade pré-preenchidos e o campo CPF viria em branco para preenchimento. Todos os campos informados no parâmetro TemplateFields serão de preenchimento obrigatório.

   "Documents": [
           {
               "EmitterUserUUID": "",
               "EmitterUserName": "Nome do Emissor",
               "DocumentType": "Nome do Documento",
               "FileBase64": "Base64File",
               "UnitUUID": null,
               "TemplateUUID": "d610d146-d658-428c-9c63-2067807fb22a",
               "TemplateFields": [
                   {
                       "FieldCode": "nome",
                       "FieldValue": "João da Silva"
                   },
                   {
                       "FieldCode": "idade",
                       "FieldValue": 30
                   },
                   {
                       "FieldCode": "cpf",
                       "FieldValue": null
                   }
               ],
               "Subscribers": [...]
       ]           
   } 
   
   Múltiplos tipos de documentos

   Um envelope pode combinar documentos de ambos os tipos (PDF/Base64 e proveninentes de templates).

3. Definindo quem irá assinar os documentos

   O assinante é o agente final do envelope, ou seja, é quem irá realizar a assinatura, concluindo o envelope, ou o recusando. A configuração de assinantes deve respeitar as seguintes regras:

   • Os assinantes devem ser os mesmos em todos os documentos contidos no envelope;
   • Cada documento precisa ter no mínimo um assinante;
   • Cada documento pode possuir mais de 1 assinante;

   A ordem de em que as assinaturas serão solicitadas deverá respeitar as seguintes regras:

   Primeiro assinante

   Em documentos gerados através de um template o primeiro assinante sempre deverá ser indicado, pois é ele quem irá preencher os campos do documento.

   • Em documentos gerados através de um template, você deverá selecionar um dos assinantes para receber a notificação primeiro. Os demais assinantes receberão na ordem indicada.
   • Os assinantes podem possuir o mesmo número de ordem, isso fará com que eles recebam a notificação no mesmo momento.
   • Em documentos gerados através de um PDF, todos os assinantes serão notificados na ordem configurada na criação do envelope.
   Assinantes, documentos e envelopes

   É importante entender que assinantes pertencem ao documento e documentos pertencem ao envelope.

4. Configurações adicionais

   Disponibilizamos algumas configurações adicionais que podem ser utilizadas no momento da criação de um envelope:

   Parâmetro	Descrição
   IsFrame	Deve ser enviado como true caso você deseje que o assinante não receba as notificações, direcione o assinante para o fluxo de assinatura web usando a URL (parâmetro UrlFrameFull).
   UrlCallback	URL de callback onde enviaremos notificações após o envelope ser finalizado, ou seja, sempre que o status do envelope mudar para 2 - Concluído, 3 - Cancelado ou 5 - Recusado.
   EnvelopeFlow	Configuração do fluxo de autenticação do assintante do envelope. Entenda os valores disponíveis nesta tabela

   Parâmetro EnvelopeFlow

   Este parâmetro recebe um valor numérico que identifica o fluxo de autenticação do assintante do envelope:

   ID_Flow

   integer <int64> Define o fluxo de autenticação do assinante no envelope. 1 - Código, 2 - Biometria, 3 - Desenho da Assinatura

   {

   • "ID_Flow": 1

   }

   Abaixo descrição detalhada de cada domínio:

   Valor	Descrição
   1	Código de acesso: O assinante deverá digitar esse código juntamente com o CPF na hora de se autenticar para fazer sua assinatura. Esse código deve ser passado do emissor para o assinante de forma externa ao processo.
   2	Biometria: O assinante deverá tirar uma foto para provar que ele está assinando aqueles documentos.
   3	Desenho de assinatura: O assinante deverá desenhar sua assinatura na tela.
   5	Emissão sem CPF: Caso o emissor não saiba o CPF do assinante é possível enviar o envelope sem essa informação. Neste caso o emissor deve estar ciente que, com esta configuração, nenhuma verificação de compatibilidade do CPF é efetuada, ou seja, a assinatura é autenticada com sucesso utilizando qualquer CPF válido.

   IsFrame e notificações

   Caso o parametro IsFrame esteja ativo:

   • Os assinantes não irão receber nenhum tipo de notificação;
   • Não é possível reenviar os envelopes;

5. Juntando todas as peças

   Tudo que mostramos nos passos acima deverá compor o corpo de uma requisição para nossas APIs REST.

   Abaixo um exemplo juntando tudo que mostramos nos passos acima:

   
   {
       "EnvelopeFlow": [
           {
               "ID_Flow": 1
           },
           {
               "ID_Flow": 3
           }
       ],
       "IsFrame": "false",
       "UrlCallback": "https://callback.com",
       "Documents": [
           {
               "EmitterUserUUID": "",
               "EmitterUserName": "Nome do Emissor",
               "DocumentType": "Nome do Documento",
               "FileBase64": "Base64File",
               "UnitUUID": null,
               "TemplateUUID": "d610d146-d658-428c-9c63-2067807fb22a",
               "TemplateFields": [
                   {
                       "FieldCode": "Campo1",
                       "FieldValue": "teste"
                   },
                   {
                       "FieldCode": "Campo2",
                       "FieldValue": 0
                   },
                   {
                       "FieldCode": "Campo3",
                       "FieldValue": NULL
                   }
               ],
               "Subscribers": [
                   {
                       "SubscriberName": "Assinante Um",
                       "SubscriberCPF": "12345678901",
                       "SubscriberEmail": "assinante@email.com",
                       "SubscriberPhone": "5511999999999",
                       "SubscriberOrder": 1,
                       "AuthCode": "CódigoDeAcessoWeb"
                   }
               ]
           }
       ]
   }
   

6. Faça uma requisição para o endpoint /envelope/

   Após montar o corpo da requisição e gerar um token de acesso válido, faça uma requisição para o endpoint de criação de envelopes de nossa API REST (POST/service/envelope).

   Abaixo um exemplo da requisição:

   curl -X 'POST' \
     'https://sign-core-uat.acesso.io/api/v1/service/envelope' \
     -H 'accept: */*' \
     -H 'Content-Type: application/json' \
     -d '{
     "Documents": [
       {
         "Url": "string",
         "UrlVoucher": "string",
         "DocumentType": "string",
         "CreatedDate": "string",
         "ID_DocumentStatus": 0,
         "DocumentStatusName": "string",
         "ID_EnvelopeStatus": 0,
         "EnvelopeStatusName": "string",
         "EmitterUserName": "string",
         "EmitterUserUUID": "string",
         "EmitterUserEmail": "string",
         "CompanySocialName": "string",
         "UUID": "3fa85f64-5717-4562-b3fc-2c963f66afa6",
         "FileBase64": "string",
         "File": "string",
         "HasFile": true,
         "UnitUUID": "string",
         "Subscribers": [
           {
             "ID_Subscriber": 0,
             "SubscriberName": "string",
             "SubscriberCPF": "string",
             "SubscriberEmail": "string",
             "SubscriberPhone": "string",
             "SubscriberUUID": "string",
             "AuthCode": "string",
             "ID_SubscriberStatus": 0,
             "SubscriberStatus": "string",
             "SubscriberOrder": 0,
             "SubscriberRole": 0,
             "SubscriberOrganization": "string",
             "SubscriberAccess": [
               {
                 "ID_Event": 0,
                 "AccessDate": "2022-09-12T03:24:48.671Z",
                 "AccessSource": "string",
                 "EventDateTime": "string",
                 "GeoLocation": "string",
                 "GeoFormattedAddress": "string",
                 "IP": "string",
                 "LogicalPort": "string",
                 "UserGMT": "string",
                 "UserAgent": "string",
                 "UserUUID": "string",
                 "UserCPF": "string",
                 "JTI": "string",
                 "EventData": "string",
                 "EventDescription": "string",
                 "GeoLat": "string",
                 "GeoLong": "string"
               }
             ],
             "URLFrame": "string",
             "URLFrameFull": "string",
             "SignatureImage": "string",
             "EmailNotification": "string",
             "IsUser": true,
             "IsLast": true
           }
         ],
         "EnvelopeFlow": [
           {
             "ID_Flow": 0
           }
         ],
         "Audit": [
           {
             "ID_AuditEvent": 0,
             "UserName": "string",
             "EventDateTime": "string",
             "EventData": "string",
             "EventDescription": "string"
           }
         ],
         "IsTemplate": true,
         "ID_Template": 0,
         "TemplateUUID": "3fa85f64-5717-4562-b3fc-2c963f66afa6",
         "DocumentSubcategoryUUID": "string",
         "DocumentSubcategoryName": "string",
         "DocumentCategoryUUID": "string",
         "DocumentCategoryName": "string",
         "TemplateFields": [
           {
             "FieldCode": "string",
             "FieldValue": "string"
           }
         ],
         "HasTemplateFields": true
       }
     ],
     "IsFrame": true,
     "UrlCallback": "string",
     "EnvelopeFlow": [
       {
         "ID_Flow": 0
       }
     ],
     "TenantID": "string"
   }'
   

   Se tudo der certo em sua requisição, você receberá como respota:

   {
       "Success": true,
       "Message": "",
       "Data": {
           "CreatedDate": "14/05/2020 11:55",
           "ID_EnvelopeStatus": 1,
           "EnvelopeStatus": "Pendente",
           "UUID": "x11x111x-x11x-1111-11x1-11x111x1xx1x",
           "Documents": [
               {
                   "Url": "https://signhom.acesso.io/api/v1/service/file/y00y000y-y00y-0000-00y0-00y000y0yy00",
                   "DocumentType": "Nome do Documento",
                   "CreatedDate": "14/05/2020 11:55",
                   "EmitterUserName": "Nome do Emissor",
                   "UUID": "y00y000y-y00y-0000-00y0-00y000y0yy00",
                   "IsTemplate": false
               }
           ]
       }
   }
   

Próximos passos

• Conheça outras funcionalidades disponíveis para o Gerenciamento de documentos.
• Conheça outras funcionalidades disponíveis para o Gerenciamento de envelopes.
• Tendo problemas em nossa integração? Acesse nossa sessão de FAQ e problemas comuns.
• Explore a documentacão da API do Unico Sign em nosso API Reference.

Ficou com dúvidas?

Esperamos ter ajudado com este artigo. Não encontrou algo ou ainda precisa de ajuda?

• Caso tenha dúvidas que não estejam relacionadas as nossas APIs, acesse nossa central de ajuda.
• Caso já seja um parceiro, entre em contato através de nosso portal de solicitações.