# Crear documento (OneClick)

<mark style="color:green;">`POST`</mark> `https://api.zapsign.com.br/api/v1/docs/`

Este endpoint te permite crear un documento para firma con un clic 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.

{% hint style="info" %}
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)](/espanol/documentos/adicionar-anexo-documento-extra.md)
{% endhint %}

#### Encabezado

<table><thead><tr><th width="175">Nombre</th><th width="103">Tipo</th><th>Descripción</th></tr></thead><tbody><tr><td>Authorization<mark style="color:red;">*</mark></td><td>string</td><td>API token prefijo con la palabra "Bearer". Ex: Bearer c7f35c84-7893-4087-b4fb-d1f06c23</td></tr></tbody></table>

#### Request Body

<table><thead><tr><th width="184">Nombre</th><th width="161">Tipo</th><th>Descripción</th></tr></thead><tbody><tr><td>name</td><td>string</td><td>Título del documento máximo 255 caracteres.</td></tr><tr><td>one_click_active</td><td>boolean</td><td>Para activar la experiencia simplificada de firma, este parámetro debe ser <strong>true.</strong></td></tr><tr><td>require_signature</td><td>boolean</td><td>Cuando se activa la experiencia simplificada de firma (one_click_active) y se define éste parametro como true, se va a pedir al firmante aceptar el checkbox y dibujar la firma. </td></tr><tr><td>url_pdf</td><td>string</td><td>Define el archivo PDF a firmar. Debe ser una URL pública y el tamaño del documento máximo 10Mb.</td></tr><tr><td>base64_pdf</td><td>string</td><td><strong>Alternativa a url_pdf:</strong> Documento convertido a cadena de base64.</td></tr><tr><td>url_docx</td><td>string</td><td><strong>Alternativa a url_pdf:</strong> Debe ser una URL pública y el tamaño del documento máximo 10Mb.</td></tr><tr><td>base64_docx</td><td>string</td><td><strong>Alternativa a url_docx:</strong> Documento convertido a cadena de base64.</td></tr><tr><td>signers [name]</td><td>Array&#x3C;Signe></td><td>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.</td></tr><tr><td>lang</td><td>string</td><td><p>Idioma del documento Posibles valores: "pt-br" (Portugues), "es" (Español), "en" (Inglés), "fr" (Francés). </p><p>Valor por defecto: "pt-br"
</p></td></tr><tr><td>disable_signer_emails </td><td>boolean</td><td>Para deshabilitar el envio de correos a los firmantes, este parametro debe ser true. Valor por defecto: false
</td></tr><tr><td>brand_logo</td><td>string</td><td><p>Para personalizar la experiencia de firma y los correos enviados por ZapSign, envia el logo en una URL pública. </p><p>Valor por defecto: ""
</p></td></tr><tr><td>brand_primary_color</td><td>string</td><td>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: ""</td></tr><tr><td>brand_name </td><td>string</td><td>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: ""
</td></tr><tr><td>external_id</td><td>string</td><td><p>Identificar del documento en tu aplicación. </p><p>Valor por defecto: ""</p></td></tr><tr><td>folder_path </td><td>string</td><td><p>Especifica la ruta de la carpeta dentro de ZapSign donde se guardará el documento. Si las carpetas no existen, se crearán automáticamente.</p><p>Ej.: "/api/" o "/folder1/folder2/folder3/". </p><p>Valor por defecto: "/" (sin folder).
</p></td></tr><tr><td>created_by</td><td>string</td><td><p>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á.</p><p>Valor por defecto: "" (el dueño del documento será el propietario de la cuenta).</p></td></tr><tr><td>date_limit_to_sign</td><td>DateTime</td><td><p>Fecha límite para la firma del documento. Después de esta fecha, el firmante no podrá acceder al link de firma.</p><p>(Formatos: YYYY-MM-DD, YYYY-MM-DDTH:m:s.ssssssZ)</p></td></tr><tr><td>signature_order_active </td><td>boolean</td><td><p>Si se establece en <strong>true</strong>, se enviará el link de firma en orden a los firmantes. </p><p>Valor por defecto: false</p></td></tr><tr><td>observers </td><td>array&#x3C;string></td><td>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.</td></tr><tr><td>reminder_every_n_days</td><td>integer</td><td><p>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.</p><p><strong>Obs</strong>: 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.</p></td></tr><tr><td>allow_refuse_signature</td><td>boolean</td><td><p>Si se establece en <strong>true</strong>, los firmantes tendrán la opción de rechazar la firma.</p><p>Valor por defecto: false.</p></td></tr><tr><td>disable_signers_get_original_file</td><td>boolean</td><td><p>Si se establece en <strong>true</strong>, los firmantes no podrán descargar el documento original.</p><p>Valor por defecto: false.</p></td></tr><tr><td>Metadata</td><td>Array</td><td>Metadatos personalizados enviados durante la creación del documento, en formato de pares <code>key</code> y <code>value</code>. Esta información solo aparece en los webhooks de creación, firma, rechazo y eliminación.</td></tr></tbody></table>

### Configuración de los firmantes

**Document** - JSON root:

{% hint style="warning" %}
**Advertencia**: cuando se crea el documento con OneClick, se debe llenar la información de name, email o phone ya que el firmante sólo aceptará la firma del documento por medio de un checkbox (es opcional habilitar firma). Además, no es posible definir métodos de autenticación (auth\_mode, selfie\_validation\_type, require\_document\_photo, require\_selfie).&#x20;
{% endhint %}

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

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

  * **email (string):** El correo electrónico del firmante. Es obligatorio definir el correo electrónico o teléfono porque el firmante no podrá llenar éstos datos.

  * **phone\_country (string):** El código de país del teléfono del firmante.  Es obligatorio definir el correo electrónico o teléfono porque el firmante no podrá llenar éstos datos.

  * **phone\_number (string):** El número de teléfono del firmante.  Es obligatorio definir el correo electrónico o teléfono porque el firmante no podrá llenar éstos datos.

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

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

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

  * **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

```javascript
{
	"name":"Nombre del documento",
	"url_pdf":"https://zapsign.s3.amazonaws.com/2022/1/pdf/63d19807-cbfa-4b51-8571-215ad0f4eb98/ca42e7be-c932-482c-b70b-92ad7aea04be.pdf",
        "one_click_active": true,
        "require_signature": true,
	"external_id": null,
	"signers":[
		{
			"name":"Maria Perez",
			"email":"maria@gmail.com",
			"send_automatic_email": false
		}
	],
    "lang": "es",
    "signed_file_only_finished": false,
    "folder_path":"/",
    "created_by":"",
    "date_limit_to_sign": null,
    "signature_order_active": false,
    "reminder_every_n_days": 0,
    "allow_refuse_signature": false,
    "disable_signers_get_original_file": false
}
```

### Respuesta

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

{% hint style="warning" %}
**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](/espanol/documentos/detalhar-documento.md) cada vez que tu usuario necesite una URL válida que caduque en más de 60 minutos.
{% endhint %}

```javascript
{
    "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.

### Editar documento OneClick en curso

Es posible adicionar, eliminar o editar un firmante de un documento en curso. Es importante destacar que **para adicionar o editar un firmante no es posible utilizar los parámetros auth\_mode, selfie\_validation\_type, require\_document\_photo o require\_selfie**, ya que OneClick es una experiencia de firma simplificada y no es compatible con métodos avanzados de autenticación.

Leer documentación para:&#x20;

* [Adicionar firmante](/espanol/firmantes/adicionar-signatario.md)
* [Eliminar firmante](/espanol/firmantes/excluir-signatario.md)
* [Editar firmante](/espanol/firmantes/atualizar-signatario.md)

### Sobre 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í.](https://en.wikipedia.org/wiki/Base64) 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](https://base64.guru/converter/encode/pdf).

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.

{% hint style="info" %}
**¡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.
{% endhint %}

### ¡Habla con Gepeto!

¿Tienes alguna duda? Usa nuestra inteligencia artificial entrenada con toda la documentación de la API =)

{% embed url="<https://n8n.zapsign.com.br/webhook/fee2c476-7f23-4a4f-8928-5c7ab081ffcd/chat>" %}


---

# Agent Instructions: Querying This Documentation

If you need additional information that is not directly available in this page, you can query the documentation dynamically by asking a question.

Perform an HTTP GET request on the current page URL with the `ask` query parameter:

```
GET https://docs.zapsign.com.br/espanol/documentos/oneclick/criar-documento-oneclick.md?ask=<question>
```

The question should be specific, self-contained, and written in natural language.
The response will contain a direct answer to the question and relevant excerpts and sources from the documentation.

Use this mechanism when the answer is not explicitly present in the current page, you need clarification or additional context, or you want to retrieve related documentation sections.