Pular para o conteúdo principal

Guia de Integração

Introdução​

O Signer é um portal de documentos que permite a realização de assinaturas digitais e eletrônicas bem como a criação de fluxos complexos. Este documento discute as possíveis opções de integração para que sua aplicação possa aproveitar ao máximo o potencial do Signer.

Autenticação​

Todas as chamadas de API exigem uma chave de acesso de API (API Key). Essa chave deve ser colocada no cabeçalho de todas requisições:

X-Api-Key: sua-aplicacao|xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx

Toda chave de API está associada uma Organização previamente cadastrada no Signer. Sendo assim, o escopo dessa chave fica restrito àquela organização, isto é, aquela chave só permitirá acessar/criar documentos daquela organização.

observação

Para obter uma chave de API entre em contato com o administrador da sua instância.

Opções de integração​

Escolha um dos casos de uso abaixo:

Assinar um documento​

Para assinar um documento siga o passo a passo abaixo:

1- Faça o upload do arquivo a ser assinado usando a API de Upload (POST /api/uploads). O arquivo deve ser enviado com uma requisição multipart/form-data. Será retornado um ID de upload que identifica aquele arquivo:

{
	...
	"id": "3fa85f64-5717-4562-b3fc-2c963f66afa6"
}

Alternativamente pode ser utilizada a API simplificada de Upload (POST /api/uploads/bytes), na qual os bytes podem ser enviados em formato Base64.

2- Crie um documento à partir do upload usando a API de Criação de Documentos. Nessa chamada você deve montar o fluxo do documento, isto é, definir quais serão os participantes do documento e em qual ordem devem tomar suas ações:

POST /api/documents

{
	"files": [
	{
		"displayName": "Contrato Integração", //Nome que será dado ao documento criado
		"id": "3fa85f64-5717-4562-b3fc-2c963f66afa6", //ID do upload
		"name": "Contrato.pdf", //Nome do arquivo original
		"contentType": "application/pdf" //mime type do arquivo original
	}
	],
	"flowActions": [
	{
		"type": "Signer",//Tipo do participante, nesse caso, assinante
		"step": 1,//Ordem de assinatura
		"user": {
		"name": "John Wick",//Nome do participante
		"identifier": "81976153069",//CPF do participante
		"email": "john.wick@mailinator.com",//Email do participante
		},
		"allowElectronicSignature": true //Permite assinatura eletrônica
	}
	]
}
dica

Você pode criar mais de um documento na mesma chamada de criação, adicionando quantos arquivos forem necessários. Nesse caso, todos documentos terão o mesmo fluxo.

A resposta retornará o ID do documento criado associado ao ID do upload, assim você sabe exatamente qual documento corresponde a qual upload:

[
	{
	"uploadId": "3fa85f64-5717-4562-b3fc-2c963f66afa6",
	"documentId": "b12cb1b2-5d6e-40b2-a050-097d068c4c11"
	}
]

Ao criar o documento, o Signer automaticamente notifica os participantes adicionados no fluxo seguindo a ordem especificada.

Cada participante receberá um e-mail com um link que permitirá a assinatura/aprovação do documento.

dica

Não é preciso se autenticar para assinar ou aprovar o documento.

Para mais detalhes sobre esse caso de uso, veja nossos exemplos no github:

Assinatura em sua própria aplicação​

Caso você queira realizar a assinatura do documento em sua própria aplicação, você pode usar a opção de Assinatura Embutida.

Para isso, você deve seguir os mesmos passos exibidos na seção anterior, no entanto, ao enviar o documento, recomenda-se adicionar o parâmetro disablePendingActionNotifications com valor true. Dessa forma, não serão enviadas notificações para os participantes.

Após a criação do documento, utilize o ID do documento para obter a URL de Assinatura usando a API de URL de Ação:

POST /api/documents/b12cb1b2-5d6e-40b2-a050-097d068c4c11/action-url

{
	//devem ser enviadas informações que identifiquem o participante desejado
	"identifier": "81976153069",
	"emailAddress": "john.wick@mailinator.com"
}

Caso o signatário tenha permitido assinatura eletrônica (usando o parâmetro allowElectronicSignature = true no upload do documento), é possível exigir que ocorra a confirmação do e-mail dele por meio de um código de acesso no momento da assinatura. Para isso, deve ser definido requireEmailAuthentication como mostrado abaixo:

POST /api/documents/b12cb1b2-5d6e-40b2-a050-097d068c4c11/action-url

{
	//The information must be sent to identify the participant
	"identifier": "81976153069",
	"emailAddress": "john.wick@mailinator.com"
	// Se a assinatura for eletrônica e esse parâmetro for true, requer confirmação de e-mail com código para completar a assinatura.
	"requireEmailAuthentication": true
}

A resposta irá apresentar duas URLs:

{
	//URL para redirecionar o usuário para a página de assinatura no Signer
	"url": "https://...",
	//URL para usar com o Widget de assinatura
	"embedUrl": "https://..."
}

Uma vez obtida a URL embedUrl, utilize o Widget de assinatura para exibir a página de assinatura do Signer na sua aplicação. A página Assinatura embutida descreve como utilizar o Widget.

Para mais detalhes sobre esse caso de uso, veja nossos exemplos no github:

Como pré-posicionar uma assinatura no documento​

Durante a criação de um documento, é possível posicionar as assinaturas de cada usuário em um determinado local deste mesmo documento. Todas as definições de atributos são feitas durante a criação do flowAction. Há opções para definir a localização da assinatura em uma página, bem como a pagina na qual deseja pré-posicionar uma assinatura.

Para mais detalhes sobre esse caso de uso, veja nossos exemplos no github:

Verificar o status de um documento​

Para verificar o status de um documento é preciso conhecer o seu ID. Em seguida, basta fazer uma chamada à API de Detalhes do Documento:

GET /api/documents/b12cb1b2-5d6e-40b2-a050-097d068c4c11

{
	"id": "b12cb1b2-5d6e-40b2-a050-097d068c4c11",
	"name": "Contrato Integração",
	"status": "Concluded",
	"creationDate": "2019-08-18T16:26:03.372Z",
	"updateDate": "2019-08-18T16:26:03.372Z",
	...
	"flowActions": [
		{
			"id": "4bf61c68-eaf1-455f-b4a1-6141554f1dae",
			"type": "Signer",
			"status": "Completed",
			"step": 1,
			...
			"user":
			{
				"id": "4d961566-9b03-450c-b144-930e0294bac2",
				"name": "John Wick",
				"identifier": "81976153069",
				"email": "john.wick@mailinator.com"
			},
			"title": "Parte",
			"allowElectronicSignature": true
		}
	]
}
  • Para saber se o documento está concluído, verifique a propriedade status corresponde a Concluded.
  • Para saber se um participante assinou/aprovou, verifique se a propriedade status corresponde a Completed para o elemento da lista de ações (flowActions) que corresponde a ele.

Adicionalmente, você pode configurar um Webhook que será disparado toda vez que um documento de sua organização for concluído, aprovado, recusado ou assinado. Para isso, acesse a tela da Organização e registre a URL desejada na opção Integração:

Webhook

Para mais detalhes sobre esses casos de uso, veja nossos exemplos no github:

Enviar lembretes de assinatura​

Uma vez verificado o status de um participante, conforme mostrado no caso de uso de Verificação de status, você pode enviar lembretes periódicos para participantes do fluxo que ainda não completaram uma ação usando a API de Envio de Lembretes. Para isso, informe o ID do documento e o ID da ação do participante (flowActionId):

POST /api/notifications/flow-action-reminder

{
	"documentId": "b12cb1b2-5d6e-40b2-a050-097d068c4c11",
	"flowActionId": "4bf61c68-eaf1-455f-b4a1-6141554f1dae"
}

Para mais detalhes sobre esse caso de uso, veja nossos exemplos no github:

Download das versões de um documento​

A partir do momento que um documento foi criado, é possível fazer o download de diferentes tipos de versões deste mesmo documento (de acordo com o estágio no qual ele se encontra). Caso queira fazer o download do documento, utilize a API de Download de Documentos.

GET /api/documents/b12cb1b2-5d6e-40b2-a050-097d068c4c11/content?type=Original

As opções disponíveis para download são:

  • Arquivo Assinado
  • Versão para impressão
  • Etiquetas de assinatura
  • Marcas de Assinatura
  • Arquivo Original

Existem dois métodos com seus respectivos tipos de retorno de dados: O primeiro retornará uma Stream de dados referente ao documento e o segundo retornará o documento em um vetor de bytes[].

Para mais detalhes sobre esse caso de uso, veja nossos exemplos no github:

Listar documentos​

É possível listar os documentos de acordo com padrões e necessidades diferentes. O parametros utilizados estão listados na API de Listagem de Documentos. Os tipos de listas que podem ser retornadas estão identificados abaixo:

  • Documentos pendentes para um determinado participante
  • Documentos concluídos
  • Listar por pastas
  • Listar por organização

Para mais detalhes sobre esse caso de uso, veja nossos exemplos no github:

Validar assinaturas de um documento​

Você pode validar as assinaturas de um documento de duas formas: com a chave de validação do documento (caso ele tenha sido assinado nesta instância do Signer) ou com o arquivo assinado.

Validação de documento com chave de validação​

Para validar um documento com chave de validação, use a API de Validação de Chave informando a chave correspondente.

Serão retornados os dados básicos do documento e as informações de cada uma das assinaturas encontradas naquele documento:

GET /api/documents/keys/AX4F8FV8NNAX25TENE2S/signatures

{
	"id": "b12cb1b2-5d6e-40b2-a050-097d068c4c11",
	"name": "Contrato Integração",
	"filename": "Contrato.pdf",
	"mimeType": "application/pdf",
	"isConcluded": true,
	...
	"creationDate": "2020-08-18T16:38:40.538Z",
	"updateDate": "2020-08-18T16:38:40.538Z",
	"signers": [
		{
			"subjectName": "John Wick",
			"emailAddress": "john.wick@mailinator.com",
			"issuerName": "Lacuna CA",
			"identifier": "81976153069",
			"companyName": null,
			"companyIdentifier": null,
			"isElectronic": false,
			"signingTime": "2020-08-18T16:38:40.538Z",
			"certificateThumbprint": "a0sRR9cWOc0PORMhTBg49ub/5BO3W5vWQ1w7+YquK5g=",
			...
			"validationResults":
			{
				...
				"isValid": true
			}
		}
	]
}

Validação de documento com arquivo assinado​

Para validar um documento assinado é preciso fazer primeiro o upload do arquivo assinado usando a API de Upload ou API simplificada de Upload (POST /api/uploads/bytes) assim como informado na seção Assinar um Documento.

Em seguida, utilize a API de validação de arquivo assinado.

POST /api/documents/validate-signatures

{
  "fileId": "f5ea05d7-0a5f-4933-a6d6-9a8aa3955b14",
  "mimeType": "application/pdf"
}

Serão retornados os dados de cada uma das assinaturas encontradas no documento.

[
	{
		"subjectName": "John Wick",
		"emailAddress": "john.wick@mailinator.com",
		"issuerName": "Lacuna CA",
		"identifier": "81976153069",
		"companyName": null,
		"companyIdentifier": null,
		"isElectronic": false,
		"signingTime": "2020-08-18T16:38:40.538Z",
		"certificateThumbprint": "a0sRR9cWOc0PORMhTBg49ub/5BO3W5vWQ1w7+YquK5g=",
		...
		"validationResults":
		{
			...
			"isValid": true
		}
	}
]

Deletar documento​

Para deletar um documento você precisa ter acesso ao ID deste mesmo documento e fazer um chamada do tipo DELETE.

DELETE /api/documents/b12cb1b2-5d6e-40b2-a050-097d068c4c11

Para mais detalhes sobre esse caso de uso, veja nossos exemplos no github:

Cancelar documento​

Caso queira cancelar um documento, é necessário enviar o ID do documento através de uma requisição do tipo POST junto ao campo reason, conforme o exemplo abaixo:

POST /api/documents/b12cb1b2-5d6e-40b2-a050-097d068c4c11/cancellation

{
    "reason": "This is a document cancellation"
}

Para mais detalhes sobre esse caso de uso, veja nossos exemplos no github:

Recusar documento​

Para recusar um documento, é necessário enviar o ID do documento através de uma requisição do tipo POST junto ao campo reason, conforme o exemplo abaixo:

POST /api/documents/b12cb1b2-5d6e-40b2-a050-097d068c4c11/refusal

{
    "reason": "This is a document refusal"
}

Para mais detalhes sobre esse caso de uso, veja nossos exemplos no github:

Enviar nova versão documento​

É possível enviar uma nova versão do documento para um documento já criado. Portanto, é necessário enviar o ID do documento, através de uma requisição do tipo POST, junto ao arquivo relativo a nova versão. Vale ressaltar que o fluxo de assinaturas será reiniciado.

Para mais detalhes sobre esse caso de uso, veja nossos exemplos no github:

Mesclar múltiplos arquivos em um único documento​

É possível fazer o upload de múltiplos arquivos e mesclar todos em um só documento (envelope). Para fazer isso, é necessário a adição do parâmetro isEnvelope=true e um nome de envelope EnvelopeName. É importante ressaltar que a mesclagem só funcionará se todos os arquivos enviados forem PDFs.

Para mais detalhes sobre esse caso de uso, veja nossos exemplos no GitHub: