Criar documento via Upload
A plataforma da ZapSign permite configurar cada signatário individualmente, definindo não apenas os dados de contato, mas também preferências de autenticação, mensagens e ordem de assinatura.
Neste artigo, vamos detalhar cada campo configurável para signatários ao criar um documento por upload de PDF ou um DOCX. Nesta seção: Configurando o Documento; Configurando Signatários; Exemplos de requesições prontas; O que faço com a resposta? Sobre o Base64;
Configurando documento
Na configuração do documento, você define as propriedades básicas para criar e gerenciar um documento na plataforma. Esses campos incluem o nome, status inicial, e URLs do arquivo original e assinado, formando a estrutura essencial do documento. Essa etapa garante que o documento esteja corretamente identificado e acessível ao longo de todo o processo de assinatura.Você deverá enviar os dados em JSON, bem como receberá eles nesse mesmo formato.
POST https://api.zapsign.com.br/api/v1/docs/
Headers
Authorization*
string
Api token a frente do texto "Bearer".
Ex: Bearer c7f35c84-7893-4087-b4fb-d1f06c23
Request Body
name
string
Título do documento. String de até 255 caracteres
url_pdf
string
Defina o PDF a ser assinado, a partir de uma URL pública com o arquivo. Aceitamos por enquanto apenas um arquivo no formato PDF, de até 10Mb.
base64_pdf
string
Alternativa ao url_pdf: Defina o PDF a ser assinado, a partir de um base64. Você deve converter o arquivo para uma string em base64 e nos enviar neste parâmetro (mais detalhes abaixo).
signers[name]
Array<Signer>
O campo 'signers' representa os signatários do documento, ou seja, quem irá assinar. A configuração de cada signatário esta abaixo.
É um array de objetos.
markdown_text
string
Aternativa ao url_pdf: Permite enviar um texto em Markdown para a criação do documento, facilitando a integração com IA e automações. Como exemplo, confira o ZapSign Agent OpenAI, que demonstra como agentes de IA podem utilizar essa funcionalidade.
url_docx
string
Alternativa ao url_pdf: Defina o Word (.docx) a ser assinado, a partir de uma URL pública com o arquivo. Aceita um arquivo no formato .docx, de até 10Mb.
base64_docx
string
Alternativa ao url_pdf: Defina o Word (.docx) a ser assinado, a partir de um base64. Você deve converter o arquivo para uma string em base64 e nos enviar neste parâmetro (mais detalhes abaixo).
lang
string
idioma do documento. Valores possíveis: "pt-br" (português), "es" (espanhol), "en" (inglês). Default: "pt-br"
disable_signer_emails
boolean
para desativar os e-mails enviados aos signatários, envie esse parâmetro como true. Default: false
brand_logo
string
(se deseja personalizar a logomarca da experiência de assinatura deste documento específico, envie a URL da imagem (precisa ser um link publicamente acessível).
Default: ""
brand_primary_color
se deseja personalizar a cor primária (do botão) da experiência de assinatura deste documento específico, envie em rgb ou hexadecimal.
Ex: "#0011ee".
Default: ""
brand_name
string
se deseja personalizar o nome do remetente dos e-mails enviados ao signatário, insira aqui o nome da marca. Por exemplo, se inserido "XPTO Advogados", o remetente do e-mail será "XPTO Advogados via ZapSign".
Max-length: 100 caracteres.
Default: ""
external_id
string
ID do documento na sua aplicação.
Default: ""
folder_path
string
caminho da pasta dentro da ZapSign em que o documento será colocado. Se as pastas não existirem, serão criadas automaticamente. Requisitos: (1) o folder_path pode ter até 255 caracteres, (2) cada pasta pode ter até 50 caracteres, (3) há um limite de 5 níveis de pasta.
Ex.: "/api/" ou "/pasta1/pasta2/pasta3/".
Default: "/" (sem pasta).
created_by
string
e-mail do usuário que será definido como criador do documento, para fins de organização interna. Caso o e-mail não exista ou não seja usuário da sua conta, este parâmetro será ignorado.
Default: ""
(documento terá como criador o proprietário da conta)
date_limit_to_sign
DateTime
Data limite para assinatura do documento.
Formatos aceitos:
YYYY-MM-DD
YYYY-MM-DDTH:m:s.ssssssZ
signature_order_active
boolean
Se verdadeiro, as assinaturas do signatário serão solicitadas sequencialmente.
Default: false
observers
array<string>
Representa os observadores do documento (limite de 20), ou seja, endereços de e-mails que serão notificados após a conclusão do fluxo de assinatura. É um array de strings.
reminder_every_n_days
integer
Representa o intervalo de dias entre os lembretes que serão enviados para os signatários.
allow_refuse_signature
boolean
Se verdadeiro, os signatários tem a opção de se recusar a assinar. Default: false.
disable_signers_get_original_file
boolean
Se verdadeiro, os signatários não tem a opção de baixar o documento original.
Default: false.
Metadata
Array
Metadados personalizados enviados na criação do documento, no formato de pares key e value. Essas informações aparecem apenas nos webhooks de criação, assinatura, recusa e exclusão.
folder_token
string
Se preenchido, este campo terá prioridade sobre folder_path. Ele define o diretório com base no token da pasta, que pode ser obtido acessando o seguinte endereço:
https://app.zapsign.com.br/conta/documentos?pasta=<token_da_pasta>
Se você ainda não souber o token, navegue até a pasta desejada a partir de:
https://app.zapsign.com.br/conta/documentos
e copie o valor do parâmetro pasta na URL após acessar a pasta.
{
"open_id": 5,
"token": "eb9c367a-e62f-4992-8360-b0219deaeecc",
"status": "pending",
"name": "oi",
"original_file": "https://zapsign.s3.amazonaws.com/pdf/62c2b027-d8fc-4392-xas75-f3c46c3cfc7a/d33336-4182-8c8b-ded5287e4c0f.pdf",
"signed_file": null,
"created_at": "2020-04-16T03:33:46.241747Z",
"last_update_at": "2020-04-16T03:33:46.241775Z",
"signers": [
{
"token": "921c115d-4a6e-445d-bdca-03fadedbbc0b",
"sign_url": "https://app.zapsign.com.br/verificar/921c115d-4a6e-445d-bdca-03fadedbbc0b",
"status": "new",
"name": "João da Silva",
"email": "",
"phone_country": "",
"phone_number": "",
"times_viewed": 0,
"last_view_at": null,
"signed_at": null
},
{
"token": "07fb0a0a-4b7d-49a5-bd7b-4958265c4e46",
"sign_url": "https://app.zapsign.com.br/verificar/07fb0a0a-4b7d-49a5-bd7b-4958265c4e46",
"status": "new",
"name": "Fulano Siclano",
"email": "",
"phone_country": "",
"phone_number": "",
"times_viewed": 0,
"last_view_at": null,
"signed_at": null
}
]
}Configurando signatários
Esses campos permitem ajustar a experiência de assinatura para cada pessoa envolvida. Personalizando cada signatário, desde o método de autenticação até as preferências de contato, ordem de assinatura e mensagens automáticas.
Documento - raiz do JSON:
Signers
auth_mode (string):
auth_modeDescriçãoCusto"assinaturaTela"
Assinatura diretamente na tela.
Sem custo
"tokenEmail"
Envio de token via e-mail para autenticação.
Sem custo
"assinaturaTela-tokenEmail"
Combinação de assinatura na tela e token enviado por e-mail.
Sem custo
"tokenSms"
Envio de token via SMS para autenticação.
R$0,10 por envio
"assinaturaTela-tokenSms"
Combinação de assinatura na tela e token enviado por SMS.
R$0,10 por envio
"tokenWhatsapp"
Envio de token via WhatsApp para autenticação.
5 créditos
"assinaturaTela-tokenWhatsapp"
Combinação de assinatura na tela e token enviado por WhatsApp.
5 créditos
"certificadoDigital"
Autenticação com certificado digital.
5 créditos
name (string): O nome do signatário. Obrigatório.
email (string): Você pode definir o e-mail do signatário
phone_country (string): Você pode definir o telefone (código do país) do signatário. Default: "" (sugestão: utilizar "55" para código do Brasil)
phone_number (string): Você pode definir o telefone (DDD + número) do signatário. Exemplo: "11998989222". Default: ""
require_cpf (boolean): Você pedir o CPF do signatário. Se não preencher o número de CPF com o parâmetro "cpf", o signatário preencherá essa informação na assinatura do documento e ela será registrada no relatório de assinaturas.Default: false
validate_cpf (boolean): se true valida o CPF, o nome e a data de nascimento na Receita Federal. Para utilizá-lo, é necessário preencher o campo "cpf", e o signatário preencherá a data de nascimento. Default: false.
cpf (string): Você informar o CPF do signatário. Default: ""
send_automatic_email (boolean): Se true, a ZapSign irá enviar um e-mail ao signatário com o link para assinar o documento. Se false (default), você é quem se encarregará de compartilhar o link de assinatura com o signatário, seja pelo seu site, widget, WhatsApp, SMS, e-mail, chat etc. Observação: para isso funcionar, é obrigatório que o email do signatário seja definido.
send_automatic_whatsapp (boolean): Se true, a ZapSign irá enviar uma mensagem por WhatsApp ao signatário com o link para assinar o documento. Se false (default), você é quem se encarregará de compartilhar o link de assinatura com o signatário, seja pelo seu site, widget, WhatsApp, SMS, e-mail, chat etc. Observação: para isso funcionar, é obrigatório que o phone_country e phone_number do signatário sejam definidos e cada envio automático via WhatsApp custa R$ 0,50. Adicione créditos em Configurações > Plano.
send_automatic_whatsapp_signed_file (boolean): Se true, a ZapSign irá enviar uma mensagem por WhatsApp ao signatário com o link para o arquivo assinado. Se false (default), você é quem se encarregará de compartilhar o link de assinatura com o signatário, seja pelo seu site, widget, WhatsApp, SMS, e-mail, chat etc. Observação: para isso funcionar, é obrigatório que o phone_country e phone_number do signatário sejam definidos e cada envio automático via WhatsApp custa R$ 0,50. Adicione créditos em Configurações > Plano.
order_group (integer): Caso "signature_order_active" esteja ativo no document, esse campo controla a ordem de assinatura. Exemplo: Se o order_group é 1, esse será o primeiro a assinar, se o order_group for 2 esse será o segundo a assinar e assim por diante.
custom_message (string): (apenas relevante caso send_automatic_email: true). A custom_message é a mensagem personalizada que você pode inserir no e-mail enviado pela ZapSign ao signatário. Exemplo: "Olá Fulano, \n Este é o seu contrato de trabalho. \n Abraços, Equipe XPTO". O símbolo \n serve para "pular uma linha" no texto do e-mail. Default: ""
lock_email (boolean): Você pode bloquear alterações ao e-mail do signatário. Default: false
blank_email (boolean): Você pode não solicitar o email do signatário. Default: false
hide_email (boolean): Você pode ocultar o email do signatário no relatório de assinaturas. Default: false
lock_phone (boolean): Você pode bloquear alterações ao telefone do signatário. Default: false
blank_phone (boolean): Você pode não solicitar o telefone do signatário. Default: false
hide_phone (boolean): Você pode ocultar o telefone do signatário no relatório de assinaturas. Default: false
lock_name (boolean): Você pode bloquear alterações ao nome do signatário. Default: false
require_selfie_photo (boolean): Você pode pedir que o signatário tire uma selfie enquanto assina. Default: false
require_document_photo (boolean): Você pode pedir que o signatário tire uma foto de seu documento pessoal enquanto assina (ex: RG ou CNH). Default: false
selfie_validation_type (string): Métodos avançados de biometria. Os disponíveis atualmente são:
Selfie_validation_typeDescriçãoPaisesValor por validação"liveness-document-match"
Reconhecimento facial que solicita que o signatário faça o upload de uma foto do documento de identidade e grave o rosto. Valida que a pessoa é a mesma do documento e que está presente no momento da assinatura. Se você já tem o documento do signatário, leia a seção Reconhecimento Facial.
Todos os países
15 creditos
"liveness-NXCD"
Valida que a pessoa está presente no momento da assinatura com um vídeo passivo (liveness)
Todos os países
15 creditos
“face-match-and-datavalid”
Autenticação via verificação facial com correspondência no banco de dados do governo (Serpro), confirmando o CPF e a CNH. Para utilizá-lo, é necessário preencher o parametro "cpf"
Disponível somente para o Brasil.
35 créditos
“identity-verification-global”
Verificação global da identidade do signatário no momento da assinatura, incluindo autenticação do documento e correspondência facial.
Todos os países
50 créditos
Para mais informações sobre os métodos de autenticação, consulte o artigo Criando documento, na nossa central de ajuda.
Além de configurar seu método de autenticação para cada signatário, você também pode configurar:
qualification (string): Qualificação para aparecer no relatório de assinaturas. Ex: valor "testemunha" irá resultar em "Assinou como testemunha". Default: ""
external_id (string): ID do signatário na sua aplicação. Default: ""
redirect_link (string): link para redirecionamento após signatário assinar. Por exemplo: "https://www.seusite.com.br/agradecimento". Irá aparecer como um botão "CONTINUAR" abaixo dos botões "Baixar original" e "Baixar assinado". Lembre-se de inserir o http:// ou https:// no começo do link. Default: ""
Exemplos de requisição
Criar documento a partir de um PDF
Criar documento a partir de um DOCX
O que faço com a resposta?
Após uma requisição bem sucedida, você deverá receber uma resposta como essa:
{
"open_id": 5,
"token": "eb9c367a-e62f-4992-8360-b0219deaeecc",
"status": "pending",
"name": "Contrato de Admissão João",
"original_file": "https://zapsign.s3.amazonaws.com/pdf/62xxxxx-d8fc-4392-8575-f3c46c3cfc7a/df6bac91-2766-4182-8c8b-ded5287e4c0f.pdf",
"signed_file": null,
"created_at": "2020-04-16T03:33:46.241747Z",
"last_update_at": "2020-04-16T03:33:46.241775Z",
"signers": [
{
"token": "921c115d-4a6e-445d-bdca-03fadedbbc0b",
"sign_url": "https://app.zapsign.com.br/verificar/921c115d-4a6e-445d-bdca-03fadedbbc0b",
"status": "new",
"name": "João da Silva",
"email": "",
"phone_country": "",
"phone_number": "",
"times_viewed": 0,
"last_view_at": null,
"signed_at": null,
"resend_attempts": null
},
{
"token": "07fb0a0a-4b7d-49a5-bd7b-4958265c4e46",
"sign_url": "https://app.zapsign.com.br/verificar/07fb0a0a-4b7d-49a5-bd7b-4958265c4e46",
"status": "new",
"name": "Fulano Siclano",
"email": "",
"phone_country": "",
"phone_number": "",
"times_viewed": 0,
"last_view_at": null,
"signed_at": null,
"resend_attempts": null
}
]
}Atenção: os links retornados em original_file e signed_file são temporários e duram 60 minutos. Caso seu sistema necessite salvar estes links é recomendado que sejam baixados em uma CDN própria ou que o endpoint de Detalhar documento seja consultado sempre para garantir que seu usuário sempre receberá um link válido.
O próximo passo é compartilhar os links de assinatura com cada signatário através da sua aplicação. Cada link é composto pela rota base:
https://app.zapsign.com.br/verificar/{{signer_token}}No exemplo acima, em que temos dois signatários, você deverá enviar dois links específicos, um para cada signatário, utilizando o respectivo token:
Agora, basta aguardar que os signatários acessem os links e concluam a assinatura!
Reconhecimento Facial
O método de autenticação valida a presença física da pessoa no momento da assinatura e garante que o rosto corresponde ao documento apresentado.
Se a empresa já possui a foto do documento de identidade do signatário, ela pode ser enviada na requisição para que o signatário apenas grave um vídeo do rosto, e esse vídeo será comparado com o documento que a empresa possui. Para isso, é necessário enviar os seguintes parâmetros:
document_photo_url (string): URL pública da frente da foto do documento de identidade. Essa foto será comparada com o vídeo gravado pelo signatário durante a assinatura do documento.
document_verse_photo_url (string): URL pública do verso da foto do documento de identidade. Ambas as fotos, junto com uma captura do vídeo gravado pelo signatário, serão registradas no relatório de assinaturas.
Importante: Este método não valida a autenticidade do documento de identidade, apenas verifica a correspondência entre a pessoa e o documento apresentado. Para um nível maior de segurança, consulte o método de autenticação "Validação de Identidade".
Saiba mais sobre reconhecimento facial clicando aqui.
Sobre o base64
Base64 é uma maneira simples de converter um arquivo em texto. Veja aqui uma definição mais completa https://pt.wikipedia.org/wiki/Base64. Assim, converter o arquivo em base64 e enviar como texto no corpo da requisição é mais fácil do que lidar com multipart/form-data, por exemplo.
Para testar a API, você pode converter manualmente seu PDF em base64 através de vários sites, como esse https://products.aspose.app/pdf/pt/conversion/word-to-base64
Quando a API já estiver integrada em seu sistema, procure a função adequada na sua linguagem de programação que pode converter o arquivo em base64.
Observação: você deve enviar o parâmetro base64_pdf apenas com a conversão do arquivo em base64. Não insira data:application/pdf;base64, na sua string.
Não quer trabalhar com base64? Suba seu PDF em uma url pública e use o parâmetro url_pdf.
Converse com o Gepeto!
Tem alguma duvida? Utilize nossa inteligência artificial treinada com toda a documentação da API =)
Last updated
Was this helpful?