Criar documento via Upload

POST https://api.zapsign.com.br/api/v1/docs/

Esse endpoint permite que você crie um documento para assinatura a partir de um PDF. Você deverá enviar os dados em JSON, bem como receberá eles nesse mesmo formato.

Headers

Name	Type	Description
Authorization*	string	Api token a frente do texto "Bearer". Ex: Bearer c7f35c84-7893-4087-b4fb-d1f06c23

Name

Type

Description

Authorization*

string

Api token a frente do texto "Bearer".

Ex: Bearer c7f35c84-7893-4087-b4fb-d1f06c23

Request Body

Name	Type	Description
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.
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.

Name

Type

Description

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.

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.

{
    "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

Documento - raiz do JSON:

Signers - para cada signer:

auth_mode (string): Você pode escolher o método de autenticação do signatário. Valores possíveis são: "assinaturaTela" (default), "tokenEmail", "assinaturaTela-tokenEmail", "tokenSms", "assinaturaTela-tokenSms","tokenWhatsapp", "assinaturaTela-tokenWhatsapp", "certificadoDigital" e "CPF" . Correspondem aos mesmos métodos disponíveis na interface web. Observação: o "certificadoDigital" tem um custo de R$ 0,50 por signatário que assinar com certificadoDigital e CPF tem o custo de R$1,00 por assinatura realizada com sucesso. Observação: cada envio automático via WhatsApp (tokenWhatsapp) custa R$0,50 e cada envio de token via SMS (tokenSms) custa R$0,10. Adicione créditos em Configurações > Plano.
email (string): Você pode definir o e-mail do signatário
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: ""
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: ""
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_cpf (boolean): Você pedir o CPF do signatário. Default: false
cpf (string): Você informar o CPF do signatário. Default: ""
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.

Selfie_validation_type	Descrição	Paises	Preço 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	BR, CO, MX, CL, PE	15 credito = R$1,5
liveness-NXCD	Valida que a pessoa está presente no momento da assinatura com um vídeo passivo (liveness)	Todos os países	15 creditos = R$1,5

Selfie_validation_type

Descrição

Paises

Preço 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

BR, CO, MX, CL, PE

15 credito = R$1,5

liveness-NXCD

Valida que a pessoa está presente no momento da assinatura com um vídeo passivo (liveness)

Todos os países

15 creditos = R$1,5

Para mais informações sobre os métodos de autenticação, clique aqui.

Adicione créditos na sua conta em Configurações > Plano > Créditos ou converse com a nossa equipe comercial.

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

Exemplo de requisição em Delphi

var
  json : string;
  ArraySigner : TJSONArray;
  ObjDoc, ObjSigner : TJSONObject;
begin
   ObjDoc := TJSONObject.Create;
   ObjDoc.AddPair('name', 'Contrato de Locação');
   ObjDoc.AddPair('base64_pdf', 'ASFASDFKÇLKÇGÇO#OP%$%#WERP#@&*OSADFJF...');  // Arquivo base64

   ArraySigner := TJSONArray.Create;

   ObjSigner := TJSONObject.Create;
   ObjSigner.AddPair('name', 'João da Silva');
   ObjSigner.AddPair('email', 'joaosilva@gmail.com.br');
   ObjSigner.AddPair('phone_country', '55');
   ObjSigner.AddPair('phone_number', '11888121111');
   // Opcional caso queira impedir alteração 
   ObjSigner.AddPair('lock_name', TJSONTrue.Create);
   ObjSigner.AddPair('lock_email', TJSONTrue.Create);
   ObjSigner.AddPair('lock_phone', TJSONTrue.Create);

   ArraySigner.AddElement(ObjSigner);

   ObjDoc.AddPair('signers', ArraySigner);
   json := ObjDoc.ToString;

   ObjDoc.DisposeOf;

   RESTClient.BaseURL := 'https://api.zapsign.com.br/api/v1/docs/?api_token=...seu token..';
   Request_remete.ClearBody;
   Request_remete.Body.Add(json,ContentTypeFromString('application/json'));
   Request_remete.Execute;
end;

O que fazer com a resposta

Após uma requisição bem sucedida, você deverá receber uma resposta como essa:

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.

{
    "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
        }
    ]
}

O que você deverá fazer com essa resposta é enviar o link de assinatura para os signatários através da sua aplicação.

O link de assinatura consiste na rota: https://app.zapsign.com.br/verificar/{{signer_token}}

Ou seja, no exemplo acima, em que temos dois signatários, você deve enviar dois links de assinatura, cada signatário com seu respectivo token: - João da Silva: https://app.zapsign.com.br/verificar/921c115d-4a6e-445d-bdca-03fadedbbc0b - Fulano Siclano: https://app.zapsign.com.br/verificar/07fb0a0a-4b7d-49a5-bd7b-4958265c4e46

E agora é só aguardar que os signatários assinem!

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://base64.guru/converter/encode/pdf

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.

PreviousInformações do Plano NextCriar documento via Modelo

Last updated 11 days ago