Resumo
Para autenticar suas requisições na API, você deve ter seus dados de acesso fornecidos pelo time da RRSign | Portal de Assinaturas.
Com os dados de acesso disponibilizados, sua aplicação deverá requisitar o endpoint responsável por gerar o token de autorização JWT para acessar os demais endpoints disponíveis.
O token possui validade diária. A partir de 00:00 | GMT -3 | Horário padrão de Brasília (América/Sao_Paulo), um novo token deverá ser resgatado no endpoint de autenticação.
Para prosseguir com as instruções de autenticação, entre em contato com api@rrsign.com.br
Áreas
GET api/v1/list-area?{signers=true}
Opção: caso deseje saber quais são os signatários de cada área, enviar o parâmetro signers
= true.
[
{
"id": "0001",
"area": "Contratos"
},
{
"id": "0002",
"area": "Jurídica"
},
{
"id": "0003",
"area": "Trabalhista"
}
]
Unidades de Negócio
GET api/v1/list-business-unit?{signers=true}
Opção: caso deseje saber quais são os signatários de cada unidade de negócio, enviar o parâmetro signers
= true.
[
{
"id": "0001",
"business_unit": "São Paulo"
},
{
"codigo": "0002",
"business_unit": "Porto Alegre"
},
{
"codigo": "0003",
"business_unit": "Rio de Janeiro"
}
]
Folder Type
GET api/v1/list-folder-type
[
{
"id": "0001",
"folder_type": "Contratos"
},
{
"id": "0002",
"folder_type": "Funcionários"
}
]
Posição do Signatário
GET api/v1/list-position
[
{
"id": "0001",
"position": "Diretor",
"reject": true,
"rubric": true,
"finish_alert": true
},
{
"id": "0002",
"position": "Testemunha",
"reject": false,
"rubric": false,
"finish_alert": true
}
]
Na requisição de Posição de Signatário, alguns campos são retornados para que você possa verificar quais permissões o signatário possui para interatividade com o documento.
Segue a lista abaixo:
- reject
: O signatário com esta posição terá permissão para rejeitar um documento.
- rubric
: O signatário com esta posição terá permissão para rubricar um documento.
- finish_alert
: O signatário com esta posição receberá o alerta de documento finalizado.
Atributos
Atributo |
Obrigatório |
Descrição |
Exemplo |
folder
|
Não |
As pastas têm o objetivo de organizar os pacotes de documentos. Nelas, você pode cadastrar informações complementares.
Para anexar um pacote de documentos à uma pasta já existente, o número da mesma deve ser informado através do atributo key .
Caso não seja informado o atributo key da pasta, o pacote de documentos será vinculado à uma nova pasta automaticamente criada.
|
{
"folder": {
"key": "0087/2022",
"type": "1",
"stakeholder": {
"type": "PF/PJ/Outros",
"name": "José da Silva",
"documentation": "123.456.789-10"
},
"area": "4",
"business_unit": "7",
"validity_date_start": "2022-02-06",
"validity_date_end": "2023-02-08"
}
}
|
folder > type
|
Não |
Este atributo define o tipo da sua pasta, de acordo com os tipos cadastrados e configurados em sua base no RRSign | Portal de Assinaturas.
Exemplo: Documentos de Funcionários, Contratos de Serviço e etc.
Para ter acesso à lista de Tipos de Pastas disponíveis para utilização, vá até a sessão Requisição de Parâmetros > Tipos de Pastas nesta documentação e siga as instruções.
Como parâmetro deste atributo, utilize o id do Tipo de pasta desejado.
|
folder > stakeholder
|
Não |
Este atributo é responsável por adicionar uma parte interessada à pasta.
Para isso, os atributos devem ser preenchidos como exemplificado abaixo:
- type : Identifica se é uma Pessoa Física, Jurídica ou Outros (com as opções de parâmetros: PF/PJ/OUTROS)
- name : Nome do Parte Interessada da Pasta
- documentation : Número do documento da Parte Interessada da Pasta
|
folder > area
|
Não |
Este atributo define a área da sua pasta, de acordo com as áreas cadastradas e configuradas em sua base no RRSign | Portal de Assinaturas.
Exemplo: Contratual, Jurídica e etc.
Caso a Área selecionada tenha signatários vinculados, os mesmos serão anexados automaticamente ao pacote de documentos.
Para ter acesso à lista de Áreas disponíveis para utilização, vá até a sessão Requisição de Parâmetros > Áreas nesta documentação e siga as instruções.
Como parâmetro deste atributo, utilize o id da Área desejada.
|
folder > business_unit
|
Não |
Este atributo define a unidade de negócio da sua pasta, de acordo com as unidades de negócios cadastradas e configuradas em sua base no RRSign | Portal de Assinaturas.
Exemplo: Filial de São Paulo, Sede de Porto Alegre e etc.
Caso a Unidade de Negócio selecionada tenha signatários vinculados, os mesmos serão anexados automaticamente ao pacote de documentos.
Para ter acesso à lista de Unidades de Negócios disponíveis para utilização, vá até a sessão Requisição de Parâmetros > Unidades de Negócio nesta documentação e siga as instruções.
Como parâmetro deste atributo, utilize o id da Unidade de Negócio desejada.
|
folder > validity_date_start
|
Não |
Este atributo define a data de início de vigência da pasta.
Esta é uma informação complementar que auxilia no controle e gestão das pastas.
Como parâmetro deste atributo, envie uma data no seguinte formato: 2022-01-25.
|
folder > validity_date_end
|
Não |
Este atributo define a data de fim de vigência da pasta.
Esta é uma informação complementar que auxilia no controle e gestão das pastas.
Como parâmetro deste atributo, envie uma data no seguinte formato: 2022-02-25.
|
draft
|
Não |
Este atributo define se o pacote de documentos será enviado diretamente para assinatura dos signatários ou ficará apenas cadastrado em seu portal de assinaturas, neste caso, aguardando o envio manualmente por um usuário.
O parâmetro deve ser enviado no formato boolean: true ou false.
|
{
"draft": "true"
}
|
sequence
|
Não* |
Este atributo tem a função de definir se haverá ordenção no processo de assinatura dos signatários, fazendo com que os mesmos sigam uma fila para assinatura do pacote de documentos.
Este parâmetro deve ser enviado no formato boolean: true ou false.
|
{
"sequence": "true"
}
|
stakeholder
|
Não |
Este atributo é responsável por adicionar um interessado exclusivamente ao pacote. Desta forma, dando suporte aos casos em que é necessário vincular um interessado diretamente ao pacote, e não à pasta.
Para isso, os parâmetros devem ser preenchidos como exemplificado abaixo:
- type : Identifica se é uma Pessoa Física, Jurídica ou Outros (com as opções de parâmetros: PF/PJ/OUTROS)
- name : Nome do Interessado do Pacote
- documentation : Número do documento do Interessado do Pacote
|
{
"stakeholder": {
"type": "PF",
"name": "Felipe Pereira Oliveira",
"documentation": "123.456.789-10"
}
}
|
documents
|
Sim |
Este parâmetro é responsável por enviar a lista de documentos que serão anexados ao pacote.
Nele, você deve enviar a lista de documentos PDF no formato base64, obrigatoriamente.
Para isso, os atributos devem ser preenchidos, formando um array de objetos, conforme as seguintes instruções:
- title : Título do Documento
- content : Documento (em base64)
|
{
"documents": [
{
"title": "Contrato de Serviços",
"content": "DQolUERGLTEuNwoxIDAgb2J[...]"
},
{
"title": "Contrato de Renovação",
"content": "MyAwIFIgPj4KZW5kb2JqCja[...]"
}
]
}
|
signers
|
Sim |
Este parâmetro é responsável por enviar a lista de signatários que deverão assinar o pacote de documentos.
Nele, você deve enviar a lista de signatários, formando um array de objetos, informando os atributos conforme as instruções abaixo:
- name
- documentation : Número do documento do signatário.
- foreign : Caso o signatário não possua um CPF ou CNPJ, este atributo deve ser preenchido com o parâmetro true . Seu valor padrão é false
- email
- phone : Obrigatório caso whatsapp = true ou tipo_assinatura = eletronica_avancada.
- whatsapp : Para enviar a notificação de assinatura através do WhatsApp, atribua o parâmetro true . Seu valor padrão é false .
- facial_biometrics : Para exigir autenticação biométrica facial pelo signatário, atribua o parâmetro true . Seu valor padrão é false .
- position : Para ter acesso à lista de Posições disponíveis para utilização, vá até a sessão Requisição de Parâmetros > Posição do Signatário nesta documentação e siga as instruções. Como parâmetro deste atributo, utilize o id da Posição desejada.
- sign_type : Possíveis valores:
- eletronica_simples: Assinatura Eletrônica.
- eletronica_avancada: Assinatura Eletrônica com autenticação via SMS.
- digital: Assinatura Digital utilizando o certificado ICP-Brasil.
Para saber mais sobre os tipos de assinatura existentes em nosso Portal de Assinaturas, clique aqui.
|
{
"signers": [
{
"name": "Rogério da Silva",
"documentation": "123.456.789-10",
"email": "rogerio@email.com.br",
"phone": "(11) 12345-6789",
"position": "1",
"sign_type": "digital",
"whatsapp": true,
"facial_biometrics": true
},
{
"name": "Paul Walker",
"documentation": "132546",
"foreign": true,
"email": "paul@email.com",
"position": "2",
"sign_type": "eletronica_simples"
}
]
}
|
followers
|
Não |
Este parâmetro é responsável por enviar a lista de acompanhantes que receberão alertas dos andamentos dos documentos.
Nele, você deve enviar a lista de acompanhantes, formando um array de objetos, informando os atributos conforme as instruções abaixo:
- name
- email
- sign_alert : Define se o acompanhante receberá alerta de assinaturas de cada signatário. Parâmetros possíveis: true ou false .
- finish_alert : Define se o acompanhante receberá alerta de finalização do processo de assinaturas do pacote de documentos. Parâmetros possíveis: true ou false .
|
{
"followers": [
{
"name": "Carlos Magno",
"email": "carlos@email.com.br",
"sign_alert": false,
"finish_alert": true
},
{
"name": "Enzo Marlon",
"email": "enzo@email.com.br",
"sign_alert": true,
"finish_alert": true
}
]
}
|
Após a requisição realizada com os parâmetros adequados, o pacote de documentos será cadastrado e os signatários receberão as instruções para assinatura dos documentos.
Exemplo Prático
Segue abaixo um exemplo do BODY
de uma requisição de inserção de pacote de documentos:
{
"folder": {
"number": "0087",
"type": "1",
"stakeholder": {
"type": "PF/PJ/Outros",
"name": "José da Silva",
"documentation": "123.456.789-10"
},
"area": "2",
"business_unit": "3",
"validity_date_start": "2022-02-06",
"validity_date_end": "2023-02-08"
},
"draft": false,
"sequence": true,
"stakeholder": {
"type": "PF/PJ/Outros",
"name": "RRSign Portal de Assinaturas Ltda",
"documentation": "47.076.298/0001-87"
},
"documents": [
{
"title" : "Contrato de Serviço",
"content" : "DQolUERGLTEuNwoxIDAgb2JqCjw8IC9UeXBlIC[...]"
},
{
"title" : "Relatório Mensal de Vendas",
"content" : "DQolUERGLTEuNwoxIDAgb2JqCjw8IC9UeXBlIC[...]"
}
],
"signers": [
{
"name": "William Santos",
"documentation": "12345678910",
"phone": "(11) 65498-1232",
"position": "3",
"sign_type": "eletronica_simples",
"whatsapp": true
},
{
"name": "Keven Gomes",
"documentation": "32165498710",
"email": "keven@email.com.br",
"position": "4",
"sign_type": "eletronica_simples"
}
],
"followers": [
{
"name": "Fábio de Melo",
"email": "fabio@email.com",
"sign_alert": true
},
{
"name": "Teresa Cristina",
"email": "teresa@email.com.br",
"sign_alert": true,
"finish_alert": true
}
]
}
Segue abaixo um exemplo do BODY
de um callback de inserção de pacote de documentos:
{
"package_key": "1234/2022",
"folder": {
"key": "0087/2022"
},
"uploaded_at": "2022-03-25T15:05:48",
"status": "Em Assinatura",
"documents": [
{
"key": "52040762a9e5aaf872cf4413e1f41083",
"title": "Contrato de Serviço"
},
{
"key": "ba91f20b58f322110086898c9e5346d8",
"title": "Relatório Mensal de Vendas"
}
],
"signers": [
{
"name": "William Santos",
"documentation": "12345678910",
"phone": "(11) 65498-1232",
"email": null,
"position": "5",
"sign_type": "eletronica_simples",
"whatsapp": true,
"from": "API"
},
{
"name": "Keven Gomes",
"documentation": "32165498710",
"phone": null,
"email": "keven@email.com.br",
"position": "6",
"sign_type": "eletronica_simples",
"whatsapp": false,
"from": "API"
},
{
"name": "Gustavo Maia",
"documentation": "48905886810",
"email": "gustavo@email.com.br",
"phone": "(11) 12345-6789",
"position": "1",
"sign_type": "digital",
"whatsapp": false,
"from": "BusinessUnit"
}
]
}
Os signatários são vinculados aos pacotes de documentos a partir de 3 possibilidades:
- Através do atributo signers
na requisição.
- Através da Área vinculada à pasta informada no pacote de documentos.
- Através da Unidade de Negócio vinculada à pasta informada no pacote de documentos.
Com o atributo from
no RESPONSE da requisição, informamos a origem de cada signatário.
Antes de anexá-los aos pacotes de documentos, é realizado um filtro automático para evitar duplicidade de signatários.
Mensagens de Retorno
Padrões e obrigatoriedades
Para garantir a integridade das inserções, a API conta com validações de padrões e obrigatoriedades. Caso alguns campos não estejam conforme o exigido, a requisição retornará mensagens alertando as necessidades para o sucesso da requisição.
A inserção do pacote de documentos será realizada apenas se todos os requisitos forem satisfeitos.
Sucesso da requisição
Com o sucesso da requisição, será iniciado o processo de assinatura do pacote de documentos.
No callback desta requisição, retornamos uma série de informações as quais são disponibilizadas para que você realize um controle e armazenamento em sua aplicação, caso desejar.
N° da Pasta, N° do Pacote, Data de Cadastro e Status do Pacote de Documentos são alguns exemplos de campos retornados no callback desta requisição.
Os Webhooks permitem criar comunicações entre o RRSign | Portal de Assinaturas e a sua plataforma. Caso ocorra algum evento no processo de assinatura, nosso portal realiza uma requisição HTTP POST
para uma URL pré-definida da sua aplicação, a qual deverá estar apta para receber esta comunicação.
Intrudução
Através dos webhooks, possibilitamos que o RRSign dispare requisições para determinadas URLs do seu sistema sempre que algum pacote for assinado, rejeitado ou excluído.
Desta forma, você pode atualizar sua aplicação conforme as informações recebidas do processo de assinatura dos documentos.
Com os webhooks, sua aplicação não será responsável por executar pollings (consultas constantes) na API do RRSign | Portal de Assinaturas. Com o objetivo de evitarmos este procedimento, um webhook é disparado automaticamente quando ocorrer um novo evento.
Por que utilizar os webhooks em vez de pollings? Tendo o mesmo objetivo, os webhooks são muito mais eficientes, pois só há disparo de informação quando há uma atualização em algum dos processos de assinatura.
Configurar Webhook
Para configurar os webhooks, acesse a sua base do RRSign | Portal de Assinaturas, vá em Configurações > Configurações da API > Webhooks e selecione a opção Editar.
Ao abrir uma janela de configuração, cadastre as suas URLs para cada evento disponível nas configurações.
Nesta mesma janela, você pode atualizar a Security Token (necessária para autenticação da requisição) e controlar o status dos webhooks (Ativo ou Desabilitado).
Eventos
Abaixo, listamos os eventos possíveis que disparam webhooks durante o processo de assinatura dos documentos:
1. Assinatura realizada por um signatário: Este evento ocorre quando um dos signatários realiza a sua assinatura no pacote de documentos.
Portanto, enviamos para sua aplicação a requisição com o BODY
abaixo:
{
"package_key": "0752/2022",
"status": "Em Assinatura",
"signer": {
"name": "Gustavo",
"documentation": "1234987984",
"signed_at": "2022-02-02T15:05:01"
}
}
2. Assinaturas concluídas: Este evento ocorre quando o último signatário realiza a sua assinatura no pacote de documentos.
Portanto, enviamos para sua aplicação a requisição com o BODY
abaixo:
{
"package_key": "0752/2022",
"status": "Assinado",
"signed_at": "2022-12-10T15:05:01",
"url": "https://documento.com.br/assinado/chave=123456789"
}
3. Documento Rejeitado: Este evento ocorre quando um signatário rejeita um dos documentos do pacote. Neste caso, o documento será removido do pacote de documentos.
Portanto, enviamos para sua aplicação a requisição com o BODY
abaixo:
{
"document": {
"key": "840c3032ad38a9a500693eb08adc206475",
"title": "Contrato de Trabalho"
},
"package_key": "0752/2022",
"status": "Rejeitado",
"from": {
"name": "Felipe",
"documentation": "98765432110"
},
"reject_reason": "Rejeito este documento pois não concordo com a primeira cláusula do contrato.",
"reject_time": "2022-12-10T15:05:01"
}
4. Pacote de Documentos Excluído: Este evento ocorre quando um usuário do portal exclui um pacote de documentos. Neste caso, o documento será removido portal e seu processo de assinatura será encerrado.
Portanto, enviamos para sua aplicação a requisição com o BODY
abaixo:
{
"package_key": "0752/2022",
"status": "Excluído",
"from": {
"name": "Felipe",
"documentation": "98765432110"
},
"delete_time": "2022-12-10T15:05:01"
}
5. Documento Excluído: Este evento ocorre quando um usuário do portal exclui um documento do pacote. Neste caso, o documento será removido do pacote e não estará na lista de documentos assinados.
Portanto, enviamos para sua aplicação a requisição com o BODY
abaixo:
{
"document": {
"key": "840c3032ad38a9a500693eb08adc206475",
"title": "Contrato de Trabalho"
},
"package_key": "0752/2022",
"status": "Excluído",
"from": {
"name": "Felipe",
"documentation": "98765432110"
},
"delete_time": "2022-12-10T15:05:01"
}
Segurança dos Webhooks
Protegendo o seu Endpoint
Para que o RRSign | Portal de Assinaturas possa se comunicar com a sua aplicação após qualquer evento no processo de assinatura, você precisará de uma URL pública acessível. Para a própria segurança da sua aplicação, é necessário que a URL fornecida seja protegida contra requisições maliciosas.
Sendo assim, sugerimos a utilização de HTTPS na URL do seu webhook.
HMAC
HMAC é uma forma de validar a integridade das informações transmitidas entre aplicações através de uma chave secreta compartilhada entre as partes.
Quando um novo webhook é cadastrado, automaticamente é gerado um código security_token. O objetivo dele é permitir que se tenha certeza de que o webhook foi enviado pela RRsign e que os dados não foram comprometidos.
A cada disparo do webhook, a RRSign calcula a soma do Body da requisição com o Secret e adiciona essa informação ao cabeçalho. Exemplo: Content-Hmac: 20dbdb06a522fb5046722c671bcf31f12be45485c
O servidor que receber a requisição deve fazer o mesmo cálculo de para verificar se a requisição de fato veio da RRsign e de que os dados não foram comprometidos. Para isso, basta calcular a soma do Body da requisição recebida com o security_token já conhecido. O valor deve ser igual ao enviado no cabeçalho da requisição.
Obs.: Você pode atualizar o security_token do webhook a qualquer momento.