we are developers

iMaster Developers

iMaster DevelopersPowered by:

APIs e Microsserviços

14 jun, 2017

Como usar a API de gerenciamento de documentos everSign eSignature SAAS

Dave Smith

Tem 6 artigos publicados com 3600 visualizações desde 2015

Dave Smith
Publicidade

 

A API everSign eSignature SAAS permite que os aplicativos gerenciem documentos a serem assinados por várias partes na Web.

Além do painel everSign SAAS, você pode usar a API eSignature que eles fornecem para gerenciar seus documentos em seu próprio site.

Leia este artigo para saber como gerenciar documentos de um site PHP a serem assinados usando a API da everSign.

Introdução

Apresento o serviço everSign em um artigo anterior, Gerenciamento de documentos digitais com Eversign SAAS. No artigo de hoje, daremos uma olhada na API que eles fornecem e como usar o pacote Assinatura de Documentos everSign PHP com ele.

Se você deseja acompanhar e experimentar alguns dos recursos você mesmo, primeiro deve baixar o pacote e depois se inscrever para uma conta em https://eversign.com/signup. O plano gratuito permitirá que você teste o serviço da API com um número limitado de solicitações de API por mês.

Depois de ter uma conta, insira suas credenciais de API específicas no arquivo eversign.class.php. Você pode encontrar suas credenciais selecionando “desenvolvedor” no menu à esquerda do painel de controle.

protected $apiKey = 'YOUR KEY HERE';
protected $busID = 'BUSINESS ID HERE';

Substitua o texto em caixa alta por suas credenciais para cada propriedade. Se você configurou mais de um negócio, basta usar sua ID de negócios principal aqui. Você poderá mudar o negócio mais tarde, se você precisar.

Exemplo de instanciação e uso básico

Você precisará colocar o arquivo de classe em um local acessível à web e, em seguida, incluí-lo e instanciá-lo em seu arquivo de script.

include('eversign.class.php');
$eSign = new everSign(true);

O parâmetro que está sendo definido como true é se vamos usar a API com SSL (seguro) ou apenas HTTP padrão (não seguro). Neste caso, estamos usando o modo seguro. No entanto, você pode alterar esse valor para false para usar o modo não seguro.

A API possui vários pontos finais que executam ações diferentes. Estaremos olhando para todos eles à medida que avançamos neste artigo. Eles são:

  • business or b as a shorthand
  • document or d
  • send_reminder or s
  • download_raw_document or rd
  • download_final_document or fd
  • file or f

Obtendo uma lista de seus negócios

Usamos o método setEndPoint para dizer à classe qual ponto final usaremos. Para o primeiro exemplo, estaremos usando o ponto final do negócio que retorna uma resposta contendo todos os negócios associados à nossa conta.

<?php

include('eversign.class.php');
$eSign = new everSign( true );
$eSign->setEndPoint( 'b' );
$eSign->getResponseCurl( false );
if( !empty($eSign->errorCode) ){
    echo 'error ' . $eSign->errorCode . ': ' . $eSign->errorText;
    die;
}
echo '<pre>';
var_dump($eSign->response);
echo '</pre>';
?>

Observe que estamos usando a abreviatura ‘b’ para o ponto final. Também poderíamos usar o nome completo do ponto final do ‘negócio’ se quiséssemos.

Na próxima linha, estamos usando o método getResponseCurl para armazenar a resposta da API. Existe um método semelhante chamado getResponse. A diferença entre os dois é que um usará CURL e o outro usará um handler de arquivos para obter a resposta.

Estou usando o método CURL porque funciona melhor em uma conexão segura. Se você usa o método padrão e está recebendo avisos de segurança e erros, use CURL em vez disso.

O parâmetro nos métodos getResponseCurl e getResponse é para incluir a ID do negócio ou não. Nesse caso, ele está configurado como false, pois este ponto final não requer a ID do negócio, ele está retornando todos os negócios.

Se houve um erro, ele será exibido. Caso contrário você deve ver um objeto contendo informações em todos os seus negócios.

Obtendo uma lista de seus documentos e modelos

Utilizamos o ponto final do ‘documento’ para obter detalhes sobre nossos documentos, que incluirão todas as configurações para cada documento recuperado. Observe que você precisará ter documentos já armazenados para recuperar informações sobre eles.

<?php

include('eversign.class.php');
$eSign = new everSign( true );
$eSign->setEndPoint('d');
$eSign->setParam( 'type', 'all');
$eSign->getResponseCurl( false );
if( !empty($eSign->errorCode) ){
    echo 'error ' . $eSign->errorCode . ': ' . $eSign->errorText;
    die;
}
echo '<pre>';
var_dump($eSign->response);
echo '</pre>';
?>

Depois de definir o nosso ponto final, introduzimos um novo método, setParam. Isso é usado para definir os parâmetros que serão enviados com nossa solicitação para a API. Estamos definindo o parâmetro ‘tipo’ como um valor de ‘tudo’. Existem vários valores que podem ser enviados:

  • all = todos os documentos
  • my_action_required = documentos que exigem sua ação
  • waiting_for_others = documentos aguardando a ação de outro signatário
  • completed = documentos completos
  • drafts = documentos ainda no estágio de rascunho
  • canceled = documentos cancelados

Se você tem uma conta premium que suporte modelos, você também pode usar o parâmetro ‘tipo’ para recuperar aqueles que estejam usando os seguintes valores:

  • templates = todos os modelos ativos
  • templates_archived = modelos arquivados
  • template_drafts = modelos ainda na fase de rascunho

Trabalhando com um único documento ou modelo

Se você executou a solicitação para obter seus documentos, você notará uma hash de documento que é basicamente o ID para esse documento.

Se você estiver olhando para um documento em seu painel de controle everSign, o hash pode ser encontrado como a última parte da url. Para obter os detalhes do documento único, usaremos o ponto final do ‘documento’ e definiremos o parâmetro document_hash em vez do parâmetro ‘tipo’ usado anteriormente.

$eSign->setParam( 'document_hash', 'your-document-hash-here');

A resposta conterá tudo o que você precisa saber sobre um documento a partir de suas configurações, arquivos associados, assinantes, destinatários, status, campos e entradas de registro.

Se você deseja cancelar um documento, você incluirá o parâmetro document_hash e um parâmetro ‘cancelar’ configurado para um valor de ‘1’ na mesma solicitação.

$eSign->setParam('cancel','1');

Criando um novo documento

O processo para criar um documento através da API pode variar de simples a extremamente elaborado.

Os arquivos associados e todas as configurações são postados no ponto final do ‘documento’. Eu recomendo que você se familiarize com a seção para criar documentos em https://eversign.com/api/documentation/methods#create-document. Felizmente, o pacote Assinatura de Documentos everSign PHP cuidará do trabalho pesado para você, então vou focar nos métodos disponíveis.

setDocParams( $params ) – este método passa uma matriz dos parâmetros básicos do documento e é usado assim:

$doc = array(
    'is_draft' => 1,
    'title' => 'My Document Title'
);
$eSign->setDocParams($doc);

addFile( $name, $file ) – este método adiciona um arquivo local e o codifica corretamente. Você forneceria o nome que você deseja que ele armazene no everSign e o caminho completo para o arquivo como parâmetros. Ele retornará uma ID de arquivo local que será usada para atribuir campos a este arquivo, mais sobre isso em um momento.

addFilebyID( $name, $id ) – este método adiciona um arquivo que você carregou anteriormente para everSign. Você forneceria o nome que você deseja que ele armazene no everSign e a ID do arquivo que o everSign atribuiu ao arquivo que você carregou. Examinaremos os carregamentos de arquivos em outra seção. Ele retornará uma ID de arquivo local que será usada para atribuir campos a este arquivo.

addFilebyURL( $name, $url ) – este método adiciona um arquivo que é acessível à web. Você forneceria o nome que você deseja que ele armazene no EverSign e a URL completa onde everSign pode recuperá-lo. Ele retornará uma ID de arquivo local que será usada para atribuir campos a este arquivo.

addField( $fileID, $params ) – cada arquivo tem a capacidade de ter campos diferentes adicionados a ele. Estes podem incluir qualquer tipo de campo suportado com as configurações associadas. Você forneceria a ID do arquivo local retornada pelos métodos de arquivo de adição mencionados acima e os parâmetros serão uma matriz de campos e suas configurações. Observe que, se um documento não contém nenhum campo de assinatura, uma página de assinatura será criada para você no final do documento.

addSigner( $name, $email, $pin=”, $message=”, $order=0, $id=0, $role=” ) – este método irá adicionar um assinante ao documento. Você deve especificar seu nome e endereço de e-mail e, opcionalmente, fornecer um pin de segurança, mensagem, ordem para a página de assinatura e para modelos uma id e função de usuário.

addCC( $name, $email, $role=” ) – este método irá adicionar um destinatário de e-mail ao documento. Você deve especificar seu nome e endereço de e-mail e, opcionalmente, fornecer sua função para os modelos.

addMeta( $key, $value ) – esse método adicionará pares valor-chave de meta ao documento. Você especifica a chave e o valor.

addTemplateField( $id, $value ) – este método irá adicionar campos ao usar um modelo. Você especifica o ID do campo do modelo e o valor.

Uma vez que todas as propriedades do documento foram definidas, você envia o documento criado usando o método sendDocument(). O pacote publicará os campos necessários para o ponto final do ‘documento’ usando CURL.

Carregando um arquivo

Conforme mencionado na seção anterior, você pode fazer o carregamento de um arquivo que, posteriormente, pode ser usado como um novo arquivo de documentos.

Para realizar isso, você usaria um formulário html padrão com multipartidário/dados de formulário criptografados e um campo de arquivo.

Poste o arquivo em seu script e use o método uploadCurl($field) para enviá-lo para a API. O parâmetro de campo é o nome que você usou para o seu campo de arquivo. A API retornará a ID do arquivo que você pode, então, usar no método addFilebyID.

<?php

include('eversign.class.php');

$eSign = new everSign(true);
if( isset($_FILES[ 'myfile' ][ 'tmp_name' ]) ) {
    $eSign->setEndPoint( 'f' );
    $eSign->uploadCurl( 'myfile' );
    if( !empty($eSign->errorCode) ){
        echo 'error ' . $eSign->errorCode . ': ' . $eSign->errorText;
        die;
    }
    $file_id = $eSign->response->file_id;
    $doc = array(
        'is_draft' => 1,
        'title' => 'Myfile Upload'
    );
    $eSign->setDocParams( $doc );
    $eSign->addFilebyID( 'Upload Test', $file_id);
    $eSign->addSigner( 'Joe Test', 'joe_test@yourdomain.com');
}
$eSign->sendDocument();
echo '<pre>';
var_dump( $eSign->response );
echo '</pre>';
die;
?>
<!DOCTYPE html>
<html>
<head>
<title>File Upload</title>
</head>
<body>
<form method="post" enctype="multipart/form-data">
<input type="file" name="myfile"><br>
<input type="submit" value="Send File">
</form>
</body>
</html>

O exemplo acima irá carregar o arquivo que você selecionou no formulário e, em seguida, criar um novo rascunho usando esse arquivo.

Exibindo documentos

Existem dois pontos finais usados para recuperar os documentos no formato Adobe Acrobat (PDF).

Para recuperar e visualizar o documento final em seu navegador, você definiria o ponto final para download_final_document e definiria o parâmetro document_hash. Você, então, chama o método displayPDF ($ name = ”), nomeando o arquivo se desejar.

<?php

include('eversign.class.php');

$eSign = new everSign(true);
$eSign->setEndPoint('fd');
$eSign->setParam( 'document_hash', 'your-document-hash-here');
$eSign->setParam('audit_trail', '1');
$eSign->displayPDF('myfile');
?>

Observe que também definimos o parâmetro audit_trail para 1, o que irá anexar a trilha de auditoria ao nosso documento final. Esta opção só está disponível ao exibir um documento final.

Também podemos exibir o documento raw alterando o nosso ponto final para download_raw_document.

$eSign->setEndPoint('rd');

Tenha em mente que não há trilha de auditoria para documentos raw, de modo que o parâmetro não seria definido nesta instância.

Conclusão

Isso abrange os conceitos básicos para interagir com a API everSign eSignature. Existem alguns outros recursos e métodos que merecem destaque.

sendReminder( $hash, $id ) – este método enviará um lembrete para o assinante. Você especifica o hash do documento e o identificador dos assinantes. Você também deve definir o ponto final para send_reminder.

setBusID($id) – esse método permitirá que você altere a ID de negócios padrão se precisar fazê-lo.

resetParams() – este método irá redefinir todos os parâmetros previamente definidos pelo método setParam.

Eu entendo que isso é um pouco demais para absorver em uma leitura. Familiarize-se com a forma como os documentos everSign são gerenciados a partir do painel, leia a documentação da API e, em seguida, teste a API e tudo começará a fazer sentido rapidamente.

 

***

Dave Smith faz parte do time de colunistas internacionais do iMasters. A tradução do artigo é feita pela Redação iMasters, com autorização do autor, e você pode acompanhar o artigo em inglês no link: https://www.phpclasses.org/blog/package/10288/post/2-How-to-use-the-everSign-eSignature-SAAS-Document-Management-PHP-API.html

De 0 a 10, o quanto você recomendaria este artigo para um amigo?

Dave Smith
Saiba mais

Dave Smith

edit6 Artigo(s)

É um desenvolvedor norte-americano que trabalha há anos com PHP, web design, MySQL, JavaScript, Linux, Windows, Smarty e jQuery. Também é autor do site PHP Classes.