TRtrytoku
Electronic Signature

Crear Document

Changed on

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, document.canceled, document.failed) que luego se envían al endpoint de webhooks configurado por la organización. Una vez recibido 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 llega cuando firmaron todos; el avance de cada firmante se consulta en el estado interno del Document.

post/document

Request

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

Headers

x-account-keystring

Llave de API de una Account, para operar sobre esa Account en lugar de la principal.

Request body

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

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

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

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

recipient_emailstring 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_namestring 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.

redirection_urlstring 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_copyboolean 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.

titlestring nullable

Título del documento en la ceremonia de firma. Si se omite, se usa «Documento de firma electrónica».

Example request

{
  "entity": {
    "id": "sub_pBf2NL0d0gvBM7Ei_1E3HIWnTN4W93_O"
  },
  "recipient_name": "Juana Pérez",
  "recipients": [
    {
      "email": "juana@example.com",
      "key": "cosigner",
      "mandate": "Mandato de firma otorgado por escritura pública del 1 de marzo de 2026.",
      "name": "Juana Pérez"
    }
  ],
  "redirection_url": "https://trytoku.com/redirection"
}

Response

Successful Response

idstring required

Identificador del Document.

urlstring uri required

URL en la que el firmante completa la ceremonia de firma.

Example response

{
  "id": "esigndoc_pBf2NL0d0gvBM7Ei_1E3HIWnTN4W93_O",
  "url": "https://trytoku.com/sign?token=123"
}

Changes