Crear documento via Upload

Crear documento via Upload

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

Este endpoint te permite crear un documento para firma a partir de un archivo PDF o DOCX. Es recomendado cuando ya tiene el archivo final, y sólo debe configurarse el documento y firmantes. Para usarlo, deberás enviar los datos en formato JSON y también recibirás la respuesta en el mismo formato.

Consejo: para enviar varios documentos en un sobre para que el firmante los firme al mismo tiempo, debes crear el documento primero con este endpoint y después adicionar los otros documentos con el endpoint Adicionar documento extra (sobre)

Encabezado

Nombre	Tipo	Descripción
Authorization*	string	API token prefijo con la palabra "Bearer". Ex: Bearer c7f35c84-7893-4087-b4fb-d1f06c23

Request Body

Nombre	Tipo	Descripción
name	string	Título del documento máximo 255 caracteres.
url_pdf	string	Define el archivo PDF a firmar. Debe ser una URL pública y el tamaño del documento máximo 10Mb.
base64_pdf	string	Alternativa a url_pdf: Documento convertido a cadena de base64.
url_docx	string	Alternativa a url_pdf: Debe ser una URL pública y el tamaño del documento máximo 10Mb.
base64_docx	string	Alternativa a url_docx: Documento convertido a cadena de base64.
signers [name]	Array<Signe>	El campo 'signers' representa las personas que van a firmar el documento. Más adelante se detalle cómo configurar cada firmante. Es un arreglo del objeto Signer.
lang	string	Idioma del documento Posibles valores: "pt-br" (Portugues), "es" (Español), "en" (Inglés), "fr" (Francés). Valor por defecto: "pt-br"
disable_signer_emails	boolean	Para deshabilitar el envio de correos a los firmantes, este parametro debe ser true. Valor por defecto: false
brand_logo	string	Para personalizar la experiencia de firma y los correos enviados por ZapSign, envia el logo en una URL pública. Valor por defecto: ""
brand_primary_color	string	Para personalizar la experiencia de firma y los correos enviados por ZapSign, envia el color de los botónes en este parámetro en formato rgb orhexadecimal. Ej: "#0011ee". Valor por defecto: ""
brand_name	string	Para personalizar el remitente de los correos, envia el nombre de tu marca en este parámetro. Por ejemplo, si escribes "Empresa ABC", el firmante recibirá el correo "Empresa ABC via ZapSign". Máximo de 100 carácteres. Valor por defecto: ""
external_id	string	Identificar del documento en tu aplicación. Valor por defecto: ""
folder_path	string	Especifica la ruta de la carpeta dentro de ZapSign donde se guardará el documento. Si las carpetas no existen, se crearán automáticamente. Ej.: "/api/" o "/folder1/folder2/folder3/". Valor por defecto: "/" (sin folder).
created_by	string	Correo electrónico del usuario que se definirá como creador del documento, con fines organizativos internos. Si el correo no existe o no es un usuario de tu cuenta, este parámetro se ignorará. Valor por defecto: "" (el dueño del documento será el propietario de la cuenta).
date_limit_to_sign	DateTime	Fecha límite para la firma del documento. Después de esta fecha, el firmante no podrá acceder al link de firma. (Formatos: YYYY-MM-DD, YYYY-MM-DDTH:m:s.ssssssZ)
signature_order_active	boolean	Si se establece en true, se enviará el link de firma en orden a los firmantes. Valor por defecto: false
observers	array<string>	Representa a los observadores del documento (hasta 20 personas), es decir, direcciones de correo electrónico que serán notificadas cuando se complete el flujo de firma. Es un array de correos electrónicos.
reminder_every_n_days	integer	Intervalo de días entre recordatorios que se enviarán a los firmantes, mientras no hayan firmado el documento. El máximo son 6 intentos de recordatorio. Obs: Este campo solo aplica si send_automatic_whatsapp o send_automatic_email están activados. Ejemplo: Si se establece en 8, se enviará un recordatorio cada 7 días.
allow_refuse_signature	boolean	Si se establece en true, los firmantes tendrán la opción de rechazar la firma. Valor por defecto: false.
disable_signers_get_original_file	boolean	Si se establece en true, los firmantes no podrán descargar el documento original. Valor por defecto: false.

200 Document created successfully.

{
    "open_id": 5,
    "token": "eb9c367a-e62f-4992-8360-b0219deaeecc",
    "status": "pending",
    "name": "Jhon Doe Documents",
    "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
        }
    ]
}

Configuración de los firmantes

Document - JSON root:

• Signers - para cada firmante define los siguientes parámetros:

  • auth_mode (string): Elige el método de autenticación para el firmante. Esto adiciona más seguridad al documento firmado, para más información sobre los métodos haz clic aqui.

  auth_mode	Descripción	Costo adicional
  "assinaturaTela"	Firma en pantalla	Gratis
  "tokenEmail"	Validación del correo con un código enviado por correo	Gratis
  "assinaturaTela-tokenEmail"	Firma en pantalla y validación del correo con un código enviado por correo	Gratis
  "tokenSms"	Validación del celular con un código enviado por SMS	Gratis
  "assinaturaTela-tokenSms"	Firma en pantalla y validación del celular con un código enviado por SMS	Gratis
  "tokenWhatsapp"	Validación del celular con un código enviado por WhatsApp	5 credis = USD$0.1
  "assinaturaTela-tokenWhatsapp"	Firma en pantalla y validación del celular con un código enviado por WhatsApp	5 creditos = USD$0.1

  Nota: para comprar créditos ve a tu cuenta de ZapSign a la sección de Ajustes > Planes > Creditos. Para un volumen superior contacta al equipo de ventas para una solución personalizada.

  • name (string): El nombre del firmante. Obligatorio.

  • email (string): El correo electrónico del firmante. Si el firmante no tiene correo electrónico, debes definir el parámetro blank_email = true.

  • phone_country (string): El código de país del teléfono del firmante. Por defecto "", pero se puede definir.

  • phone_number (string): El número de teléfono del firmante. Ejemplo: "11998989222".

  • require_document (booleano): Si es true, se requerirá que el firmante proporcione su información de identificación (país, tipo de documento y número de documento). Esta información se incluirá en el informe de firma. Valor predeterminado: false.

  • require_document_data {objeto}: Si se definen el país, tipo de documento y número de documento, el firmante no podrá modificar esta información durante el proceso de firma. Si solo se definen el país y el tipo de documento, el firmante deberá ingresar el número

    • document_country (string). Posibles valores: "br" (Brazil), "co" (Colombia), "mx" (Mexico), "us" (United Stated), "ar" (Argentina), "pe" (Peru), "cl" (Chile), "other" (Other country).

    • document_type (string). Posibles valores: "national_id", "foreign_id", "driver_license", "ppt".

    • document_number (string): Por defecto: "".

  • lock_email (boolean): Si se establece en true, el firmante no podrá cambiar su correo electrónico durante el proceso de firma. Por defecto es false.

  • blank_email (boolean): Si se establece en true, no se solicitará el correo electrónico del firmante y no se incluirá en el informe de la firma. Es obligatorio tener el correo O el número de teléfono del firmante.

  • hide_email (boolean): Si se establece en true, el correo electrónico del firmante no se mostrará en el informe de firmas. Por defecto es false.

  • lock_phone (boolean): Si se establece en true, el firmante no podrá cambiar su celular electrónico durante el proceso de firma. Por defecto es false.

  • blank_phone (boolean): YSi se establece en true, no se solicitará el celular del firmante y no se incluirá en el informe de la firma. Es obligatorio tener el correo O el número de teléfono del firmante.

  • hide_phone (boolean): Si se establece en true, el celular del firmante no se mostrará en el informe de firmas. Por defecto es false.

  • lock_name (boolean): Si se establece en true, el firmante no podrá cambiar su nombre electrónico durante el proceso de firma. Por defecto es false.

  • send_automatic_email (boolean): Si se establece en true, ZapSign enviará automáticamente un correo al firmante con el enlace para firmar el documento. Por defecto es false

  • send_automatic_whatsapp (boolean): Si se establece en true, ZapSign enviará automáticamente un mensaje por WhatsApp al firmante con el enlace para firmar el documento. Recuerda que se deben tener créditos para enviar por WhatsApp. Por defecto es false

  • send_automatic_whatsapp_signed_file (boolean): Si se establece en true, ZapSign enviará un mensaje por WhatsApp al firmante con el enlace al documento firmado. Recuerda que se deben tener créditos para enviar por WhatsApp. Por defecto es false

  • order_group (integer): Si "signature_order_active" es true en el documento, este campo controla el orden de firma. Ejemplo: Si se establece en 1, este firmante será el primero en firmar; si es 2, será el segundo, y así sucesivamente.

  • custom_message (string): Si send_automatic_email es true, puedes personalizar el mensaje del correo enviado al firmante. Ejemplo: "Hola [Nombre], \n Este es tu contrato de empleo. \n Saludos, Equipo XPTO". El símbolo \n sirve para saltos de línea.

  • require_selfie_photo (boolean): Si se establece en true, se pedirá al firmante que tome una selfie durante el proceso de firma (no hay validación de la foto). Por defecto es false.

  • require_document_photo (boolean): Si se establece en true, se pedirá al firmante que tome una foto del frente y anverso del documento de identidad durante el proceso de firma (no hay validación de la foto). Por defecto es false.

  • selfie_validation_type (string): Métodos biométricos avanzados para validar la selfie del firmante. Para conocer más sobre cada método haz clic aqui.

selfie_validation_type	Descripción	Países	Precio
liveness-document-match	Reconocimiento facial que valida que el firmante esté presente y sea el mismo que la foto del documento suministrada.	CO, BR, MX, CL, PE	25 creditos = $0.5 USD
identity-verification	Validación del documento y biometría facial, asegurando que el firmante esté presente, que el documento sea real y que esté registrado en bases de datos gubernamentales.	CO, MX, CL, PE	55 creditos = $1.0 USD

Tenemos disponible la opción del método de "Validación de identidad" para otros países, contacta al equipo comercial para mayor información.

• qualification (string): Rol del firmante que se mostrará en el informe de firma. Por ejemplo "Testigo" se mostrará como "Firmo como Testigo". Por defecto "".

• external_id (string): ID del firmante en tu aplicación. Por defecto está "".

• redirect_link (string): Enlace al que se redirige al firmante después de firmar el documento. Después de firmar se mostrará un botón de "Continuar". Recuerda incluir http:// o https:// al inicio del enlace. Por defecto está "".

Solicitud

Create document via PDF

https://www.postman.com/zapsign/workspace/zapsign-workspace/request/27495556-97395ac6-ced0-41bd-99eb-1f94c05625de?ctx=documentationwww.postman.com

URL for the Create doc from upload PDF endpoint

Create document via DOCX

https://www.postman.com/zapsign/workspace/zapsign-workspace/request/27495556-95777596-18ed-415a-ad5f-2b1ac98b496b?ctx=documentationwww.postman.com

URL for the Create doc from upload DOCX endpoint

Delphi request example

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', '[e-mail]');
   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;

Respuesta

Después de una solicitud exitosa, recibirás una respuesta similar a esta:

Advertencia: los enlaces original_file y signed_file son temporales y caducan en 60 minutos. Si tu sistema necesita guardar esos enlaces, se recomienda almacenarlos en tu propio CDN o llamar al endpoint de Detalle del documento cada vez que tu usuario necesite una URL válida que caduque en más de 60 minutos.

{
    "open_id": 5,
    "token": "eb9c367a-e62f-4992-8360-b0219deaeecc",
    "status": "pending",
    "name": "John's contract",
    "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.co/verificar/921c115d-4a6e-445d-bdca-03fadedbbc0b",
            "status": "new",
            "name": "John Doe",
            "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.co/verificar/07fb0a0a-4b7d-49a5-bd7b-4958265c4e46",
            "status": "new",
            "name": "Grumpy Jones",
            "email": "",
            "phone_country": "",
            "phone_number": "",
            "times_viewed": 0,
            "last_view_at": null,
            "signed_at": null,
            "resend_attempts": null
        }
    ]
}

Link de firma

En la respuesta de la solicitud, cada firmante va a tener un singer_url que es el link para que firmen el documento. Si no enviaste el documento por los canales de ZapSign (send_automatic_email o send_automatic_whatsapp) debes enviar el enlace a los firmantes.

About the base64

Base64 es una forma sencilla de convertir archivos en texto. Si quieres conocer más detalles sobre qué es Base64, puedes consultar su definición completa aquí. Al convertir un archivo a Base64 y enviarlo como texto en el cuerpo de la solicitud, es más fácil de manejar que, por ejemplo, el formato multipart/form-data.

Para probar la API, puedes convertir tu archivo PDF a Base64 manualmente a través de varios sitios web, como este.

Cuando ya tengas la API integrada en tu sistema, busca la función correspondiente en tu lenguaje de programación para convertir archivos a Base64.

¡Atención! Debes enviar el parámetro base64_pdf solo con la conversión Base64 del archivo. No incluyas data:application/pdf;base64, en tu parámetro.