{
  "$schema": "https://json-schema.org/draft/2020-12/schema",
  "$id": "https://artifacts.apis.io/toku/json-schema/toku-create-document-payload-schema.json",
  "title": "CreateDocumentPayload",
  "description": "Datos para crear un Document y generar su enlace de firma.",
  "x-generated": "2026-11-10",
  "x-method": "derived",
  "x-generator": "derive-json-schema.py",
  "x-source": "openapi/toku-electronic-signature-api-openapi.yml#/components/schemas/CreateDocumentPayload",
  "properties": {
    "attestation": {
      "anyOf": [
        {
          "enum": [
            "mx_nom151",
            "br_icp_brasil"
          ],
          "type": "string"
        },
        {
          "type": "null"
        }
      ],
      "description": "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.",
      "title": "Attestation"
    },
    "auth_data": {
      "anyOf": [
        {
          "additionalProperties": {
            "type": "string"
          },
          "type": "object"
        },
        {
          "type": "null"
        }
      ],
      "description": "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.",
      "title": "Auth Data"
    },
    "data": {
      "anyOf": [
        {
          "additionalProperties": true,
          "type": "object"
        },
        {
          "type": "null"
        }
      ],
      "description": "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.",
      "title": "Data"
    },
    "document": {
      "description": "Documento a firmar, codificado en Base64. Su texto debe incluir el marcador `[[sign_here]]`, que indica dónde se ubica la firma del firmante.",
      "title": "Document",
      "type": "string"
    },
    "entity": {
      "anyOf": [
        {
          "$ref": "#/$defs/ElectronicSignature_Entity"
        },
        {
          "type": "null"
        }
      ],
      "description": "Entidad de Toku a asociar al Document. Su Customer aporta el nombre del firmante."
    },
    "language": {
      "anyOf": [
        {
          "type": "string"
        },
        {
          "type": "null"
        }
      ],
      "description": "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.",
      "title": "Language"
    },
    "places": {
      "anyOf": [
        {
          "items": {
            "$ref": "#/$defs/Place"
          },
          "type": "array"
        },
        {
          "type": "null"
        }
      ],
      "description": "Campos adicionales que el firmante debe completar, además de la firma.",
      "title": "Places"
    },
    "recipient_email": {
      "anyOf": [
        {
          "type": "string"
        },
        {
          "type": "null"
        }
      ],
      "description": "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.",
      "title": "Recipient Email"
    },
    "recipient_name": {
      "anyOf": [
        {
          "type": "string"
        },
        {
          "type": "null"
        }
      ],
      "description": "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.",
      "title": "Recipient Name"
    },
    "recipients": {
      "anyOf": [
        {
          "items": {
            "$ref": "#/$defs/Recipient"
          },
          "maxItems": 10,
          "minItems": 1,
          "type": "array"
        },
        {
          "type": "null"
        }
      ],
      "description": "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.",
      "title": "Recipients"
    },
    "redirection_url": {
      "description": "URL a la que se redirige al firmante al terminar la ceremonia de firma.",
      "format": "uri",
      "maxLength": 2083,
      "minLength": 1,
      "title": "Redirection Url",
      "type": "string"
    },
    "routing": {
      "anyOf": [
        {
          "enum": [
            "sequential",
            "parallel"
          ],
          "type": "string"
        },
        {
          "type": "null"
        }
      ],
      "description": "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.",
      "title": "Routing"
    },
    "send_signed_copy": {
      "anyOf": [
        {
          "type": "boolean"
        },
        {
          "type": "null"
        }
      ],
      "description": "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": "Send Signed Copy"
    },
    "title": {
      "anyOf": [
        {
          "type": "string"
        },
        {
          "type": "null"
        }
      ],
      "description": "Título del documento en la ceremonia de firma. Si se omite, se usa «Documento de firma electrónica».",
      "title": "Title"
    }
  },
  "required": [
    "document",
    "redirection_url"
  ],
  "type": "object",
  "$defs": {
    "ElectronicSignature_Entity": {
      "description": "Entidad de Toku a la que queda asociado el Document.",
      "properties": {
        "id": {
          "description": "Identificador de la entidad asociada.",
          "pattern": "^[a-z]+_[a-zA-Z0-9_-]+$",
          "title": "Id",
          "type": "string"
        },
        "type": {
          "description": "Tipo de la entidad asociada: `subscription` o `gad_cat_mandate`.",
          "title": "Type",
          "type": "string"
        }
      },
      "required": [
        "id",
        "type"
      ],
      "title": "ElectronicSignature_Entity",
      "type": "object"
    },
    "Place": {
      "description": "Campo que el firmante completa o firma en el documento, ubicado por un marcador ``[[key]]``.",
      "properties": {
        "capture_as": {
          "anyOf": [
            {
              "type": "string"
            },
            {
              "type": "null"
            }
          ],
          "description": "Nombre con el que se devuelve el valor capturado.",
          "title": "Capture As"
        },
        "format": {
          "anyOf": [
            {
              "type": "string"
            },
            {
              "type": "null"
            }
          ],
          "description": "Formato que debe cumplir el valor ingresado.",
          "title": "Format"
        },
        "format_message": {
          "anyOf": [
            {
              "type": "string"
            },
            {
              "type": "null"
            }
          ],
          "description": "Mensaje que se muestra si el valor no cumple el formato.",
          "title": "Format Message"
        },
        "hint": {
          "anyOf": [
            {
              "type": "string"
            },
            {
              "type": "null"
            }
          ],
          "description": "Texto de ayuda que acompaña al campo.",
          "title": "Hint"
        },
        "key": {
          "description": "Marcador `[[key]]` del documento donde se ubica el campo.",
          "title": "Key",
          "type": "string"
        },
        "prompt": {
          "anyOf": [
            {
              "type": "string"
            },
            {
              "type": "null"
            }
          ],
          "description": "Texto que se le muestra al firmante para pedir el valor.",
          "title": "Prompt"
        },
        "recipient_key": {
          "description": "Firmante al que se le pide el campo.",
          "title": "Recipient Key",
          "type": "string"
        },
        "requirement": {
          "anyOf": [
            {
              "type": "string"
            },
            {
              "type": "null"
            }
          ],
          "description": "Exigencia del campo para completar la firma.",
          "title": "Requirement"
        },
        "type": {
          "description": "Tipo de campo que el proveedor renderiza en esa posición.",
          "title": "Type",
          "type": "string"
        }
      },
      "required": [
        "key",
        "type",
        "recipient_key"
      ],
      "title": "Place",
      "type": "object"
    },
    "Recipient": {
      "description": "Firmante de un Document con más de un firmante.",
      "properties": {
        "auth": {
          "anyOf": [
            {
              "enum": [
                "email_link",
                "email_code"
              ],
              "type": "string"
            },
            {
              "type": "null"
            }
          ],
          "description": "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.",
          "title": "Auth"
        },
        "email": {
          "anyOf": [
            {
              "type": "string"
            },
            {
              "type": "null"
            }
          ],
          "description": "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.",
          "title": "Email"
        },
        "key": {
          "description": "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]]`.",
          "pattern": "^[a-z][a-z0-9_]{0,31}$",
          "title": "Key",
          "type": "string"
        },
        "mandate": {
          "anyOf": [
            {
              "maxLength": 500,
              "type": "string"
            },
            {
              "type": "null"
            }
          ],
          "description": "Solo en `automatic_signer`, y obligatorio: autorización bajo la cual se firma, que el proveedor registra textual en el registro de auditoría.",
          "title": "Mandate"
        },
        "name": {
          "description": "Nombre del firmante en la ceremonia y en los correos.",
          "title": "Name",
          "type": "string"
        },
        "signature_image": {
          "anyOf": [
            {
              "type": "string"
            },
            {
              "type": "null"
            }
          ],
          "description": "Solo en `automatic_signer`, y obligatorio: imagen de la firma, en PNG codificado en Base64.",
          "title": "Signature Image"
        },
        "type": {
          "default": "signer",
          "description": "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.",
          "enum": [
            "signer",
            "automatic_signer"
          ],
          "title": "Type",
          "type": "string"
        }
      },
      "required": [
        "key",
        "name"
      ],
      "title": "Recipient",
      "type": "object"
    }
  }
}