Pular para o conteúdo principal

Guia de Integraçã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 guia apresenta as opções de integração para que sua aplicação aproveite ao máximo o potencial do Signer.

Novo por aqui?

Se é a sua primeira integração, comece pelos Primeiros passos, que levam você do zero ao primeiro documento assinado em cerca de 15 minutos. Este guia serve como referência dos casos de uso.

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 as requisições:

X-Api-Key: sua-aplicacao|xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx

Toda chave de API está associada a 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: se você tem permissão para criar aplicações na organização, crie uma aplicação em Aplicações e gere a chave com o botão Chaves dela, como mostram os Primeiros passos. Caso contrário, peça uma chave ao administrador da sua instância.

Bibliotecas cliente​

A Lacuna publica uma biblioteca cliente da API para .NET, Java, Node.js e PHP. Você cria o cliente com a URL da sua instância do Signer e a chave de API, e chama as APIs pelos métodos dele. Também é possível chamar a API REST diretamente de qualquer linguagem, como fazem os Primeiros passos com curl.

LinguagemPacoteVersãoInstalação
.NET (.NET Framework 4.5 ou posterior, .NET Standard 2.0)Lacuna.Signer.Client1.24.0dotnet add package Lacuna.Signer.Client
Javacom.lacunasoftware.signer:signer-client2.14.0Gradle: implementation 'com.lacunasoftware.signer:signer-client:2.14.0'
Node.jssigner-node-client1.1.0npm install signer-node-client
PHPlacuna/signer-client1.4.10composer require lacuna/signer-client

Os exemplos no GitHub usam essas bibliotecas, com um cenário por caso de uso deste guia. Para embutir a tela de assinatura na sua página web, use a biblioteca JavaScript lacuna-signer-widget: veja Assinatura embutida.

Como o fluxo funciona​

Na prática, uma integração com o Signer segue quatro etapas. Cada etapa tem uma página dedicada neste guia:

  1. Criar documentos: envie o arquivo, monte o fluxo de participantes e (opcionalmente) assine dentro da sua própria aplicação.
  2. Acompanhar documentos: verifique o status, envie lembretes e receba notificações por webhook.
  3. Baixar e listar: obtenha as versões do documento e liste documentos por diferentes critérios.
  4. Validar assinaturas: valide as assinaturas por chave de validação ou pelo arquivo assinado.

E, ao longo da vida do documento, você pode precisar de operações de ciclo de vida: cancelar, recusar, enviar nova versão ou deletar.

Casos de uso​

Caso de usoO que você faz
Criar documentosUpload, criação do fluxo, assinatura embutida, pré-posicionamento de assinaturas e envelopes (múltiplos arquivos)
Acompanhar documentosVerificar status do documento e dos participantes, enviar lembretes e configurar webhooks
Baixar e listarBaixar as diferentes versões do documento e listar documentos
Validar assinaturasValidar assinaturas por chave ou por arquivo assinado
Ciclo de vida do documentoCancelar, recusar, enviar nova versão e deletar

Respostas de erro​

As APIs respondem com estes códigos de status HTTP:

CódigoSignificado
200 (OK)Requisição processada. O corpo da resposta depende da API: veja a entrada dela na referência da API.
400 (Bad Request)Erro de sintaxe, por exemplo um campo obrigatório que não foi enviado.
401 (Unauthorized)A chave de API não foi enviada ou é inválida.
403 (Forbidden)A chave de API é válida, mas a aplicação dela não tem permissão para a operação pedida.
422 (Unprocessable Entity)Erro da API, por exemplo um ID de entidade que não foi encontrado. O corpo é um ErrorModel.

Um ErrorModel tem três campos:

CampoTipoConteúdo
codestringO código do erro. Teste este campo no seu código, e não a mensagem.
messagestringUma descrição do erro.
detailsobjeto, com valores stringInformações adicionais sobre o erro. Pode ser null.
{
    "code": "DocumentNotFound",
    "message": "...",
    "details": null
}

A referência da API lista os principais códigos de uma resposta 422: CertificateNotFound, DocumentNotFound, FolderNotFound, CpfMismatch, CpfNotExpected, InvalidFlowAction e DocumentInvalidKey. A lista não é completa, e novos códigos podem ser incluídos a qualquer momento sem aviso, então trate também os códigos que você não conhece. Outras páginas descrevem os códigos das suas operações, como DocumentHasNoSignatures ao baixar uma versão e MaxWebhooksLimitReached ao cadastrar um webhook.

Ver em Markdown