# Solicitando assinaturas ## Sobre este guia[​](https://developers.unico.io/docs/sign/api-guides/envelope#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`. {% hint style="info" %} **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. {% endhint %} ## O que você vai precisar[​](https://developers.unico.io/docs/sign/api-guides/envelope#o-que-voc%C3%AA-vai-precisar) Antes de iniciar sua integração: 1. Certifique-se que você possui credenciais válidas para utilizar o **Unico Sign**. Se você ainda não possui suas credenciais, siga nosso [guia de Primeiros Passos](https://devcenter.unico.io/unico-sign/primeiros-passos) para configurar sua conta de teste e obter suas 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](https://devcenter.unico.io/unico-sign/conceitos-basicos). ## Funcionamento básico[​](https://developers.unico.io/docs/sign/api-guides/envelope#funcionamento-b%C3%A1sico) Como explicamos em nosso [guia de conceitos básicos](https://devcenter.unico.io/unico-sign/conceitos-basicos), `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. {% hint style="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. {% endhint %} 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[​](https://developers.unico.io/docs/sign/api-guides/envelope#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: ```json "Documents": [ { ... "EmitterUserUUID": "", "EmitterUserName": "Nome do Emissor", ... } ] ``` ### 2. Definindo o tipo de documento[​](https://developers.unico.io/docs/sign/api-guides/envelope#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**[**​**](https://developers.unico.io/docs/sign/api-guides/envelope#utilizando-um-arquivo-pdfbase64) 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*. {% hint style="info" %} 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](https://developer.mozilla.org/en-US/docs/Glossary/Base64). {% endhint %} Abaixo um exemplo utilizando o campo `FileBase64`: {% code overflow="wrap" %} ```json "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" } ] } ] ``` {% endcode %} {% hint style="warning" %} Caso utilize um arquivo PDF codificado em *Base64* para a criação de seu documento, os campos de template **não** devem ser preenchidos. {% endhint %} **Utilizando um modelo (template pré-definido)**[**​**](https://developers.unico.io/docs/sign/api-guides/envelope#utilizando-um-modelo-template-pr%C3%A9-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”`. {% hint style="info" %} 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. {% endhint %} 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. ```json "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": [...] ] } ``` {% hint style="info" %} **Múltiplos tipos de documentos** Um envelope pode combinar documentos de ambos os tipos (PDF/Base64 e proveninentes de templates). {% endhint %} ### 3. Definindo quem irá assinar os documentos[​](https://developers.unico.io/docs/sign/api-guides/envelope#definindo-quem-ir%C3%A1-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: {% hint style="warning" %} **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. {% endhint %} * 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. {% hint style="success" %} **Assinantes, documentos e envelopes** É importante entender que assinantes pertencem ao documento e documentos pertencem ao envelope. {% endhint %} ### 4. Configurações adicionais[​](https://developers.unico.io/docs/sign/api-guides/envelope#configura%C3%A7%C3%B5es-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 assinante do envelope. Entenda os valores disponíveis na tabela abaixo. | **Parâmetro EnvelopeFlow**[**​**](https://developers.unico.io/docs/sign/api-guides/envelope#par%C3%A2metro-envelopeflow) Este parâmetro recebe um valor numérico que identifica o fluxo de autenticação do assintante do envelope: | ID\_Flow |

integer \

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

| | -------- | ------------------------------------------------------------------------------------------------------------------------------------------- | 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. | {% hint style="warning" %} **IsFrame e Notificações** Caso o parâmetro IsFrame esteja ativo: * Os assinantes não irão receber nenhum tipo de notificação; * Não é possível reenviar os envelopes; {% endhint %} ### 5. Juntando todas as peças[​](https://developers.unico.io/docs/sign/api-guides/envelope#juntando-todas-as-pe%C3%A7as) 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: ```json { "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/`[​](https://developers.unico.io/docs/sign/api-guides/envelope#fa%C3%A7a-uma-requisi%C3%A7%C3%A3o-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: ```json curl -X 'POST' \ 'https://signhom.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 resposta: {% code overflow="wrap" %} ```json { "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 } ] } } ``` {% endcode %} ## Próximos passos[​](https://developers.unico.io/docs/sign/fundamentals#pr%C3%B3ximos-passos) * Conheça as funcionalidades disponíveis para o [Gerenciamento de documentos](https://devcenter.unico.io/unico-sign/guia-das-apis/gerenciando-documentos). * Conheça as funcionalidades disponíveis para o [Gerenciamento de envelopes](https://devcenter.unico.io/unico-sign/guia-das-apis/gerenciando-envelopes). * Tendo problemas em nossa integração? Acesse nossa seção de [FAQ e problemas comuns](https://devcenter.unico.io/unico-sign/recursos-adicionais/faq). *** **Dúvidas?**[**​**](https://developers.unico.io/docs/IDunico/Integracao/primeirosPassos#d%C3%BAvidas) Não encontrou algo ou ainda precisa de ajuda? Se já é um cliente ou parceiro, pode entrar em contato através da [Central de Ajuda](https://empresas.unico.io/hc/pt-br/p/atendimentoparaempresas). --- # Agent Instructions: Querying This Documentation If you need additional information that is not directly available in this page, you can query the documentation dynamically by asking a question. Perform an HTTP GET request on the current page URL with the `ask` query parameter: ``` GET https://devcenter.unico.io/unico-sign/guia-das-apis/solicitando-assinaturas.md?ask= ``` The question should be specific, self-contained, and written in natural language. The response will contain a direct answer to the question and relevant excerpts and sources from the documentation. Use this mechanism when the answer is not explicitly present in the current page, you need clarification or additional context, or you want to retrieve related documentation sections.