Criar documento via Upload

post
Criar documento via Upload

https://api.zapsign.com.br/api/v1/docs/?api_token={{seu_token_de_acesso}}
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.
Request
Response
Request
Body Parameters
sandbox
optional
boolean
Default: false. Defina como true caso se trate de um documento de teste (sem cobrança de créditos e sem validade jurídica).
name
required
string
Título do documento. String de até 255 caracteres
url_pdf
required
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
optional
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]
required
string
O campo 'signers' representa os signatários do documento, ou seja, quem irá assinar. É um array de objetos. O parâmetro 'name' (nome do signatário) é obrigatório.
Response
200: OK
Documento criado com sucesso.
{
"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",
"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",
"status": "new",
"name": "Fulano Siclano",
"email": "",
"phone_country": "",
"phone_number": "",
"times_viewed": 0,
"last_view_at": null,
"signed_at": null
}
]
}

Campos opcionais da requisição

  • Documento - raiz do JSON:

    • 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

    • signed_file_only_finished (boolean): para desativar os botões "Baixar original" e "Baixar assinado" da experiência de signatário, ative este flag. Assim, você é quem se encarregará de entregar o signed_file ao signatário. 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 (string): 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: ""

    • 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).

  • 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". Correspondem aos mesmos métodos disponíveis na interface web.

    • 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.

    • 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

    • lock_phone (boolean): Você pode bloquear alterações ao telefone do signatário. 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

    • 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: ""

Exemplo de requisição

Os parâmetros devem estar em formato JSON no corpo da requisição

{
"name":"Contrato de Admissão João",
"base64_pdf":"JVBERi0xLjcNCiWhs8XXDQoxIDA...",
"brand_primary_color":"#000000",
"signers":[
{
"name":"João da Silva"
},
{
"name":"Fulano Siclano",
"email":"[email protected]",
"send_automatic_email":true,
"custom_message":"Olá Fulano, \n Este é o seu contrato de trabalho. \n Abraços, Equipe XPTO",
"lock_email":true,
"lock_phone":true,
"phone_country":"55",
"phone_number":"11977778600",
"auth_mode":"assinaturaTela-tokenSms"
}
]
}

O que fazer 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",
"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",
"status": "new",
"name": "Fulano Siclano",
"email": "",
"phone_country": "",
"phone_number": "",
"times_viewed": 0,
"last_view_at": null,
"signed_at": 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.

Exemplos de requisição em algumas linguagens de programação

PHP

<?php
$url = "https://api.zapsign.com.br/api/v1/docs/?api_token=1e19d1f9-69e0-4a66-b93d-e515fdf081c693b8b613-25e9-4536-b5df-76d25120449a";
$ch = curl_init( $url );
$base64 = 'JVBERi0xLjMNCiXi48/TDQoNCjEgMCBvYmoNCjw8DQovVHlwZSAvQ2F0YWxvZw0KL091dGxpbmVzIDIgMCBSDQovUGFnZXMgMyAwIFINCj4+DQplbmRvYmoNCg0KMiAwIG9iag0KPDwNCi9UeXBlIC9PdXRsaW5lcw0KL0NvdW50IDANCj4+DQplbmRvYmoNCg0KMyAwIG9iag0KPDwNCi9UeXBlIC9QYWdlcw0KL0NvdW50IDINCi9LaWRzIFsgNCAwIFIgNiAwIFIgXSANCj4+DQplbmRvYmoNCg0KNCAwIG9iag0KPDwNCi9UeXBlIC9QYWdlDQovUGFyZW50IDMgMCBSDQovUmVzb3VyY2VzIDw8DQovRm9udCA8PA0KL0YxIDkgMCBSIA0KPj4NCi9Qcm9jU2V0IDggMCBSDQo+Pg0KL01lZGlhQm94IFswIDAgNjEyLjAwMDAgNzkyLjAwMDBdDQovQ29udGVudHMgNSAwIFINCj4+DQplbmRvYmoNCg0KNSAwIG9iag0KPDwgL0xlbmd0aCAxMDc0ID4+DQpzdHJlYW0NCjIgSg0KQlQNCjAgMCAwIHJnDQovRjEgMDAyNyBUZg0KNTcuMzc1MCA3MjIuMjgwMCBUZA0KKCBBIFNpbXBsZSBQREYgRmlsZSApIFRqDQpFVA0KQlQNCi9GMSAwMDEwIFRmDQo2OS4yNTAwIDY4OC42MDgwIFRkDQooIFRoaXMgaXMgYSBzbWFsbCBkZW1vbnN0cmF0aW9uIC5wZGYgZmlsZSAtICkgVGoNCkVUDQpCVA0KL0YxIDAwMTAgVGYNCjY5LjI1MDAgNjY0LjcwNDAgVGQNCigganVzdCBmb3IgdXNlIGluIHRoZSBWaXJ0dWFsIE1lY2hhbmljcyB0dXRvcmlhbHMuIE1vcmUgdGV4dC4gQW5kIG1vcmUgKSBUag0KRVQNCkJUDQovRjEgMDAxMCBUZg0KNjkuMjUwMCA2NTIuNzUyMCBUZA0KKCB0ZXh0LiBBbmQgbW9yZSB0ZXh0LiBBbmQgbW9yZSB0ZXh0LiBBbmQgbW9yZSB0ZXh0LiApIFRqDQpFVA0KQlQNCi9GMSAwMDEwIFRmDQo2OS4yNTAwIDYyOC44NDgwIFRkDQooIEFuZCBtb3JlIHRleHQuIEFuZCBtb3JlIHRleHQuIEFuZCBtb3JlIHRleHQuIEFuZCBtb3JlIHRleHQuIEFuZCBtb3JlICkgVGoNCkVUDQpCVA0KL0YxIDAwMTAgVGYNCjY5LjI1MDAgNjE2Ljg5NjAgVGQNCiggdGV4dC4gQW5kIG1vcmUgdGV4dC4gQm9yaW5nLCB6enp6ei4gQW5kIG1vcmUgdGV4dC4gQW5kIG1vcmUgdGV4dC4gQW5kICkgVGoNCkVUDQpCVA0KL0YxIDAwMTAgVGYNCjY5LjI1MDAgNjA0Ljk0NDAgVGQNCiggbW9yZSB0ZXh0LiBBbmQgbW9yZSB0ZXh0LiBBbmQgbW9yZSB0ZXh0LiBBbmQgbW9yZSB0ZXh0LiBBbmQgbW9yZSB0ZXh0LiApIFRqDQpFVA0KQlQNCi9GMSAwMDEwIFRmDQo2OS4yNTAwIDU5Mi45OTIwIFRkDQooIEFuZCBtb3JlIHRleHQuIEFuZCBtb3JlIHRleHQuICkgVGoNCkVUDQpCVA0KL0YxIDAwMTAgVGYNCjY5LjI1MDAgNTY5LjA4ODAgVGQNCiggQW5kIG1vcmUgdGV4dC4gQW5kIG1vcmUgdGV4dC4gQW5kIG1vcmUgdGV4dC4gQW5kIG1vcmUgdGV4dC4gQW5kIG1vcmUgKSBUag0KRVQNCkJUDQovRjEgMDAxMCBUZg0KNjkuMjUwMCA1NTcuMTM2MCBUZA0KKCB0ZXh0LiBBbmQgbW9yZSB0ZXh0LiBBbmQgbW9yZSB0ZXh0LiBFdmVuIG1vcmUuIENvbnRpbnVlZCBvbiBwYWdlIDIgLi4uKSBUag0KRVQNCmVuZHN0cmVhbQ0KZW5kb2JqDQoNCjYgMCBvYmoNCjw8DQovVHlwZSAvUGFnZQ0KL1BhcmVudCAzIDAgUg0KL1Jlc291cmNlcyA8PA0KL0ZvbnQgPDwNCi9GMSA5IDAgUiANCj4+DQovUHJvY1NldCA4IDAgUg0KPj4NCi9NZWRpYUJveCBbMCAwIDYxMi4wMDAwIDc5Mi4wMDAwXQ0KL0NvbnRlbnRzIDcgMCBSDQo+Pg0KZW5kb2JqDQoNCjcgMCBvYmoNCjw8IC9MZW5ndGggNjc2ID4+DQpzdHJlYW0NCjIgSg0KQlQNCjAgMCAwIHJnDQovRjEgMDAyNyBUZg0KNTcuMzc1MCA3MjIuMjgwMCBUZA0KKCBTaW1wbGUgUERGIEZpbGUgMiApIFRqDQpFVA0KQlQNCi9GMSAwMDEwIFRmDQo2OS4yNTAwIDY4OC42MDgwIFRkDQooIC4uLmNvbnRpbnVlZCBmcm9tIHBhZ2UgMS4gWWV0IG1vcmUgdGV4dC4gQW5kIG1vcmUgdGV4dC4gQW5kIG1vcmUgdGV4dC4gKSBUag0KRVQNCkJUDQovRjEgMDAxMCBUZg0KNjkuMjUwMCA2NzYuNjU2MCBUZA0KKCBBbmQgbW9yZSB0ZXh0LiBBbmQgbW9yZSB0ZXh0LiBBbmQgbW9yZSB0ZXh0LiBBbmQgbW9yZSB0ZXh0LiBBbmQgbW9yZSApIFRqDQpFVA0KQlQNCi9GMSAwMDEwIFRmDQo2OS4yNTAwIDY2NC43MDQwIFRkDQooIHRleHQuIE9oLCBob3cgYm9yaW5nIHR5cGluZyB0aGlzIHN0dWZmLiBCdXQgbm90IGFzIGJvcmluZyBhcyB3YXRjaGluZyApIFRqDQpFVA0KQlQNCi9GMSAwMDEwIFRmDQo2OS4yNTAwIDY1Mi43NTIwIFRkDQooIHBhaW50IGRyeS4gQW5kIG1vcmUgdGV4dC4gQW5kIG1vcmUgdGV4dC4gQW5kIG1vcmUgdGV4dC4gQW5kIG1vcmUgdGV4dC4gKSBUag0KRVQNCkJUDQovRjEgMDAxMCBUZg0KNjkuMjUwMCA2NDAuODAwMCBUZA0KKCBCb3JpbmcuICBNb3JlLCBhIGxpdHRsZSBtb3JlIHRleHQuIFRoZSBlbmQsIGFuZCBqdXN0IGFzIHdlbGwuICkgVGoNCkVUDQplbmRzdHJlYW0NCmVuZG9iag0KDQo4IDAgb2JqDQpbL1BERiAvVGV4dF0NCmVuZG9iag0KDQo5IDAgb2JqDQo8PA0KL1R5cGUgL0ZvbnQNCi9TdWJ0eXBlIC9UeXBlMQ0KL05hbWUgL0YxDQovQmFzZUZvbnQgL0hlbHZldGljYQ0KL0VuY29kaW5nIC9XaW5BbnNpRW5jb2RpbmcNCj4+DQplbmRvYmoNCg0KMTAgMCBvYmoNCjw8DQovQ3JlYXRvciAoUmF2ZSBcKGh0dHA6Ly93d3cubmV2cm9uYS5jb20vcmF2ZVwpKQ0KL1Byb2R1Y2VyIChOZXZyb25hIERlc2lnbnMpDQovQ3JlYXRpb25EYXRlIChEOjIwMDYwMzAxMDcyODI2KQ0KPj4NCmVuZG9iag0KDQp4cmVmDQowIDExDQowMDAwMDAwMDAwIDY1NTM1IGYNCjAwMDAwMDAwMTkgMDAwMDAgbg0KMDAwMDAwMDA5MyAwMDAwMCBuDQowMDAwMDAwMTQ3IDAwMDAwIG4NCjAwMDAwMDAyMjIgMDAwMDAgbg0KMDAwMDAwMDM5MCAwMDAwMCBuDQowMDAwMDAxNTIyIDAwMDAwIG4NCjAwMDAwMDE2OTAgMDAwMDAgbg0KMDAwMDAwMjQyMyAwMDAwMCBuDQowMDAwMDAyNDU2IDAwMDAwIG4NCjAwMDAwMDI1NzQgMDAwMDAgbg0KDQp0cmFpbGVyDQo8PA0KL1NpemUgMTENCi9Sb290IDEgMCBSDQovSW5mbyAxMCAwIFINCj4+DQoNCnN0YXJ0eHJlZg0KMjcxNA0KJSVFT0YNCg==';
$payload = array(
"name"=>"Contrato de Admissão João",
"signers"=>array(
array(
"name"=>"João da Silva"
),
array(
"name"=>"Fulano Siclano",
"email"=>"[email protected]",
"auth_mode"=>"tokenEmail"
)
),
"base64_pdf"=>$base64
);
$json_payload = json_encode($payload);
curl_setopt( $ch, CURLOPT_POSTFIELDS, $json_payload );
curl_setopt( $ch, CURLOPT_HTTPHEADER, array('Content-Type:application/json'));
curl_setopt( $ch, CURLOPT_RETURNTRANSFER, true );
curl_setopt($ch, CURLOPT_SSL_VERIFYHOST, 0);
curl_setopt($ch, CURLOPT_SSL_VERIFYPEER, 0);
$result = curl_exec($ch);
// A depender da versão de php, curl e OpenSSL do seu servidor,
// você pode testar também outras opções do curl, como:
// curl_setopt ($ch, CURLOPT_SSL_VERIFYPEER, 0);
// curl_setopt ($ch, CURLOPT_SSL_VERIFYHOST, 0);
// curl_setopt ($ch, CURLOPT_FOLLOWLOCATION, TRUE);
// curl_setopt ($ch, CURLOPT_SSLVERSION, 6);
// curl_setopt ($ch, CURLOPT_USERAGENT, "Mozilla/5.0 (Windows NT 6.1; WOW64) AppleWebKit/537.36 (KHTML, like Gecko) Chrome/42.0.2311.135 Safari/537.36");
// curl_setopt ($ch, CURLOPT_COOKIESESSION, TRUE);
// curl_setopt ($ch, CURLOPT_RETURNTRANSFER, 1);
// curl_setopt( $ch, CURLOPT_POSTFIELDS, $json_payload );
// curl_setopt( $ch, CURLOPT_HTTPHEADER, array('Content-Type:application/json'));
// curl_setopt ($ch, CURLOPT_HEADER, 1);
// curl_setopt ($ch, CURLOPT_POST, true);
// curl_setopt ($ch, CURLOPT_FRESH_CONNECT , 1);
// curl_setopt($ch, CURLOPT_RETURNTRANSFER, 1);
// curl_setopt($ch, CURLOPT_HTTPAUTH, CURLAUTH_BASIC);
// Para testes/debug, descomentar:
// echo $result;
// echo curl_getinfo($ch);
// echo curl_errno($ch);
// echo curl_error($ch);
curl_close($ch);

Python

import requests
url = "https://api.zapsign.com.br/api/v1/docs/?api_token=1e19d1f9-69e0-4a66-b93d-e515fdf081c693b8b613-25e9-4536-b5df-76d25120449a"
payload = "{\"name\":\"Contrato de Admissão João\",\"signers\":[{\"name\":\"João da Silva\"},{ \"name\":\"Fulano Siclano\"}],\"base64_pdf\":\"JVBERi0xLjcNCiWhs8XXDQoxIDA...\"}"
headers = {
'Content-Type': 'application/json'
}
response = requests.request("POST", url, headers=headers, data = payload)
print(response.text.encode('utf8'))

Node.js

var request = require('request');
var options = {
'method': 'POST',
'url': 'https://api.zapsign.com.br/api/v1/docs/?api_token=1e19d1f9-69e0-4a66-b93d-e515fdf081c693b8b613-25e9-4536-b5df-76d25120449a',
'headers': {
'Content-Type': 'application/json'
},
body: JSON.stringify({"name":"Contrato de Admissão João","signers":[{"name":"João da Silva"},{"name":"Fulano Siclano"}],"base64_pdf":"JVBERi0xLjcNCiWhs8XXDQoxIDA..."})
};
request(options, function (error, response) {
if (error) throw new Error(error);
console.log(response.body);
});

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', '[email protected]');
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;