1 de 20

Unico Sign

Introdução

Sobre nós

O Unico Sign é o módulo de assinaturas da Unico. Com a gestão inteligente dos documentos, garante uma uma maneira simples, acessível e segura, a governança de documentos assinados digitalmente e permite que as pessoas formalizem transações e encontrem seus documentos armazenados, a qualquer hora, de forma rápida, segura, eficiente e descomplicada.

Através de uma experiência prática e fácil para quem assina e com autenticação através de biometria, o Unico Sign, permite mobilidade e gestão simples de documentos assinados com validade jurídica e garantia privacidade e segurança de ponta a ponta.

Quer saber mais sobre a Unico? Acesse nosso site!

O Unico Sign só é compatível com o produto Unico People.

O que você encontrará por aqui

Neste espaço, você encontrará tudo que necessita para construir sua integração com o unico | sign do zero. Aqui você encontrará todas as informações que necessita sobre nossa API REST, assim como guias de implementação e conceitos básicos, extramente importantes para o sucesso de sua integração.

Através de nossa API, em poucos passos você será capaz de:

Solicitar assinaturas eletronicas por e-mail ou SMS (Utilizando um arquivo PDF ou um Modelo);
Obter dados de templates preenchidos e assinados eletronicamente;
Efetuar a gestão dos documentos enviados para assinatura eletrônica;

Confira todas as possibilidades e casos de uso no guia de Visão Geral de nossas APIs.

Próximos passos

Hora de começar nossa jornada! A seguir recomendamos que você entenda um pouco mais sobre nossos conceitos básicos e logo em seguida navegue por nossos guias de integração.

Dúvidas?

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.

Primeiros passos

Entenda como configurar sua conta na Unico e deixar tudo pronto para efetuar suas primeiras requisições com a API REST do Unico Sign. Após estes passos, você estará pronto para iniciar sua integração com nossa API.

Crie sua conta com a Unico

O Unico Sign ainda não está disponível para todos nossos clientes. Caso tenha interesse, entre em contato conosco através de nossos canais de atendimento e solicite um convite.

Obtenha suas credenciais

Após a criação de sua conta na Unico, você deverá solicitar uma conta de serviço para sua aplicação. A conta de serviço deve ser solicitada diretamente ao GP ou CS responsável por sua integração.

Ao receber sua conta de serviço, você também receberá um arquivo (no formato .pem) contendo suas credenciais. O arquivo .pem será utilizado posteriormente no processo de autenticação das APIs.

É importante solicitar que o perfil Integradores seja adicionado a sua conta de serviço.

Teste sua integração

Sugerimos que você efetue um teste rápido com suas credenciais, para isto:

Obtenha um token OAuth válido

Para efetuar requisições a nossas APIs você necessitará de um token de acesso OAuth válido. Caso não esteja familizarizado com o modelo de autenticação OAuth, entenda como gerar um token válido neste artigo. Após sua geração, o token de acesso deverá ser enviado no header de sua requisição.

Ambientes

Ao iniciar sua integração você receberá credenciais a nosso ambiente de homologação. Sómente após o processo de testes e certificação você receberá credenciais de produção.

Você deverá apontar suas requisições às URLs corretas em cada estágio de sua integração. Abaixo listamos as URLs de homologação e produção:

Ambiente de homologação: https://signhom.acesso.io;
Ambiente de produção: https://sign.acesso.io.

Faça uma requisição básica a nossa API

Após obter um token de acesso válido, efetue uma requisição a um de nossos end-points e certifique-se que tudo está funcionando. Recomendamos um teste com o end-point que retorna os envelopes criados em sua conta. Abaixo um exemplo de como chamar este end-point:

curl --location --request POST '${URI}/api/v1/service/envelopes' \
--header 'accept: */*' \
--header 'Content-Type: application/json' \
--header 'Authorization: Bearer ${access_token}' \
--data-raw '{}'

Se tudo der certo, você deverá receber um código HTTP 200 e caso possua algum envelope criado em sua conta uma resposta semelhante a esta:

{
    "Success": true,
    "Message": "",
    "Data": {
        "Page": 1,
        "MaxPage": 363,
        "Count": 10886,
        "Envelopes": [
            {
                "CreatedDate": "21/05/2018 17:24",
                "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",
                        "UrlVoucher": "https://sign.acesso.io/api/v1/service/evidence/y00y000y-y00y-0000-00y0-00y000y0yy00",
                        "DocumentType": "Teste Core",
                        "CreatedDate": "21/05/2018 17:24",
                        "CompanySocialName": "ACESSO DIGITAL",
                        "UUID": "y00y000y-y00y-0000-00y0-00y000y0yy00",
                        "Subscribers": [
                            {
                                "SubscriberName": "Nome do Assinante Primeiro",
                                "SubscriberCPF": "11122233344",
                                "SubscriberEmail": "nome@email.com",
                                "SubscriberPhone": "5511999988888",
                                "SubscriberRole": 1,
                                "URLFrameFull": "https://url/client/?token=JymY0s0s0s0d0sa0d0sd0sa0dsa0d"
                            }
                        ]
                    }
                ]
            }
        ]
    }
}

Próximos passos

A seguir recomendamos que você entenda um pouco mais sobre nossos conceitos básicos e logo em seguida navegue por nossos guias de integração.

Dúvidas?

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.

Conceitos básicos

Sobre este guia

Nossa API utiliza uma série de conceitos e objetos como base para nossas funcionalidades. Este guia tem o objetivo de tornar familiar cada um desses conceitos para que você tenha um processo de integração totalmente fluido.

Ao explorar os conceitos deste guia, você será capaz de entender todo o fluxo de vida de um documento dentro do Unico Sign.

Conceitos básicos

Entenda abaixo alguns conceitos básicos e termos importantes para sua integração.

Envelope

A entidade Envelope é uma representação de um envelope com documentos na vida real. Ele é o objeto que agrupa todos os documentos(Document) e seus assinantes(Subscriber). 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.

Document

A entidade Document é a representação de um documento e pode ter duas formas:

O documento pode ser um arquivo pdf na forma de Base64 ou pode ser um modelo(Template) pré pronto.
Um documento pode conter um ou mais assinantes(Subscribers).

Em ambos os casos, o tamanho de cada documento não pode exceder 10Mb.

Subscriber

Subscriber é o assinante de um documento(Document). Todo assinante tem um tipo(SubscriberRole), sendo que existem três possíveis, são eles: Assinatura própria, Representante Legal ou Testemunha. Em cada envelope, o assinante pode ter apenas um dos três tipos. Segue abaixo a descrição de cada tipo.

Assinatura própria: é a assinatura do contratado.
Representante Legal: é a assinatura de uma pessoa que representa terceiros, sejam empresas ou outras pessoas.
Testemunha: é a assinatura da testemunha do documento.

Template

Template é um modelo de documento, normalmente utilizado em casos de envio de arquivos recorrentes, uma vez que pode ser reutilizado em vários envelopes. Um exemplo de uso é o envio de holerites ou folha de ponto. Além disso, modelos podem conter formulários, para que o assinante possa preencher ou ser preenchido pelo emissor com uma informação como, por exemplo, data da emissão ou assinatura, idade, nome dos pais, nome completo, opções sexuais, e qualquer coisa que precise ser preenchido em tempo de emissão ou assinatura.

Para criar um modelo é necessário acessar o Dashboard do Unico Sign, criar o modelo a partir de um arquivo pdf válido e configurar o seu formulário visualmente, caso seja necessário. A partir desse ponto, os modelos poderão ser utilizados na emissão via API.

Emitter

Emitter se trata do emissor do documento, ou seja o usuário que está realizando a criação do envelope. Caso o emissor precise também ser assinante do envelope, ele pode ser adicionado como assinante e terá o tipo de representante legal.

Evidências ou conjunto probatório

Conjunto formado pelas principais informações do envelope. Serve para comprovar juridicamente a conformidade e validade de um envelope, documento ou assinatura.

Próximos passos

Conheça as funcionalidades disponíveis para o Gerenciamento de documentos.
Conheça as funcionalidades disponíveis para o Gerenciamento de envelopes.
Tendo problemas em nossa integração? Acesse nossa seção de FAQ e problemas comuns.

Dúvidas?

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.

Guia das APIs

Visão Geral

A API Rest do Unico Sign oferece uma integração simples e rápida ao sistema de assinaturas da Unico. Nossa API utiliza requisições e respostas no formato JSON e possui um sistema de autenticação baseado em JWT Bearer.

Principais funcionalidades

Através de nossas APIs, você poderá gerenciar todo o fluxo de vida de um envelope, seus documentos e assinantes. Abaixo uma lista com as principais funcionalidades de nossa API.

Conceitos básicos

Se você ainda nao o fez, recomendamos explorar nosso guia de conceitos básicos.

Por lá, você entenderá no detalhe o que representa cada uma das entidades que comentaremos a seguir:

Criação de envelopes;
Criação de contatos;
Geração de evidências;
Listar documentos de um envelope;
Gerar PDFs de documentos em envelopes;
Gerar PDFs de documentos em envelopes.

Você poderá utilizar nossa API em um ambiente de homologação para testar nosas funcionalidades, evitando afetar seu entorno produtivo.

Casos de uso

A API Rest do Unico Sign possibilita a criação de uma ampla variedade de aplicações. Entenda alguns casos de uso:

Assinatura e gerenciamento de contratos de locação de imóvel;
Assinatura e gerenciamento de documentos de RH como folha de ponto e holerite;
Assinatura de contratos de prestação de serviços.

Próximos passos

Conheça as funcionalidades disponíveis para o Gerenciamento de documentos.
Conheça as funcionalidades disponíveis para o Gerenciamento de envelopes.
Tendo problemas em nossa integração? Acesse nossa seção de FAQ e problemas comuns.

Dúvidas?

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.

Autenticação

Sobre este guia

Através deste guia, explicaremos como gerar um Token de Acesso (AccessToken) em nossa plataforma de autenticação OAuth2, através de um JSON Web Token (JWT) assinado com SHA256withRSA. Ao seguir os passos deste guia, em poucos minutos você será capaz de ter tudo pronto para efetuar requisições para nossas APIs REST.

O que você vai precisar

Antes de iniciar sua integração:

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 para configurar sua conta de teste e obter suas chaves de API.
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

Para utilizar a API REST do Unico Sign, você deverá efetuar uma requisição ao nosso servidor de autenticação para obter um Token de Acesso válido.

Entenda, a seguir, como gerar manualmente seu JWT assinado e com ele obter um token de acesso válido:

Solicite uma conta de serviço

Para utilizar nossas APIs, você precisará solicitar a criação de uma conta de serviço ao gerente de projetos responsável por sua conta. Ao criar sua conta, enviaremos um e-mail contendo os dados necessários sua autenticação:

Nome de conta;
Identificador de sua empresa (Tenant ID);
ID da chave.

Todas as informações listadas acima serão utilizadas na geração de seu JWT nos passos abaixo.

Gere um JWT (JSON Web Token)

Para obter um Token de Acesso válido, você deverá enviar um JWT na requisição ao nosso servidor de autenticação. Este JWT é composto por três blocos (header, payload e assinatura) codificados, e separados pelo caractere . (ponto final).

Ao longo deste guia vamos destacar a cor de fundo do header, payload e assinatura para simplificar o entendimento.

Abaixo o detalhe de cada um dos blocos:

Header

O header para geração do JWT deverá conter os parâmetros alg (algorítimo de assinatura) e typ (tipo do token). Em nosso caso, sempre utilizaremos:

{
  "alg": "RS256",
  "typ": "JWT"
}

Após codificação em Base64URL: eyJhbGciOiJSUzI1NiIsInR5cCI6IkpXVCJ9

Payload

O payload para geração do JWT deverá conter os seguintes atributos:

Parâmetro

Descrição

iss

scope

Os escopos necessários para sua aplicação, separados pelo caractere +. Caso necessite todos os escopos utilize o caractere *.

aud

URI do serviço de autenticação. Utilize https://identityhomolog.acesso.io para o ambiente de homologação e https://identity.acesso.io para o ambiente de produção.

iat

exp

Exemplo de JSON:

{
  "iss": "service_account_name@tenant_id.iam.acesso.io",
  "aud": "https://identityhomolog.acesso.io",
  "scope": "*",
  "exp": 1626296976,
  "iat": 1626293376
}

Após codificação em Base64URL: eyJpc3MiOiJzZXJ2aWNlX2FjY291bnRfbmFtZUB0ZW5hbnRfaWQuaWFtLmFjZXNzby5pbyIsImF1ZCI6Imh0dHBzOi8vaWRlbnRpdHlob21vbG9nLmFjZXNzby5pbyIsInNjb3BlIjoiKiIsImV4cCI6MTYyNjI5Njk3NiwiaWF0IjoxNjI2MjkzMzc2fQ

Assinatura

Por último, vamos gerar a assinatura do JWT utilizando da chave privada enviada para o seu e-mail. A assinatura é o que permitirá que a Unico saiba que o JWT foi criado por sua aplicação.

As primeiras duas partes do JWT (gerada acima) deverão ser assinadas com a chave privada associada a sua conta de serviço, utilizando SHA256withRSA. Esse algoritmo primeiro calcula um hash exclusivo com os dados de entrada usando SHA256. O hash é então criptografado com uma chave privada usando o algoritmo RSA.

Existem inúmeras biblíotecas que podem te auxiliar a gerar esta assinatura. Você pode consultar algumas delas no site da ferramenta jwt.io.

O conteúdo de entrada para o cálculo da assinatura será: {Header em Base64url}.{Payload em Base64url}, exemplo utilizando o header e payload acima:

Exemplo de conteúdo enviado para assinatura:

eyJhbGciOiJSUzI1NiIsInR5cCI6IkpXVCJ9. eyJpc3MiOiJzZXJ2aWNlX2FjY291bnRfbmFtZUB0ZW5hbnRfaWQuaWFtLmFjZXNzby5pbyIsImF1ZCI6Imh0dHBzOi8vaWRlbnRpdHlob21vbG9nLmFjZXNzby5pbyIsInNjb3BlIjoiKiIsImV4cCI6MTYyNjI5Njk3NiwiaWF0IjoxNjI2MjkzMzc2fQ

Após sua geração, a assinatura deverá ser também codificada em Base64URL:

Exemplo de assinatura já codificada :

JsymP3NZdgCSqeNlgsOM2-AQ7M450NxFnZnnaKSu4Q8g12QGEIvvM4EhCokUHfwk5s7pOpm2UDNg3Hb5g_wgrjfiVSLWH5Q2wYg1AvfLqoYSoJWaMHm9KL0kpv32XdDD8TZVR-MVd2VBHmCMVbV6gvk8buUoK1HZDN7g84PaY3bfgcB3RKU-H55lR8yyJjZxToIv17-wfla2G99uaMEFNGX0ZSE7ETn5Z8-WypmFrNAK0TM58upzvfVI6-gY4cj4iQvmRbuvxsAaGiHA2xd0RVm2Mrx-gQtdPqtbZPuQcH7k64Z_EOQBgiGTgVjucyHD6zBijr_P-2mhIxuecNSw

Montando o JWT

Agora basta concatenar a assinatura codificada em Base64URL ao header e payload que foram utilizados para a assinatura: {Header em Base64url}.{Payload em Base64url}.{Assinatura em Base64url}. Abaixo um exemplo com o Header, Payload e assinatura utilizados acima:

Exemplo do JWT Assinado:

eyJhbGciOiJSUzI1NiIsInR5cCI6IkpXVCJ9.eyJpc3MiOiJzZXJ2aWNlX2FjY291bnRfbmFtZUB0ZW5hbnRfaWQuaWFtLmFjZXNzby5pbyIsImF1ZCI6Imh0dHBzOi8vaWRlbnRpdHlob21vbG9nLmFjZXNzby5pbyIsInNjb3BlIjoiKiIsImV4cCI6MTYyNjI5Njk3NiwiaWF0IjoxNjI2MjkzMzc2fQ. JsymP3NZdgCSqeNlgsOM2-AQ7M450NxFnZnnaKSu4Q8g12QGEIvvM4EhCokUHfwk5s7pOpm2UDNg3Hb5g_wgrjfiVSLWH5Q2wYg1AvfLqoYSoJWaMHm9KL0kpv32XdDD8TZVR-MVd2VBHmCMVbV6gvk8buUoK1HZDN7g84PaY3bfgcB3RKU-H55lR8yyJjZxToIv17-wfla2G99uaMEFNGX0ZSE7ETn5Z8-WypmFrNAK0TM58upzvfVI6-gY4cj4iQvmRbuvxsAaGiHA2xd0RVm2Mrx-gQtdPqtbZPuQcH7k64Z_EOQBgiGTgVjucyHD6zBijr_P-2mhIxuecNSw

Faça uma requisição para obter o token de acesso

Após gerar um JWT assinado, faça uma requisição para nossa plataforma de autenticação (POST /oauth2/token) enviando os parâmetros conforme a tabela abaixo:

Parâmetro

Descrição

grant_type

Enviar sempre o valor urn:ietf:params:oauth:grant-type:jwt-bearer

assertion

JWT assinado, como gerado acima

Abaixo um exemplo com o JWT gerado nos passos acima:

curl --location --request POST 'https://identityhomolog.acesso.io' \
--header 'Content-Type: application/x-www-form-urlencoded' \
--data-urlencode 'grant_type=urn:ietf:params:oauth:grant-type:jwt-bearer' \
--data-urlencode 'assertion=eyJhbGciOiJSUzI1NiIsInR5cCI6IkpXVCJ9.eyJpc3MiOiJzZXJ2aWNlX2FjY291bnRfbmFtZUB0ZW5hbnRfaWQuaWFtLmFjZXNzby5pbyIsImF1ZCI6Imh0dHBzOi8vaWRlbnRpdHlob21vbG9nLmFjZXNzby5pbyIsInNjb3BlIjoiKiIsImV4cCI6MTYyNjI5Njk3NiwiaWF0IjoxNjI2MjkzMzc2fQ.JsymP3NZdgCSqeNlgsOM2-AQ7M450NxFnZnnaKSu4Q8g12QGEIvvM4EhCokUHfwk5s7pOpm2UD_Ng3Hb5g_wgrjfiVSLWH5Q2wYg1AvfLqoYSoJWaMHm9KL0kpv32XdDD8TZVR-MVd2VBHmCMVbV6gvk8buUoK1HZDN7g84PaY3bfgcB3RKU-H55lR8yyJjZxToIv17-wfla2G99uaMEFNGX0ZSE7ETn5Z8-WypmFrNAK0TM58upzvfVI6_-gY4cj4iQvmRbuvxsAaGiHA2xd0RVm2Mrx-gQtdPqtbZPuQcH7k64Z_EOQBgiGTgVjucyHD6zBijr_P-2mhIxuecNSw'

Se tudo der certo em sua requisição, você receberá como resposta um JSON contendo um token de acesso válido:

{
  "access_token": "<access_token>",
  "token_type": "Bearer",
  "expires_in": "3600",
}

Validade do Token

A duração do token de acesso estará informada no campo “expires_in”. Não solicite um novo token de acesso até que a validade do token atual esteja chegando ao fim.

Sugerimos que solicite um novo token 10 minutos antes da expiração.

Em casos de erro, retornaremos como resposta um JSON como o abaixo:

{
  "error": "server_error",
  "error_description": "Falha na autenticação x.x.x",
}

Erros ao chamar o endpoint de autorização

Você pode consultar os códigos de erros neste mesmo artigo, na seção Códigos de erro.

Use seu token de acesso para chamar nossas APIs

Agora que você obteve um token de acesso válido, basta chamar a API REST do Unico Sign utilizando este token no header de suas requisições. Abaixo um exemplo:

curl -X 'POST' \
  'https://sign-core-uat.acesso.io/api/v1/service/envelopes' \
  -H 'accept: application/json' \
  -H 'Content-Type: application/json' \
  -H 'Authorization: Bearer {{ACCESS_TOKEN}}'
  -d '{
  "CPF": "10000000019",  
  "StartDate": "01/08/2022",
  "EndDate": "31/08/2022",
  "Status": 1,
  "Order": "ASC"
}'

Códigos de erro

Caso sua requisição apresente algum erro, você pode consultar o motivo do erro na tabela abaixo:

Código

Descrição

1.0.14

Verifique com o responsável pelo projeto se a aplicação utilizada está ativa.

1.1.1

Parâmetro "scope" não foi informado no payload do token jwt utilizado na requisição.

1.2.4

O token jwt utilizado na requisição está expirado. Verifique o valor informado no campo "exp" do payload.

1.2.5

O token jwt utilizado na requisição não pode ser validado. Verifique os parâmetros informados e tenha certeza de tê-lo assinado da forma correta.

1.2.6

A chave privada utilizada na assinatura do token jwt utilizado na requisição não é mais aceitável. Solicite novas credenciais para a conta utilizada.

1.2.7

O token jwt utilizado na requisição não é mais aceitável, pois já foi utilizado anteriormente. Gere um novo token para fazer uma nova requisição.

1.2.11

A conta utilizada não está ativa.

1.2.14

A conta utilizada não possui as permissões necessárias.

1.2.18

A conta utilizada foi temporariamente bloqueada por ter excedido a quantidade de tentativas inválidas de autenticação.

1.2.19

A conta utilizada não está autorizada a impersonar outra conta de usuário (remova o parâmetro "sub" do payload).

1.2.20 / 1.2.21

Falha na decodificação do token jwt utilizado na requisição. Utilize um novo token inserindo somente os campos especificados nas seções "Campos obrigatórios" e "Campos adicionais", obedecendo à nomenclatura, semântica e tipo de cada campo.

1.2.22

O token jwt utilizado na requisição possui campos adicionais no payload que não são permitidos. Utilize um novo token inserindo somente os campos especificados nas seções "Campos obrigatórios" e "Campos adicionais", obedecendo à nomenclatura, semântica e tipo de cada campo.

1.3.1

A conta utilizada possui restrições de IP de origem.

1.3.2

A conta utilizada possui restrições de data/hora de acesso.

Próximos passos

Conheça as funcionalidades disponíveis para o Gerenciamento de documentos.
Conheça as funcionalidades disponíveis para o Gerenciamento de envelopes.
Tendo problemas em nossa integração? Acesse nossa seção de FAQ e problemas comuns.

Dúvidas?

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.

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:

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 para configurar sua conta de teste e obter suas chaves de API.
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.

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:

Informações do emissor (Emmiter);
Tipo de documento (Um PDF em base64 ou um template pré estabelecido);
Informações de quem irá assinar o documento (Subscriber);
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.

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"
            }
        ]
    }
]

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

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 assinante do envelope. Entenda os valores disponíveis na tabela abaixo.

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

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 parâmetro 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 resposta:

{
    "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 as funcionalidades disponíveis para o Gerenciamento de documentos.
Conheça as funcionalidades disponíveis para o Gerenciamento de envelopes.
Tendo problemas em nossa integração? Acesse nossa seção de FAQ e problemas comuns.

Dúvidas?

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.

Gerenciando documentos

Obter detalhes

Sobre este guia

Através deste guia, demonstraremos como obter todos os detalhes de um documento através de nossa API REST. Ao seguir os passos deste guia, em poucos minutos você será capaz de obter todos os detalhes de um documento de forma estruturada em uma resposta JSON.

O que você vai precisar

Antes de iniciar sua integração:

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 para configurar sua conta de teste e obter suas chaves de API.
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

Todos os eventos que ocorrem no ciclo vida de um documento ficam registrados e podem ser recuperados através desta funcionalidade. Este endpoint disponibilza os detalhes de cada documento, assim como todos seus eventos.

Atualmente, os seguintes eventos são armazenados e retornados:

Envio do documento para assinatura;
Abertura do link do envelope por um assinante;
Visualização do documento por um assinante;
Assinatura ou recusa do documento por um assinante;

Entenda, a seguir, como chamar nossa API Rest para obter detalhes de seus documentos:

Obtenha um token OAuth válido

Para efetuar requisições à nossa API REST você necessitará de um token de acesso OAuth válido. Caso não esteja familiarizado com o modelo de autenticação OAuth, entenda como gerar um token válido neste artigo. Após sua geração, o token de acesso deverá ser enviado no header de sua requisição, junto ao parâmetro Authorization.

Ambientes

Ao iniciar sua integração você receberá credenciais a nosso ambiente de homologação. Sómente após o processo de testes e certificação você receberá credenciais de produção.

Você deverá apontar suas requisições às URLs corretas em cada estágio de sua integração. Abaixo listamos as URLs de homologação e produção:

Ambiente de homologação: https://signhom.acesso.io;
Ambiente de produção: https://sign.acesso.io.

Faça uma requisição GET para o endpoint `/documents/`

Após gerar um token de acesso válido, faça uma requisição para o endpoint de obtenção de detalhes de documentos da nossa API REST (GET/service/documents), especificando qual documento deseja como um parâmetro no path da requisição.

Abaixo um exemplo da requisição:

Não se esqueça de substituir o parâmetro DOCUMENT_UUID na requisição abaixo. Este parâmetro deve conter o UUID do documento ao qual você deseje gerar as evidências.

Exemplo de formato de um UUID: 00000000-0000-0000-0000-000000000000

curl -X 'GET' \
  'https://sign-core-dev.acesso.io/api/v1/service/documents/{{DOCUMENT_UUID}}' \
  -H 'accept: application/pdf' \
  -H 'Authorization: Bearer {{ACCESS_TOKEN}}'

Se tudo der certo em sua requisição, você receberá como respota um JSON contendo uma lista com os campos do template:

{
  "Url": "https://",
  "UrlVoucher": "https://",
  "DocumentType": "Nome",
  "CreatedDate": "09/04/2022 20:09",
  "EmitterUserName": "Name",
  "EmitterUserEmail": "email@gmail.com",
  "CompanySocialName": "Unico",
  "UUID": "4a95e405-2534-4cf6-aa56-01ddc535bbf4",
  "HasFile": false,
  "Subscribers": [
    {
      "SubscriberName": "Flavia dos Santos",
      "SubscriberCPF": "10000000019",
      "SubscriberEmail": "email@gmail.com",
      "SubscriberPhone": "5513987654321",
      "ID_SubscriberStatus": 108,
      "SubscriberOrder": 1,
      "SubscriberEvents": [
        {
          "EventName": "NotifiedEmail",
          "EventDescription": "O envelope foi enviado via E-mail",
          "EventDates": [
            "2022-09-03T20:20:01.6046578+00:00"
          ]
        },
        {
          "EventName": "EnvelopeOpened",
          "EventDescription": "O link do envelope foi aberto",
          "EventDates": [
            "2022-09-04T15:20:01.6046598+00:00",
            "2022-09-04T16:20:01.6046602+00:00"
          ]
        },
        {
          "EventName": "DocumentViewed",
          "EventDescription": "O documento foi visualizado",
          "EventDates": [
            "2022-09-04T17:20:01.6046608+00:00",
            "2022-09-04T18:20:01.6046614+00:00",
            "2022-09-04T19:20:01.6046616+00:00"
          ]
        },
        {
          "EventName": "DocumentAccepted",
          "EventDescription": "O documento foi aceito",
          "EventDates": [
            "2022-09-04T20:10:01.6046619+00:00"
          ]
        },
        {
          "EventName": "DocumentRefused",
          "EventDescription": "Recusou-se a assinar",
          "EventData": "Os meus dados pessoais estão inválidos.",
          "EventDates": [
            "2024-10-04T13:33:16.210813+00:00"
          ]
        },
        {
          "EventName": "DocumentFinalized",
          "EventDescription": "O processo de assinatura do signatário foi finalizado",
          "EventDates": [
            "2022-09-04T20:15:01.6046622+00:00"
          ]
        }
      ]
    }
  ],
  "IsTemplate": false,
  "DocumentSubcategoryUUID": "af70e1a4-1f8e-432c-b4c1-40b29dfd1aea",
  "DocumentSubcategoryName": "Abertura de conta bancária",
  "DocumentCategoryUUID": "e3529e7f-63cd-4574-a03e-d248f078d8fd",
  "DocumentCategoryName": "Admissão"
}

Cada elemento do objeto SubscriberEvents representa um evento ocorrido no documento, sendo que:

O parâmetro EventName representa o nome do evento;
O parâmetro EventDescription representa a descrição do evento;
O parâmetro EventDates contem uma lista de datas nas quais o evento ocorreu.

Próximos passos

Conheça as funcionalidades disponíveis para o Gerenciamento de documentos.
Conheça as funcionalidades disponíveis para o Gerenciamento de envelopes.
Tendo problemas em nossa integração? Acesse nossa seção de FAQ e problemas comuns.

Dúvidas?

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.

Obter arquivo PDF

Sobre este guia

Através deste guia, demonstraremos como gerar um arquivo PDF a partir de um documento através de nossa API REST. Ao seguir os passos deste guia, em poucos minutos você será capaz de obter um arquivo PDF do documento desejado.

Você já sabe, mas não custa lembrar: Um envelope possui um ou mais documentos. O documento em questão deverá estar dentro de um envelope.

O que você vai precisar

Antes de iniciar sua integração:

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 para configurar sua conta de teste e obter suas chaves de API.
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, Documentos (document) são a representação virtual de um documento que deve ser assinado (por um ou mais assinanates) e pode ser gerado a patir de um arquivo PDF ou de um modelo (Template). Os documentos estão contidos dentro de um envelope, que por sua vez pode conter um ou mais documentos.

Entenda a seguir, como obter um arquivo PDF de um documentos pertencente a um de seus envelopes:

Obtenha um token OAuth válido

Ambientes

Ao iniciar sua integração você receberá credenciais a nosso ambiente de homologação. Somente após o processo de testes e certificação você receberá credenciais de produção.

Você deverá apontar suas requisições às URLs corretas em cada estágio de sua integração. Abaixo listamos as URLs de homologação e produção:

Ambiente de homologação: https://signhom.acesso.io;
Ambiente de produção: https://sign.acesso.io.

Faça uma requisição para o endpoint `/file/`

Após gerar um token de acesso válido, faça uma requisição para o endpoint de geração de arquivos PDF de nossa API REST (GET/service/file), especificando qual documento deseja como um parâmetro no path da requisição.

Abaixo um exemplo da requisição:

Não se esqueça de substituir o parâmetro DOCUMENT_UUID na requisição abaixo. Este parâmetro deve conter o UUID do documento ao qual você deseje gerar as evidências.

Exemplo de formato de um UUID: 00000000-0000-0000-0000-000000000000

curl -X 'GET' \
  'https://sign-core-dev.acesso.io/api/v1/service/file/{{DOCUMENT_UUID}}' \
  -H 'accept: application/pdf' \
  -H 'Authorization: Bearer {{ACCESS_TOKEN}}'

Se tudo der certo em sua requisição, você receberá como resposta o arquivo binário do PDF.

Próximos passos

Conheça as funcionalidades disponíveis para o Gerenciamento de documentos.
Conheça as funcionalidades disponíveis para o Gerenciamento de envelopes.
Tendo problemas em nossa integração? Acesse nossa seção de FAQ e problemas comuns.

Dúvidas?

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.

Obter dados de modelo

Sobre este guia

Através deste guia, demonstraremos como obter dados preenchidos em um documento gerado a partir de um modelo através de nossa API REST. Ao seguir os passos deste guia, em poucos minutos você será capaz de obter todos os dados inseridos pelos usuários em seus documentos.

O que você vai precisar

Antes de iniciar sua integração:

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 para configurar sua conta de teste e obter suas chaves de API.
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, Documentos (document) são a representação virtual de um documento que deve ser assinado (por um ou mais assinanates) e pode ser gerado a patir de um arquivo PDF ou de um modelo (Template). Documentos gerados a partir de template podem possuir campos preenchíveis pelos usuários que irão assinar o documento.

Entenda a seguir, como obter dados preenchidos por um assinante em documentos gerados a partir de um modelo:

Obtenha um token OAuth válido

Ambientes

Ao iniciar sua integração você receberá credenciais a nosso ambiente de homologação. Somente após o processo de testes e certificação você receberá credenciais de produção.

Você deverá apontar suas requisições às URLs corretas em cada estágio de sua integração. Abaixo listamos as URLs de homologação e produção:

Ambiente de homologação: https://signhom.acesso.io;
Ambiente de produção: https://sign.acesso.io.

Faça uma requisição para o endpoint `/templatedata/`

Após gerar um token de acesso válido, faça uma requisição para o endpoint de obtenção dos dados do template na nossa API REST (GET/service/templatedata), especificando qual documento deseja como um parâmetro no path da requisição.

Abaixo um exemplo da requisição:

Não se esqueça de substituir o parâmetro DOCUMENT_UUID na requisição abaixo. Este parâmetro deve conter o UUID do documento ao qual você deseje gerar as evidências.

Exemplo de formato de um UUID: 00000000-0000-0000-0000-000000000000

curl -X 'GET' \
  'https://sign-core-dev.acesso.io/api/v1/service/templatedata/{{DOCUMENT_UUID}}' \
  -H 'accept: application/pdf' \
  -H 'Authorization: Bearer {{ACCESS_TOKEN}}'

Se tudo der certo em sua requisição, você receberá como respota um JSON contendo uma lista com os campos do template:

{
    "Success": true,
    "Message": "",
    "Data": {
        "UUID": "d610d146-d658-428c-9c63-2067807fb22a",
        "TemplateFields": [
            {
                "FieldCode": "CampoTextBox",
                "FieldValue": "Reposta Modelo"
            },
            {
                "FieldCode": "CampoCheckBox1",
                "FieldValue": "1"
            },
            {
                "FieldCode": "CampoRadioATrue",
                "FieldValue": "0"
            },
            {
                "FieldCode": "CampoRadioAFalse",
                "FieldValue": "1"
            }
        ]
    }
}

Cada elemento do objeto TemplateFields representa um campo no template, sendo que:

O parâmetro FieldCode representa o nome do campo;
O parâmetro FieldValue representa o valor preenchido no campo correspondente.

Próximos passos

Conheça as funcionalidades disponíveis para o Gerenciamento de documentos.
Conheça as funcionalidades disponíveis para o Gerenciamento de envelopes.
Tendo problemas em nossa integração? Acesse nossa seção de FAQ e problemas comuns.

Dúvidas?

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.

Obter evidências

Sobre este guia

Através deste guia, demonstraremos como recuperar um conjunto de evidências de um documento assinado através de nossas APIs REST. Ao seguir os passos deste guia, em poucos minutos você será capaz de obter um arquivo PDF com o conjunto de evidências.

Envelopes, documentos e evidências

Você já sabe, mas não custa lembrar: Um envelope possui um ou mais documentos. As evidências relacionam-se diretamente aos documentos e não aos envelopes.

O que você vai precisar

Antes de iniciar sua integração:

Certifique-se que você possui credenciais válidas para utilizar o Unico Sign. Se você ainda não possui suas credenciais, siga nosso para configurar sua conta de teste e obter suas chaves de API.
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 .

Funcionamento básico

Como explicamos em nosso , Evidências servem para comprovar juridicamente a conformidade e validade de um envelope, documento ou assinatura.

Os elementos básicos de um conjunto de Evidências são:

Dados do emissor do envelope;
Dados do envelope (Id e Status);
Dados do documento original (Nome, Id e Hash SHA256 do documento);
Dados dos assinantes;
Dados do documento assinado (Nome, Id e Hash SHA256 da assinatura);
Logs dos eventos ocorridos no envelope.

Entenda a seguir, como obter um arquivo PDF com o conjunto de evidências de um documento já assinado:

Obtenha um token OAuth válido

Ambientes

Ao iniciar sua integração você receberá credenciais a nosso ambiente de homologação. Somente após o processo de testes e certificação você receberá credenciais de produção.

Você deverá apontar suas requisições às URLs corretas em cada estágio de sua integração. Abaixo listamos as URLs de homologação e produção:

Ambiente de homologação: https://signhom.acesso.io;
Ambiente de produção: https://sign.acesso.io.

Certifique-se que o documento tem um status válido

O documento de evidências está disponível apenas para os 3 status finais do fluxo de assinaturas: Concluído, recusado ou cancelado. Caso o documento não esteja em um desses formatos, você não conseguirá gerar o arquivo PDF.

Consulta do status

Caso o documento não esteja em um status considerado "final", retornaremos um erro HTTP 500.

import HttpMethod from '@site/src/components/HttpMethod';

Você pode consultar o status dos documentos através do método (GET/service/documents). Saiba mais sobre este método neste guia.

Faça uma requisição para o endpoint `/evidence/`

Após gerar um token de acesso válido, faça uma requisição para o endpoint de geração de evidencias de nossa API REST (GET/service/evidence), especificando o documento ao qual deseja gerar as evidências como um parâmetro no path.

Abaixo um exemplo da requisição:

Não se esqueça de subsctituir o parâmetro DOCUMENT_UUID na requisição abaixo. Este parâmetro deve conter o UUID do documento ao qual você deseje gerar as evidências.

Exemplo de formato de um UUID: 00000000-0000-0000-0000-000000000000

Se tudo der certo em sua requisição, você receberá como resposta o arquivo binário do PDF.

Obter categorias

Sobre este guia

Através deste guia, demonstraremos como obter todas as categorias e subcategorias disponíveis de um usuário através de nossa API REST. Ao seguir os passos deste guia, em poucos minutos você será capaz de obter todas as categorias disponíveis em seus documentos em uma resposta JSON.

O que você vai precisar

Antes de iniciar sua integração:

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 para configurar sua conta de teste e obter suas chaves de API.
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

Cada documento pode ser classificado com uma categorias e subcategoria. Essas categorias são uteis para classificar e identificar facilmente quais IDs correspondem a quais documentos.

Entenda, a seguir, como chamar nossa API Rest para obter suas categorias:

Obtenha um token OAuth válido

Ambientes

Ao iniciar sua integração você receberá credenciais a nosso ambiente de homologação. Somente após o processo de testes e certificação você receberá credenciais de produção.

Você deverá apontar suas requisições às URLs corretas em cada estágio de sua integração. Abaixo listamos as URLs de homologação e produção:

Ambiente de homologação: https://signhom.acesso.io;
Ambiente de produção: https://sign.acesso.io.

Faça uma requisição GET para o endpoint `/categories/`

Após gerar um token de acesso válido, faça uma requisição para o endpoint de obtenção de categorias da nossa API REST (GET/service/categories).

Abaixo um exemplo da requisição:

curl -X 'GET' \
  'https://sign-core-dev.acesso.io/api/v1/service/categories/' \
  -H 'accept: application/json' \
  -H 'Authorization: Bearer {{ACCESS_TOKEN}}'

Se tudo der certo em sua requisição, você receberá como respota um JSON contendo as categorias com seus documentIds.

{
  "Success": true,
  "Message": "",
  "Data": {
    "Page": 5,
    "Count": 1,
    "DocumentCategories": [
      {
        "DocumentCategoryName": "Admissão",
        "UUID": "00000000-0000-0000-0000-000000000000",
        "DocumentSubcategories": [
          {
            "DocumentSubcategoryName": "Contrato",
            "DocumentCategoryUUID": "dad4bfa9-a993-492d-953e-d412d2d185f3",
            "UUID": "00000000-0000-0000-0000-000000000000"
          },
          {
            "DocumentSubcategoryName": "Exame médico",
            "DocumentCategoryUUID": "dad4bfa9-a993-492d-953e-d412d2d185f3",
            "UUID": "00000000-0000-0000-0000-000000000000"
          }
        ]
      }
    ]
  }
}

Próximos passos

Conheça as funcionalidades disponíveis para o Gerenciamento de documentos.
Conheça as funcionalidades disponíveis para o Gerenciamento de envelopes.
Tendo problemas em nossa integração? Acesse nossa seção de FAQ e problemas comuns.

Dúvidas?

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.

Gerenciando envelopes

Cancelar envelopes

Sobre este guia

Através deste guia, demonstraremos como cancelar um envelope através de nossa API REST. Ao seguir os passos deste guia, em poucos minutos você será capaz de cancelar um envelope a partir de seu UUID e receber uma confirmação em uma resposta JSON.

O que você vai precisar

Antes de iniciar sua integração:

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 para configurar sua conta de teste e obter suas chaves de API.
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, nossa entidade Envelope (envelope) é a representação virtual de um envelope com documentos na vida real. Ele é o objeto que agrupa todos os documentos (document) e seus assinantes (subscriber), sendo que um envelope pode conter mais de documento, que por sua vez pode conter um ou mais assinantes.

Ao cancelar um envelope, um e-mail e/ou SMS serão enviados para os assinantes dos documentos contidos no envelope. O método de notificação irá dependender de quais dados dos assinantes foram cadastrados no momento do envio do envelope.

Uma vez cancelado, o envelope não poderá mais ser acessado, assinado ou recusado pelos assinantes.

Entenda, a seguir, como chamar nossa API REST para cancelar um envelope.

Obtenha um token OAuth válido

Ambientes

Ao iniciar sua integração você receberá credenciais a nosso ambiente de homologação. Somente após o processo de testes e certificação você receberá credenciais de produção.

Você deverá apontar suas requisições às URLs corretas em cada estágio de sua integração. Abaixo listamos as URLs de homologação e produção:

Ambiente de homologação: https://signhom.acesso.io;
Ambiente de produção: https://sign.acesso.io.

Faça uma requisição POST para o endpoint `/cancel/`

Após gerar um token de acesso válido, faça uma requisição para o endpoint de cancelamento de envelopes da nossa API REST (POST/service/cancel) enviando os parâmetros conforme o schema abaixo:

EnvelopeUUID

string <uuid>

Identificador único do envelope

Reason

string

Motivo de cancelamento do envelope

UserName

string or null

Default: "Integração"

Nome do usuário que está cancelando

Se não fornecido será extraído o nome de usuário do token utilizado, e se não encontrado o nome será Integração

Permissão para Visualizar Documentos

Para utilizar esta rota é necessário que o usuário tenha permissão de Enviar Documentos.

Abaixo um exemplo de como cancelar um envelope com o UUID igual a 00000000-0000-0000-0000-000000000000 informando como motivo "Solicitação de correção":


curl -X 'POST' \
  'https://sign-core-uat.acesso.io/api/v1/service/cancel' \
  -H 'accept: application/json' \
  -H 'Content-Type: application/json' \
  -H 'Authorization: Bearer {{ACCESS_TOKEN}}'
  -d '{
  "EnvelopeUUID": "00000000-0000-0000-0000-000000000000",
  "Reason": "Solicitação de correção"
}'

Se tudo der certo em sua requisição, você receberá como resposta um JSON contendo a confirmação da exclusão do envelope.

{
  "Success": true,
  "Message": "Envelope cancelado com sucesso"
}

Próximos passos

Conheça as funcionalidades disponíveis para o Gerenciamento de documentos.
Conheça as funcionalidades disponíveis para o Gerenciamento de envelopes.
Tendo problemas em nossa integração? Acesse nossa seção de FAQ e problemas comuns.

Dúvidas?

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.

Listar documentos

Sobre este guia

Através deste guia, demonstraremos como listar os documentos pertencentes a um envelope através de nossa API REST. Ao seguir os passos deste guia, em poucos minutos você será capaz de obter todos os documentos de um envelope (assim como alguns de seus detalhes), de forma estruturada em uma resposta JSON.

O que você vai precisar

Antes de iniciar sua integração:

Certifique-se que você possui credenciais válidas para utilizar o Unico Sign. Se você ainda não possui suas credenciais, siga nosso para configurar sua conta de teste e obter suas chaves de API.
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 .

Funcionamento básico

Como explicamos em nosso , nossa entidade Envelope (envelope) é a representação virtual de um envelope com documentos na vida real. Ele é o objeto que agrupa todos os documentos (document) e seus assinantes (subscriber), sendo que um envelope pode conter mais de documento, que por sua vez pode conter um ou mais assinantes.

Entenda, a seguir, como chamar nossa API REST para obter todos os documentos de um envelope.

Obtenha um token OAuth válido

Para efetuar requisições à nossa API REST você necessitará de um token de acesso OAuth válido. Caso não esteja familiarizado com o modelo de autenticação OAuth, entenda como gerar um token válido . Após sua geração, o token de acesso deverá ser enviado no header de sua requisição, junto ao parâmetro Authorization.

Ambientes

Ao iniciar sua integração você receberá credenciais a nosso ambiente de homologação. Somente após o processo de testes e certificação você receberá credenciais de produção.

Você deverá apontar suas requisições às URLs corretas em cada estágio de sua integração. Abaixo listamos as URLs de homologação e produção:

Ambiente de homologação: https://signhom.acesso.io;
Ambiente de produção: https://sign.acesso.io.

Configure os filtros de sua pesquisa

Opcionalmente, você pode configurar alguns critérios para sua busca. Para isto, os campos de filtro devem ser enviados no body de sua requisição.

Obrigatoriedade dos filtros

Nenhum dos filtros é obrigatório. Caso não informados, por padrão, retornaremos 30 envelopes em nossa resposta JSON.

O schema abaixo contêm os parâmetros e domínios permitidos para a configuração dos filtros:

O exemplo abaixo solicita em ordem ascendente, envelopes cujos assinantes possuam o CPF 100.000.000-19, criados de 01/08/2022 a 31/08/2022, com status pendente.

Faça uma requisição POST para o endpoint `/envelopes/`

Após gerar um token de acesso válido e, opcionalmente, montar o body com os filtros, faça uma requisição para o endpoint de obtenção de lista de documentos da nossa API REST (POST/service/envelopes). Serão obtidos os dados de todos envelopes atrelados ao usuário do token utilizado.

Permissão para Visualizar Documentos

Para utilizar esta rota é necessário que o usuário tenha permissão de Visualizar Documentos.

Exemplo solicitando em ordem ascendente, envelopes cujos assinantes possuam o CPF 100.000.000-19, criados de 01/08/2022 a 31/08/2022, com status pendente:

Se tudo der certo em sua requisição, você receberá como resposta um JSON contendo uma lista todos os envelopes associados a sua consulta:

Limite de páginas

Atualmente não é possível listar documentos da página 334 em diante. Caso seja necessário acessar uma dessas páginas, recomendamos utilizar os filtros para uma busca mais precisa.

Cada elemento do objeto Envelopes representa um envelope com seus respectivos documentos, contidos no objeto Documents.

Próximos passos

Reenviar envelopes

Sobre este guia

Através deste guia, demonstraremos como reenviar um envelope através de nossa API REST. Ao seguir os passos deste guia, em poucos minutos você será capaz de reenviar um envelope a partir de seu UUID.

O que você vai precisar

Antes de iniciar sua integração:

Certifique-se que você possui credenciais válidas para utilizar o Unico Sign. Se você ainda não possui suas credenciais, siga nosso para configurar sua conta de teste e obter suas chaves de API.
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 .

Funcionamento básico

Disponibilizamos este end-point para reenviar os envelopes (ainda pendentes de assinatura) para seus assinantes, podendo inclusive informar um novo e-mail ou telefone.

Fluxo de assinatura dentro de um frame

Envelopes criados com a opção isFrame=True não podem ser reenviados.

Entenda, a seguir, como chamar nossa API REST para reenviar um envelope.

Obtenha um token OAuth válido

Ambientes

Ao iniciar sua integração você receberá credenciais a nosso ambiente de homologação. Somente após o processo de testes e certificação você receberá credenciais de produção.

Você deverá apontar suas requisições às URLs corretas em cada estágio de sua integração. Abaixo listamos as URLs de homologação e produção:

Ambiente de homologação: https://signhom.acesso.io;
Ambiente de produção: https://sign.acesso.io.

Faça uma requisição POST para o endpoint `/resend/`

Após gerar um token de acesso válido, faça uma requisição para o endpoint de reenvio de envelopes da nossa API REST (POST/service/resend) enviando os parâmetros conforme o schema abaixo:

Abaixo um exemplo de como reenviar um um envelope com o UUID igual a 00000000-0000-0000-0000-000000000000, atualizando as informações de Subscribers.

Se tudo der certo em sua requisição, você receberá como resposta um código HTTP 200, que confirma o reenvio de seu envelope.

Gerenciando contatos

Sobre este guia

Através deste guia, demonstraremos como alterar ou criar contatos através de nossa API REST. Ao seguir os passos deste guia, em poucos minutos você será capaz de criar ou alterar contatos com apenas um endpoint.

O que você vai precisar

Antes de iniciar sua integração:

Certifique-se que você possui credenciais válidas para utilizar o Unico Sign. Se você ainda não possui suas credenciais, siga nosso para configurar sua conta de teste e obter suas chaves de API.
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 .

Funcionamento básico

Através deste endpoint, você poderá criar ou editar contatos utilizando um CPF como chave única de consulta.

Caso o CPF enviado na requisição ainda não esteja cadastrado, um novo contato associado a sua conta será criado. Caso o CPF já existam, atualizaremos os dados do contato com as informações enviadas na requisição.

Entenda, a seguir, como chamar nossa API REST para criar ou editar contatos:

Obtenha um token OAuth válido

Para efetuar requisições à nossa API REST você necessitará de um token de acesso OAuth válido. Caso não esteja familiarizado com o modelo de autenticação OAuth, entenda como gerar um token válido . Após sua geração, o token de acesso deverá ser enviado no header de sua requisição, junto ao parâmetro Authorization.

Ambientes

Ao iniciar sua integração você receberá credenciais a nosso ambiente de homologação. Somente após o processo de testes e certificação você receberá credenciais de produção.

Você deverá apontar suas requisições às URLs corretas em cada estágio de sua integração. Abaixo listamos as URLs de homologação e produção:

Ambiente de homologação: https://signhom.acesso.io;
Ambiente de produção: https://sign.acesso.io.

Faça uma requisição POST para o endpoint `/cancel/`

Após gerar um token de acesso válido, faça uma requisição para o endpoint de gerenciamento de contatos da nossa API REST (POST/service/contact) enviando os parâmetros conforme o schema abaixo:

Permissão para Visualizar Documentos

Para utilizar esta rota é necessário que o usuário tenha permissão de Adminstrar Contatos.

Abaixo um exemplo alterando o nome e o e-email do CPF 100.000.000-19 (Assumindo que o CPF já existe na base).

Se tudo der certo em sua requisição, você receberá como resposta um JSON contendo a confirmação da inclusão ou atualização do contato, conforme abaixo:

Recursos adicionais

FAQ

Consolidamos aqui algumas das perguntas mais frequentes sobre nossos SDKs. Confira abaixo:

Para que serve o campo “IsFrame”?

O detalhamento do campo IsFrame está da nossa documentação.

A notificação do callback é enviada para quais status do envelope?

O detalhamento do callback está da nossa documentação.

Posso incluir mais de um assinante no mesmo envelope/requisição?

Sim, o envio de novo envelope aceita até no máximo 10 assinantes.

Qual o número máximo de documentos que posso incluir em um envelope?

É possível incluir quantos documentos quiser desde que não sejam ultrapassados os limites de tamanho de 20MB no total e 10MB por arquivo.

Qual o tamanho máximo dos documentos que posso incluir em um envelope?

É possível inserir documentos de até 10MB cada um e a soma do tamanho dos arquivos tem um máximo de 20MB.

Não, apenas o assinante com ordem 1, ou seja, a primeira pessoa a assinar pode preencher os campos em branco.

Não existe limitação do número de requisições por tempo.

O UUID do documento é recebido na resposta da chamada quando é feita uma requisição para que seja criado um novo envelope. Também é possível obter esse UUID fazendo uma busca por envelope.

Algumas razões podem estar ocasionando esse problema.

Se na hora do envio for cadastrado telefone e o email não for informado, então será enviada a notificação por SMS e não haverá notificação por email.
Se na hora do envio for cadastrado email e o telefone não for informado, então será enviada a notificação por email e não haverá notificação por SMS.
Se na hora do envio for cadastrado telefone e email e o assinante tiver o Unico | You instalado ele não receberá email, apenas a notificação do aplicativo e o SMS.
Se na hora do envio o IsFrame estiver como true, não é enviada nenhuma notificação.

Depende da configuração de cada cliente, mas o padrão é que o envelope expire após 10 dias corridos desde a data de envio.

Não. O período de expiração é geral para todos os envelopes.

Não, são aceitos apenas PDFs.

Só é possível reenviar um envelope que esteja com status de pendente ou expirado, qualquer outro status ocasionará em erro.

Só é possível cancelar um envelope que esteja com status de pendente ou expirado, qualquer outro status ocasionará em erro.

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:

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 para configurar sua conta de teste e obter suas chaves de API.
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

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.

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.

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:

Informações do emissor (Emmiter);
Tipo de documento (Um PDF em base64 ou um template pré estabelecido);
Informações de quem irá assinar o documento (Subscriber);
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

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

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"
            }
        ]
    }
]

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)

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

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;

"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 assinante do envelope. Entenda os valores disponíveis na tabela abaixo.

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

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

Valor

Descrição

1

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

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;

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 resposta:

{
    "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 as funcionalidades disponíveis para o Gerenciamento de documentos.
Conheça as funcionalidades disponíveis para o Gerenciamento de envelopes.
Tendo problemas em nossa integração? Acesse nossa seção de FAQ e problemas comuns.

Dúvidas?

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.

Unico Sign

Introdução

Sobre nós​

O que você encontrará por aqui​

Próximos passos​

Primeiros passos

Crie sua conta com a Unico​

Obtenha suas credenciais​

Teste sua integração​

Obtenha um token OAuth válido

Faça uma requisição básica a nossa API

Próximos passos​

Conceitos básicos

Sobre este guia​

Conceitos básicos​

Envelope​

Document​

Subscriber​

Template​

Emitter​

Evidências ou conjunto probatório​

Próximos passos​

Guia das APIs

Visão Geral

Principais funcionalidades​

Casos de uso​

Próximos passos​

Autenticação

Sobre este guia​

O que você vai precisar​

Funcionamento básico​

Solicite uma conta de serviço

Gere um JWT (JSON Web Token)

Faça uma requisição para obter o token de acesso

Use seu token de acesso para chamar nossas APIs

Códigos de erro​

Próximos passos​

Solicitando assinaturas

Sobre este guia​

O que você vai precisar​

Funcionamento básico​

1. Definindo o emissor do envelope​

2. Definindo o tipo de documento​

3. Definindo quem irá assinar os documentos​

4. Configurações adicionais​

5. Juntando todas as peças​

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

Próximos passos​

Gerenciando documentos

Obter detalhes

Sobre este guia​

O que você vai precisar​

Funcionamento básico​

Obtenha um token OAuth válido

Faça uma requisição GET para o endpoint /documents/

Próximos passos​

Obter arquivo PDF

Sobre este guia​

O que você vai precisar​

Funcionamento básico​

Obtenha um token OAuth válido

Faça uma requisição para o endpoint /file/

Próximos passos​

Obter dados de modelo

Sobre este guia​

O que você vai precisar​

Funcionamento básico​

Obtenha um token OAuth válido

Faça uma requisição para o endpoint /templatedata/

Próximos passos​

Obter evidências

Sobre este guia

O que você vai precisar

Funcionamento básico

Obtenha um token OAuth válido

Certifique-se que o documento tem um status válido

Faça uma requisição para o endpoint /evidence/

Obter categorias

Sobre este guia​

O que você vai precisar​

Sobre nós

O que você encontrará por aqui

Próximos passos

Crie sua conta com a Unico

Obtenha suas credenciais

Teste sua integração

Próximos passos

Sobre este guia

Conceitos básicos

Envelope

Document

Subscriber

Template

Emitter

Evidências ou conjunto probatório

Próximos passos

Principais funcionalidades

Casos de uso

Próximos passos

Sobre este guia

O que você vai precisar

Funcionamento básico

Códigos de erro

Próximos passos

Sobre este guia

O que você vai precisar

Funcionamento básico

1. Definindo o emissor do envelope

2. Definindo o tipo de documento

3. Definindo quem irá assinar os documentos

4. Configurações adicionais

5. Juntando todas as peças

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

Próximos passos

Sobre este guia

O que você vai precisar

Funcionamento básico

Faça uma requisição GET para o endpoint `/documents/`

Próximos passos

Sobre este guia

O que você vai precisar

Funcionamento básico

Faça uma requisição para o endpoint `/file/`

Próximos passos

Sobre este guia

O que você vai precisar

Funcionamento básico

Faça uma requisição para o endpoint `/templatedata/`

Próximos passos

Faça uma requisição para o endpoint `/evidence/`

Sobre este guia

O que você vai precisar

Funcionamento básico

Faça uma requisição GET para o endpoint `/categories/`

Próximos passos

Sobre este guia

O que você vai precisar

Funcionamento básico

Faça uma requisição POST para o endpoint `/cancel/`

Próximos passos

Faça uma requisição POST para o endpoint `/envelopes/`

Faça uma requisição POST para o endpoint `/resend/`

Faça uma requisição POST para o endpoint `/cancel/`

Sobre nós

O que você encontrará por aqui

Próximos passos

Principais funcionalidades

Casos de uso

Próximos passos

Crie sua conta com a Unico

Obtenha suas credenciais

Teste sua integração

Próximos passos

Sobre este guia

Conceitos básicos

Envelope

Document

Subscriber

Template

Emitter