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

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

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

[
  {
    "id": "0001",
    "folder_type": "Contratos"
  },
  {
    "id": "0002",
    "folder_type": "Funcionários"
  }
]

Posição do Signatário

[
  {
    "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

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

{
  "draft": "true"
}

{
  "sequence": "true"
}

{
  "stakeholder": {
    "type": "PF",
    "name": "Felipe Pereira Oliveira",
    "documentation": "123.456.789-10"
  }
}

{
  "documents": [
    {
      "title": "Contrato de Serviços",
      "content": "DQolUERGLTEuNwoxIDAgb2J[...]"
    },
    {
      "title": "Contrato de Renovação",
      "content": "MyAwIFIgPj4KZW5kb2JqCja[...]"
    }
  ]
}

{
  "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": [
    {
      "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.

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.