---
title: "Crear Document"
method: POST
path: "/document"
tags: ["Electronic Signature"]
---

# Crear Document

`POST /document`

## Request

- Base URL: `https://api.trytoku.com`
- URL: `https://api.trytoku.com/document`
- Auth: API key in header `x-api-key`

Crea un Document a partir de un archivo en Base64 y devuelve la URL en la que el firmante completa la ceremonia de firma.

Se usa para iniciar el flujo de firma. El archivo se envía al proveedor, el Document queda en estado `pending` y los cambios de estado posteriores se notifican mediante los webhooks `document.*` ([`document.signed`](/reference/document-signed), [`document.canceled`](/reference/document-canceled), [`document.failed`](/reference/document-failed)) que luego se envían al endpoint de webhooks configurado por la organización. Una vez recibido [`document.signed`](/reference/document-signed), el documento firmado se descarga con `GET /document/{document_id}/signed-url`.

Con `entity` el Document queda asociado a esa entidad y el nombre del Customer asociado se usa como nombre del firmante. Con `data` el archivo se procesa como plantilla DOCX y sus campos se reemplazan al generar el documento; sin `data` se procesa como PDF.

Con `recipients` firman varias personas sobre el mismo documento. `client` firma en la URL que devuelve este endpoint; a cada uno de los demás `signer` el proveedor le envía su enlace por correo cuando le toca firmar (con `routing` secuencial, cuando firma el anterior). Un `automatic_signer` (por ejemplo, la institución) lo firma el proveedor al crear el Document, sin correo ni ceremonia. [`document.signed`](/reference/document-signed) llega cuando firmaron todos; el avance de cada firmante se consulta en el estado interno del Document.

## Headers

- `x-account-key` string

## Request body

- CreateDocumentPayload: Datos para crear un Document y generar su enlace de firma.
  - `attestation` 'mx_nom151' | 'br_icp_brasil', nullable: Constancia a solicitar al proveedor: `mx_nom151` (sello NOM-151 de México) o `br_icp_brasil` (sello ICP-Brasil). `br_icp_brasil` requiere que la organización tenga contratada la Firma Virtual con Sello Brasil; si no, se responde 403.
  - `auth_data` object, nullable: Metadatos propios que se guardan junto al documento en el proveedor. Máximo 9 pares; cada clave hasta 100 caracteres y cada valor hasta 1000.
  - `data` object, nullable: Valores con los que se rellena el documento cuando es una plantilla DOCX. Al enviarlo, el archivo se procesa como DOCX en vez de PDF. Serializado no puede superar los 50000 caracteres. A los valores enviados se agregan siempre `current_day` (día del mes, 1 a 31), `current_month` (nombre del mes en minúscula, en el idioma del país de la organización: español o portugués) y `current_year` (año en 4 dígitos), con la fecha del día en la zona horaria de la organización, de modo que la plantilla no tenga que traer la fecha fija; si se envía alguno de esos nombres, prevalece el valor enviado.
  - `document` string, required: Documento a firmar, codificado en Base64. Su texto debe incluir el marcador `[[sign_here]]`, que indica dónde se ubica la firma del firmante.
  - `entity` ElectronicSignatureEntity: Entidad de Toku a la que queda asociado el Document.
    - `id` string, required: Identificador de la entidad asociada.
    - `type` string, required: Tipo de la entidad asociada: `subscription` o `gad_cat_mandate`.
  - `language` string, nullable: Idioma de la ceremonia de firma y de los correos que el proveedor envía al firmante. Valores soportados: `es` (español) y `pt` (portugués de Brasil). Si se omite, se usa el idioma del país de la organización, o `es` si ese idioma no está soportado.
  - `places` Place[], nullable: Campos adicionales que el firmante debe completar, además de la firma.
    - `capture_as` string, nullable: Nombre con el que se devuelve el valor capturado.
    - `format` string, nullable: Formato que debe cumplir el valor ingresado.
    - `format_message` string, nullable: Mensaje que se muestra si el valor no cumple el formato.
    - `hint` string, nullable: Texto de ayuda que acompaña al campo.
    - `key` string, required: Marcador `[[key]]` del documento donde se ubica el campo.
    - `prompt` string, nullable: Texto que se le muestra al firmante para pedir el valor.
    - `recipient_key` string, required: Firmante al que se le pide el campo.
    - `requirement` string, nullable: Exigencia del campo para completar la firma.
    - `type` string, required: Tipo de campo que el proveedor renderiza en esa posición.
  - `recipient_email` string, nullable: Correo del firmante. Si se envía, el proveedor le hace llegar la invitación a firmar por correo; si se omite, el enlace de firma se entrega solo en la respuesta.
  - `recipient_name` string, nullable: Nombre con el que se identifica al firmante en la ceremonia de firma y en los correos que el proveedor le envía. Si se envían ambos, se prioriza el nombre del Customer asociado al `entity`; si ese Customer no tiene nombre, se usa `recipient_name`. Si no se envía ninguno de los dos, el firmante queda identificado con un nombre genérico.
  - `recipients` Recipient[], nullable: Firmantes del Document, cuando firma más de una persona. Si se omite, firma una sola persona (identificada por `recipient_name` / `recipient_email` o por el `entity`). Si se envía, no se admiten `recipient_name` ni `recipient_email`; cada firmante distinto de `client` necesita al menos un `places[]` de tipo `signature` y ningún firmante recibe copia del documento firmado por correo.
    - `auth` 'email_link' | 'email_code', nullable: Autenticación de un `signer` distinto de `client`: `email_link` (por defecto) firma con el enlace del correo; `email_code` además le pide un código enviado al correo. No se admite en `client`, que se autentica en el producto que integra, ni en un `automatic_signer`, que firma el proveedor.
    - `email` string, nullable: Correo del firmante. Obligatorio para todo `signer` distinto de `client`: el proveedor le envía ahí el enlace para firmar cuando le toca su turno. No se admite en un `automatic_signer`, que no recibe correos.
    - `key` string, required: Identificador del firmante dentro del Document, al que apuntan los `places[].recipient_key`. `client` es obligatorio: firma en la ceremonia cuya URL devuelve este endpoint, ubicada por el marcador `[[sign_here]]`.
    - `mandate` string, nullable: Solo en `automatic_signer`, y obligatorio: autorización bajo la cual se firma, que el proveedor registra textual en el registro de auditoría.
    - `name` string, required: Nombre del firmante en la ceremonia y en los correos.
    - `signature_image` string, nullable: Solo en `automatic_signer`, y obligatorio: imagen de la firma, en PNG codificado en Base64.
    - `type` 'signer' | 'automatic_signer': Tipo de firmante: `signer` (por defecto) firma una persona; `automatic_signer` firma el proveedor al crear el Document, sin ceremonia ni correo, con `signature_image` y bajo `mandate` (por ejemplo, la firma de la institución). Un `automatic_signer` necesita su propio `places[]` de tipo `signature` y, con `routing` secuencial, va antes que los demás firmantes.
  - `redirection_url` string, uri, required: URL a la que se redirige al firmante al terminar la ceremonia de firma.
  - `routing` 'sequential' | 'parallel', nullable: Orden de firma cuando se envían `recipients`: `sequential` (por defecto) en el orden de la lista, de modo que cada firmante recibe su invitación cuando firma el anterior, o `parallel`, todos a la vez.
  - `send_signed_copy` boolean, nullable: Con `false`, el proveedor no le envía al firmante la copia del documento firmado, aunque se envíe `recipient_email`: sirve cuando la copia final se entrega por otro medio. Si se omite, se envía la copia siempre que haya `recipient_email`. Con `recipients` no se admite `true`: en ese modo ningún firmante recibe la copia.
  - `title` string, nullable: Título del documento en la ceremonia de firma. Si se omite, se usa «Documento de firma electrónica».

## Response `201`

Successful Response

- CreateDocumentResponse: Document recién creado, con el enlace para firmarlo.
  - `id` string, required: Identificador del Document.
  - `url` string, uri, required: URL en la que el firmante completa la ceremonia de firma.

## Other responses

- `400`: El proveedor de firma rechazó el documento enviado. El detalle indica el motivo: por ejemplo, el archivo no se pudo interpretar o no contiene el marcador de firma.
- `401`: La organización no tiene habilitada la firma electrónica.
- `403`: La API key no se envió, no es válida o la organización está desactivada; o la organización no tiene habilitada la constancia pedida en `attestation`.
- `404`: La entidad indicada en `entity` no existe.
- `422`: El payload no es válido: `document` no es Base64, `entity.type` o `language` no están soportados, algún campo incumple sus límites, o `recipients` no calza con `places` (claves repetidas o desconocidas, falta `client`, o un firmante distinto de `client` sin correo o sin lugar de firma).
- `429`: Se superó el límite de peticiones permitidas.
- `500`: No se pudo crear el Document. Reintentar más tarde.

## Changes

- **2026-11-03** `a6ef070075b1`: 1 info
  - endpoint added

[Operation history](https://skmtc.dev/trytoku/apis/toku-api/changes/document/post.md)

---

[API](https://skmtc.dev/trytoku/apis/toku-api.md) - [All operations](https://skmtc.dev/trytoku/apis/toku-api/llms.txt) - [OpenAPI document](https://skmtc.dev/trytoku/apis/toku-api/revisions/a6ef070075b1?raw)