Como facilitar a integração da Zapsign com SDK em Java em 3 passos

Se você chegou até aqui, já deve ter conhecido a Zapsign e sua maravilhosa documentação, mas deve ter pensado: será que não existe uma maneira mais fácil de fazer a integração da ZapSign com SDK em Java? A resposta para essa pergunta é sim!

Continue a leitura deste artigo para saber o seu funcionamento e como colocá-la em prática!

O que é um SDK e como ele pode ajudar?

Na integração com a Zapsign, você deve criar um JSON com os dados necessários e fazer uma requisição para nossa api. Mas, o que deve ter nesse JSON? Como deveria mandar essa requisição?

A resposta está no Software Development Kit (ou kit de desenvolvimento de softwares), isto é, um conjunto de ferramentas desenvolvidas para auxiliar desenvolvedores na criação de aplicativos.

Nosso SDK vai deixar todas essas perguntas mais simples, pois disponibilizamos para você tudo que é necessário para utilizar de forma clara e simples a nossa aplicação.

Certo, mas como fazer isso?

Para começar, precisamos primeiro de uma aplicação Java Maven. Ao usar o IntelliJ, basta seguir o comando File / New / Project e criar esse projeto com Maven Archetype, tal como mostra o print abaixo.

Com o projeto feito, precisamos incluir a dependência da Zapsign no .pom do projeto:

<!-- https://mvnrepository.com/artifact/br.com.zapsign/zapsign_sdk -->
<dependency>
    <groupId>br.com.zapsign</groupId>
    <artifactId>zapsign_sdk</artifactId>
    <version>1.0-3</version>
</dependency>

Lembre-se de sempre adicionar a versão mais atual.

Com isso, você está pronto para utilizar todas as funcionalidades.

Passo a passo para integração do SDK em Java

Digamos que você tenha um contrato em PDF na nuvem e queira mandar para duas pessoas assinarem. Como traduzir isso para nosso SDK? Confira os passos seguintes para descubrir.

1. Construa o documento

Tentamos dar os nomes mais intuitivos para cada funcionalidade. Então, se você deseja construir um documento via upload de PDF, a classe usada é a DocFromPdf.

Aqui estamos construindo um documento em modo produção (sandbox = false), com o nome “My Contract”, linguagem “pt-br” e o seguinte link para o PDF:

“https://zapsign.s3.amazonaws.com/2022/1/pdf/63d19807-cbfa-4b51-8571-215ad0f4eb98/ca42e7be-c932-482c-b70b-92ad7aea04be.pdf“.

Mas, todo o contrato precisa de assinantes, correto? Para isso, construiremos objetos da classe Signer e guardaremos em uma lista.

Com isso, conseguimos criar dois signatários: um mais simples, apenas com o nome, e outro com mais dados.

Para saber todas as opções de signatários, dê uma olhada na nossa documentação. No final, adicionamos esses assinantes em uma lista e incluímos na criação do documento.

Até aqui, temos todos os dados necessários para a criação do documento na Zapsign, porém precisamos saber em qual conta vamos criar esse documento.

2. Configure a autenticação

Precisamos do seu token de api da sua conta Zapsign. Então, entre em zapsign.com.br, faça login na sua conta, entre em configurações e selecione o sub item Integração.

Lembramos que apenas administradores e proprietários da conta têm acesso às configurações.

Vamos salvar esse token no nosso código para utilizá-lo mais tarde:

Com esse token, já conseguimos saber qual é a sua conta. Mas, ainda precisamos enviar esse documento para nossa API.

3. Envie os dados do documento para assinatura

Nesse ultimo passo, precisamos fazer uma requisição ao enviar tudo que criamos. Para isso, já deixamos pronto a classe DocRequests que contém todos os métodos referentes à criação, remoção, edição e listagem de documentos.

Para nosso caso específico, usaremos o método createDocFromUploadPdf, adicionando o token da sua conta e o documento criado anteriormente.

Esse método ja vai criar o documento na sua conta e retornar todos os dados em uma classe clamada DocResponse. Nesse exemplo convertemos essa classe em JSON, por meio do JsonConverter, apenas para printar na tela. Mas, você pode utilizar a classe da forma que quiser.

Essa resposta contém dados importantes, como o identificador único do documento na Zapsign e os dados dos signatários.

Quais são as etapas seguintes?

Agora que você entendeu os três passos necessários para dar início à integração, vejamos agora o que você deve realizar em seguida.

O que fazer com a resposta?

Muitos clientes têm a necessidade de enviar um e-mail próprio para os assinantes. Para isso, podemos utilizar a seguinte ideia:

Dentro da resposta, podemos percorrer todos os signatários ao usar um for no docResponse.getSigners() e enviar um email da sua própria aplicação. Em seguida, passamos apenas o link para a assinatura, que está salvo dentro do signer.getSign_url().

Este é só um dos muitos exemplos que podemos fazer com os dados na nossa aplicação. Agora, é deixar a imaginação fluir.

Webhooks

Ok, conseguimos fazer um documento. Mas, precisamos saber quando um signatário assinou o documento, certo?

Pois então, a aplicação da Zapsign tem três webhooks prontos para uso: um na criação de documentos, outro na assinatura dos signatários e o último quando um documento é deletado.

Temos uma parte específica para explicar como configurar webhook na nossa documentação.

Outros Requests

Além de criar um documento via PDF na nuvem, é possível fazer diversas funcionalidades. Todas elas estão listadas e exemplificadas na nossa documentação do SDK.

Exemplo de código

package org.example.tests.docs;

import body.doc.DocFromPdf;
import body.signer.Signer;
import docs.DocRequests;
import response.DocResponse;
import services.JsonConverter;

import java.io.IOException;
import java.util.ArrayList;
public class CreateDocFromUploadPdf {
    public static void main(String[] args) throws IOException, InterruptedException  {
        String apiToken = "0a4d6893-f431-4d83-af80-...";

        Signer signer1 = Signer.builder()
                .name("My First Signer")
                .build();

        Signer signer2 = Signer.builder()
                .name("My Second Signer")
                .email("[email protected]")
                .lock_email(true)
                .lock_phone(true)
                .phone_country("55")
                .phone_number("99999999999")
                .auth_mode("assinaturaTela")
                .send_automatic_email(false)
                .send_automatic_whatsapp(false)
                .build();

        ArrayList<Signer> signers = new ArrayList<>();
        signers.add(signer1);
        signers.add(signer2);

        DocFromPdf docFromPdf = DocFromPdf.docFromPdfBuilder()
                .sandbox(false)
                .name("My Contract")
                .brand_primary_color("#000000")
                .lang("pt-br")
                .signers(signers)
                .url_pdf("https://zapsign.s3.amazonaws.com/2022/1/pdf/63d19807-cbfa-4b51-8571-215ad0f4eb98/ca42e7be-c932-482c-b70b-92ad7aea04be.pdf")
                .build();

        try {
            DocResponse docResponse = new DocRequests(apiToken).createDocFromUploadPdf(docFromPdf);
            String jsonDocResponse = new JsonConverter().docResponseToJson(docResponse);
            System.out.println(jsonDocResponse);
        }
        catch(Exception exceptionError) {
            System.out.println(exceptionError.getMessage());
        }
    }
}

Considerações finais

Uma integração entre duas aplicações tende a ser uma tarefa trabalhosa, mas eu espero que nosso SDK facilite o seu trabalho. Se precisar de alguma ajuda ou quer comentar sobre como você está usando essa ferramenta, deixe um comentário aqui.

Gostou da integração, mas ainda não conhece a Zapsign? Vamos resolver isso então! Para ver o que a Zapsign tem de bom para sua empresa, solicite um “tour” na nossa plataforma com um dos nossos atendentes!