Crear Documento Síncrono

POST

https://api.firmeasy.legal/api/v1/documents

Crear Documento Síncrono

Este endpoint permite registrar un nuevo documento principal y, opcionalmente, anexos, firmantes y posiciones de firma en una sola llamada. Responde 201 con el sobre completo.

¿Sync o Async?

	Síncrono `POST /v1/documents`	Asíncrono `POST /v1/documents/envelopes/async`
Documentos por sobre	hasta 5 (principal + 4 anexos)	hasta 100
Peso	50 MB total del sobre	~100 MB por doc · 1 GB total
Fuente del archivo	base64, URL, DOCX o key temporal	solo URL (primer release)
Respuesta	201 con el sobre completo	202 con `ingest_token` (se arma en background)
Cuándo	caso interactivo / pocos docs	lotes grandes / archivos pesados

curl -X POST https://api.firmeasy.legal/api/v1/documents \
-H "Authorization: Bearer YOUR_TOKEN" \
-H "Content-Type: application/json" \
-d '{
  "name": "Contrato de Servicios",
  "document_pdf_url": "https://files.example.com/contrato.pdf",
  "signers": [{
    "name": "John Doe",
    "email": "[email protected]",
    "country_code": "+51",
    "phone": "900000001"
  }]
}'

Sin ejecutar·latencia ~ 412 ms

Demo pública · no guarda datos · firma con sandbox PKI

Autenticación

El token de acceso obtenido en el proceso de login debe enviarse en cada solicitud:

Parámetro	Tipo	Descripción	Límites
`Authorization`	string	Token de acceso obtenido en el login, con el prefijo 'Bearer'.	Obligatorio
`Content-Type`	string	Especifica el tipo de contenido del cuerpo de la solicitud HTTP. Para las peticiones que incluyen datos JSON	'application/json'

Authorization

string

Token de acceso obtenido en el login, con el prefijo 'Bearer'.

Límites:Obligatorio

Content-Type

string

Especifica el tipo de contenido del cuerpo de la solicitud HTTP. Para las peticiones que incluyen datos JSON

Límites:'application/json'

Campos Obligatorios

Los campos marcados con un asterisco (*) son obligatorios y deben ser proporcionados en la solicitud. Los demás campos son opcionales.

Límites del Sobre

Límite	Valor
Documentos por sobre (principal + anexos)	5
Peso TOTAL del sobre	50 MB
Anexos (`extra_docs`)	Máximo 4 (= total − 1)
Un documento individual	≤ peso total (50 MB)

Fuente del documento principal

Se debe elegir estrictamente UNA de las siguientes opciones (son excluyentes entre sí, enviar dos causará un error 422):

Parámetro	Tipo	Descripción	Límites
`document_pdf_url`	url	URL pública desde donde el sistema descargará el archivo PDF.	Excluyente
`document_pdf_base64`	string	Archivo PDF codificado en formato Base64.	Excluyente
`document_temporal_key`	string(255)	Llave temporal de un archivo PDF pre-subido al sistema.	Excluyente
`document_docx_url`	url	URL pública de un archivo DOCX. El sistema lo convertirá automáticamente a PDF.	Excluyente
`document_docx_base64`	string	Archivo DOCX codificado en formato Base64 para su conversión automática.	Excluyente

document_pdf_url

url

URL pública desde donde el sistema descargará el archivo PDF.

Límites:Excluyente

document_pdf_base64

string

Archivo PDF codificado en formato Base64.

Límites:Excluyente

document_temporal_key

string(255)

Llave temporal de un archivo PDF pre-subido al sistema.

Límites:Excluyente

document_docx_url

url

URL pública de un archivo DOCX. El sistema lo convertirá automáticamente a PDF.

Límites:Excluyente

document_docx_base64

string

Archivo DOCX codificado en formato Base64 para su conversión automática.

Límites:Excluyente

Identidad y referencia

Parámetro	Tipo	Descripción	Límites
`name`	string	Nombre oficial del documento. El sistema lo normaliza automáticamente a MAYÚSCULAS y le añade la extensión '.pdf'.	Obligatorio
`ref_id`	string	Referencia para el archivo principal. En este flujo síncrono el sistema lo ignora por defecto, mapeando el archivo principal siempre como 'main'.	Opcional (se ignora)

name

string

Nombre oficial del documento. El sistema lo normaliza automáticamente a MAYÚSCULAS y le añade la extensión '.pdf'.

Límites:Obligatorio

ref_id

string

Referencia para el archivo principal. En este flujo síncrono el sistema lo ignora por defecto, mapeando el archivo principal siempre como 'main'.

Límites:Opcional (se ignora)

Configuración del sobre

Parámetro	Tipo	Descripción	Límites
`external_id`	string(255)	ID externo libre asignado por el integrador (pass-through) para control interno.	Opcional
`folder_token`	uuid	Token de la carpeta destino donde se guardará el documento.	Debe ser un UUID válido
`template_token`	uuid	Token de la plantilla pre-configurada a aplicar.	Debe ser un UUID válido
`created_by`	email	Correo electrónico del usuario creador de la solicitud.	Formato de email
`created_through`	enum	Canal de creación del sobre. Valores admitidos: 'api' o 'web'.	Por defecto: 'api'
`signature_deadline`	ISO8601	Fecha y hora límite futura para completar las firmas (ej. '2026-12-31T23:59:59.000Z').	Formato UTC completo
`sender_name`	string(150)	Nombre del solicitante que se le mostrará a los firmantes en las notificaciones. Si se omite, se usa el del propietario.	Máx 150 caracteres
`reply_to_email`	email	Dirección de correo configurada para recibir las respuestas de las notificaciones enviadas.	Formato de email
`disable_owner_notifications`	bool	Desactiva por completo las alertas por correo hacia el propietario del sobre.	Por defecto: false
`disable_signer_notifications`	bool	Desactiva las alertas y flujos automáticos de correo hacia los firmantes.	Por defecto: false
`send_automatic_invitations`	bool	Dispara de forma inmediata los correos o mensajes de invitación al crear el sobre.	Por defecto: true
`send_automatic_invitations_by`	enum	Medio de envío de las invitaciones. Valores: 'email' o 'whatsapp'.	Opcional
`send_signed_document_by_whatsapp`	bool	Envía una copia en PDF del documento finalizado directo al WhatsApp del firmante.	Por defecto: false
`is_signature_order_active`	bool	Fuerza a que los firmantes sigan estrictamente el orden jerárquico establecido (secuencial).	Por defecto: false
`is_rejection_allowed`	bool	Habilita el botón para que un firmante pueda rechazar formalmente el documento explicando el motivo.	Por defecto: false
`is_original_download_allowed`	bool	Permite al firmante descargar el PDF original limpio antes de estampar su firma.	Por defecto: true
`reminder_every_n_days`	int	Frecuencia de días para enviar recordatorios automáticos de firma pendiente (rango 0 a 30).	0 para desactivar
`lang`	enum	Idioma de la interfaz y comunicaciones del firmante. Valores: 'es', 'en', 'pt'.	Por defecto: 'es'
`observers`	array<string>	Lista de correos de observadores con acceso de solo lectura al documento (máximo 20).	Array de emails
`redirect_link`	string(255)	URL de redirección a la que el navegador enviará al usuario inmediatamente después de firmar.	Debe ser una URL válida
`metadata`	object	Objeto JSON libre de almacenamiento llave-valor para guardar metadatos personalizados.	Pass-through

external_id

string(255)

ID externo libre asignado por el integrador (pass-through) para control interno.

Límites:Opcional

folder_token

uuid

Token de la carpeta destino donde se guardará el documento.

Límites:Debe ser un UUID válido

template_token

uuid

Token de la plantilla pre-configurada a aplicar.

Límites:Debe ser un UUID válido

created_by

Correo electrónico del usuario creador de la solicitud.

Límites:Formato de email

created_through

enum

Canal de creación del sobre. Valores admitidos: 'api' o 'web'.

Límites:Por defecto: 'api'

signature_deadline

ISO8601

Fecha y hora límite futura para completar las firmas (ej. '2026-12-31T23:59:59.000Z').

Límites:Formato UTC completo

sender_name

string(150)

Nombre del solicitante que se le mostrará a los firmantes en las notificaciones. Si se omite, se usa el del propietario.

Límites:Máx 150 caracteres

reply_to_email

Dirección de correo configurada para recibir las respuestas de las notificaciones enviadas.

Límites:Formato de email

disable_owner_notifications

bool

Desactiva por completo las alertas por correo hacia el propietario del sobre.

Límites:Por defecto: false

disable_signer_notifications

bool

Desactiva las alertas y flujos automáticos de correo hacia los firmantes.

Límites:Por defecto: false

send_automatic_invitations

bool

Dispara de forma inmediata los correos o mensajes de invitación al crear el sobre.

Límites:Por defecto: true

send_automatic_invitations_by

enum

Medio de envío de las invitaciones. Valores: 'email' o 'whatsapp'.

Límites:Opcional

send_signed_document_by_whatsapp

bool

Envía una copia en PDF del documento finalizado directo al WhatsApp del firmante.

Límites:Por defecto: false

is_signature_order_active

bool

Fuerza a que los firmantes sigan estrictamente el orden jerárquico establecido (secuencial).

Límites:Por defecto: false

is_rejection_allowed

bool

Habilita el botón para que un firmante pueda rechazar formalmente el documento explicando el motivo.

Límites:Por defecto: false

is_original_download_allowed

bool

Permite al firmante descargar el PDF original limpio antes de estampar su firma.

Límites:Por defecto: true

reminder_every_n_days

int

Frecuencia de días para enviar recordatorios automáticos de firma pendiente (rango 0 a 30).

Límites:0 para desactivar

lang

enum

Idioma de la interfaz y comunicaciones del firmante. Valores: 'es', 'en', 'pt'.

Límites:Por defecto: 'es'

observers

array<string>

Lista de correos de observadores con acceso de solo lectura al documento (máximo 20).

Límites:Array de emails

redirect_link

string(255)

URL de redirección a la que el navegador enviará al usuario inmediatamente después de firmar.

Límites:Debe ser una URL válida

metadata

object

Objeto JSON libre de almacenamiento llave-valor para guardar metadatos personalizados.

Límites:Pass-through

Anexos

Permite añadir hasta un máximo de 4 documentos complementarios en la misma llamada.

Parámetro	Tipo	Descripción	Límites
`extra_docs[].ref_id`	string	Identificador único y obligatorio del anexo. Es vital para asociarle sus coordenadas de firma más adelante.	Obligatorio y único
`extra_docs[].name`	string	Nombre del archivo anexo.	Opcional
`extra_docs[].pdf_url`	url	URL pública para la descarga directa del anexo.	Excluyente si se usa base64 o key
`extra_docs[].pdf_base64`	string	Contenido del anexo codificado en formato Base64.	Excluyente
`extra_docs[].temporal_key`	string(255)	Llave temporal del archivo anexo pre-subido.	Excluyente
`extra_docs[].file`	file (pdf)	Archivo PDF adjuntado directamente en la solicitud. Solo disponible si el request se envía como `multipart/form-data`.	Excluyente con url/base64/key

extra_docs[].ref_id

string

Identificador único y obligatorio del anexo. Es vital para asociarle sus coordenadas de firma más adelante.

Límites:Obligatorio y único

extra_docs[].name

string

Nombre del archivo anexo.

Límites:Opcional

extra_docs[].pdf_url

url

URL pública para la descarga directa del anexo.

Límites:Excluyente si se usa base64 o key

extra_docs[].pdf_base64

string

Contenido del anexo codificado en formato Base64.

Límites:Excluyente

extra_docs[].temporal_key

string(255)

Llave temporal del archivo anexo pre-subido.

Límites:Excluyente

extra_docs[].file

file (pdf)

Archivo PDF adjuntado directamente en la solicitud. Solo disponible si el request se envía como `multipart/form-data`.

Límites:Excluyente con url/base64/key

Campos Obligatorios

Los campos marcados con un asterisco (*) son obligatorios y deben ser proporcionados en la solicitud. Los demás campos son opcionales.

Firmantes

Define los actores del documento. Campos mínimos requeridos por elemento: name, country_code (ej. ‘+51’), phone y email.

Parámetro	Tipo	Descripción	Límites
`signers[].role`	enum	Rol del participante dentro del sobre. Valores admitidos: 'signer' (firma), 'approver' (aprueba sin firmar) o 'witness' (testigo).	Por defecto: 'signer'
`signers[].document_type`	string	Tipo de documento legal de identidad (ej. 'DNI', 'CE'). Obligatorio si utilizas flujos avanzados de identidad.	Obligatorio con flujos de alta seguridad
`signers[].document_number`	string	Número del documento de identidad. Si es DNI, se validan exactamente 8 dígitos numéricos.	Obligatorio con flujos de alta seguridad
`signers[].standard_flow`	array<string>	Métodos primarios de firma electrónica. Valores válidos: 'holographic_signature' (o su alias 'firma_biometrica'), 'otp_email', 'otp_sms', 'otp_whatsapp', o 'digital_certificate_local'.	Ver reglas abajo
`signers[].advanced_flow`	array<string>	Capas avanzadas de validación biométrica. Valores válidos: 'selfie', 'doc_identidad' (alias 'identity_document_verification'), 'video_firma' (alias 'live_video_authentication'), 'face_recognition', 'reniec_match'.	Máximo 2 flujos activos

signers[].role

enum

Rol del participante dentro del sobre. Valores admitidos: 'signer' (firma), 'approver' (aprueba sin firmar) o 'witness' (testigo).

Límites:Por defecto: 'signer'

signers[].document_type

string

Tipo de documento legal de identidad (ej. 'DNI', 'CE'). Obligatorio si utilizas flujos avanzados de identidad.

Límites:Obligatorio con flujos de alta seguridad

signers[].document_number

string

Número del documento de identidad. Si es DNI, se validan exactamente 8 dígitos numéricos.

Límites:Obligatorio con flujos de alta seguridad

signers[].standard_flow

array<string>

Métodos primarios de firma electrónica. Valores válidos: 'holographic_signature' (o su alias 'firma_biometrica'), 'otp_email', 'otp_sms', 'otp_whatsapp', o 'digital_certificate_local'.

Límites:Ver reglas abajo

signers[].advanced_flow

array<string>

Capas avanzadas de validación biométrica. Valores válidos: 'selfie', 'doc_identidad' (alias 'identity_document_verification'), 'video_firma' (alias 'live_video_authentication'), 'face_recognition', 'reniec_match'.

Límites:Máximo 2 flujos activos

Posicionamiento de Firma (Formatos Excluyentes)

Opción A) Estructura Recomendada: `placements[]` (Porcentajes)

Se configura dentro del arreglo de cada firmante (signers[].placements[]). Permite posicionar firmas e iniciales de forma fluida en múltiples documentos a la vez.

Parámetro	Tipo	Descripción	Límites
`document_ref`	string	Etiqueta del archivo al que aplica la firma. Puede ser 'main' (documento principal) o el 'ref_id' exacto asignado a un anexo.	Por defecto: 'main'
`type`	enum	Tipo de marca gráfica a estampar en la hoja. Valores: 'signature' (firma completa) o 'initials' (visado/iniciales).	Por defecto: 'signature'
`page_number`	int	Número correlativo de la página donde se colocará el cuadro (debe ser mayor o igual a 1).	Obligatorio
`relative_position_left`	float	Posición en eje X calculada como porcentaje (0 a 100) desde el borde izquierdo de la hoja.	Obligatorio (ej. 36.5)
`relative_position_top`	float	Posición en eje Y calculada como porcentaje (0 a 100) medido desde el borde superior de la hoja.	Excluyente con bottom
`relative_position_bottom`	float	Posición en eje Y calculada como porcentaje (0 a 100) medido desde el borde inferior de la hoja.	Excluyente con top
`relative_size_width`	float	Ancho del cuadro de firma calculado como porcentaje total del ancho de la página.	Opcional (0 a 100)
`relative_size_height`	float	Alto del cuadro de firma calculado como porcentaje total del alto de la página.	Opcional (0 a 100)

document_ref

string

Etiqueta del archivo al que aplica la firma. Puede ser 'main' (documento principal) o el 'ref_id' exacto asignado a un anexo.

Límites:Por defecto: 'main'

type

enum

Tipo de marca gráfica a estampar en la hoja. Valores: 'signature' (firma completa) o 'initials' (visado/iniciales).

Límites:Por defecto: 'signature'

page_number

int

Número correlativo de la página donde se colocará el cuadro (debe ser mayor o igual a 1).

Límites:Obligatorio

relative_position_left

float

Posición en eje X calculada como porcentaje (0 a 100) desde el borde izquierdo de la hoja.

Límites:Obligatorio (ej. 36.5)

relative_position_top

float

Posición en eje Y calculada como porcentaje (0 a 100) medido desde el borde superior de la hoja.

Límites:Excluyente con bottom

relative_position_bottom

float

Posición en eje Y calculada como porcentaje (0 a 100) medido desde el borde inferior de la hoja.

Límites:Excluyente con top

relative_size_width

float

Ancho del cuadro de firma calculado como porcentaje total del ancho de la página.

Límites:Opcional (0 a 100)

relative_size_height

float

Alto del cuadro de firma calculado como porcentaje total del alto de la página.

Límites:Opcional (0 a 100)

"placements": [
  {
    "document_ref": "main",
    "type": "signature",
    "page_number": 1,
    "relative_position_left": 36.5,
    "relative_position_top": 39.25,
    "relative_size_width": 25,
    "relative_size_height": 8
  }
]

Opción B) Legacy: Puntos PDF Absolutos (Solo principal)

Se configura a nivel raíz del firmante (fuera de placements). No se puede mezclar con placements o arrojará 422.

Campo	Tipo	Notas
`position_x`	número	Coordenada X exacta en puntos absolutos del PDF (origen top-left).
`position_y`	número	Coordenada Y exacta en puntos absolutos del PDF.
`page`	int	Número de página (mayor o igual a 1).

Ejemplo de solicitud mínima (Payload JSON)

{
  "name": "Contrato de Prestación de Servicios N°9",
  "document_pdf_base64": "JVBERi0xLjQKJdPr6goxIDAgb2JqCjw8L0xlbmd0aCAyIDAgUi9GaWx0ZXIvRmxhdGVEZWNvZGU+PnN0cmVhbQp4nDMwVTAwULAwMDIxUzAFAAZ3A2Y5CmVuZHN0cmVhbQplbmRvYmoKMiAwIG9iagozMAplbmRvYmoKMyAwIG9iago8PC9UeXBlL1BhZ2VzL0NvdW50IDEvS2lkc1s0IDAgUl0+PgplbmRvYmoKNDAwIFJGST0=",
  "signers": [
    {
      "name": "Jane Doe",
      "email": "[email protected]",
      "country_code": "+51",
      "phone": "900000001",
      "standard_flow": ["digital_certificate_local"],
      "placements": [
        {
          "document_ref": "main",
          "type": "signature",
          "page_number": 1,
          "relative_position_left": 36.5,
          "relative_position_top": 39.25,
          "relative_size_width": 25,
          "relative_size_height": 8
        }
      ]
    }
  ]
}

Respuesta exitosa (201 Created)

{
  "external_id": "ERP-123",
  "token": "abcdef01-2345-6789-abcd-ef0123456789",
  "name": "Acuerdo_Comercial_2025.pdf",
  "folder": { "token": "uuid", "name": "Carpeta" },
  "status": "pending",
  "lang": "es",
  "size": 245100,
  "original_file": "https://api.firmeasy.legal/files/...?intent=view&signature=...",
  "signed_file": null,
  "original_download_file": "https://api.firmeasy.legal/files/...?intent=download&...",
  "signed_download_file": null,
  "signatures_made": 0,
  "signature_deadline": "2026-12-31T23:59:59.000Z",
  "created_by": { "email": "[email protected]" },
  "extra_docs_count": 0,
  "extra_docs": [],
  "signers": [
    {
      "external_id": null,
      "token": "signer-api-id",
      "status": "pending",
      "rejection_reason": null,
      "order": 1,
      "name": "Carl Smith",
      "email": "[email protected]",
      "phone": "900000002",
      "country_code": "+51",
      "document_type": null,
      "document_number": null,
      "role": "signer",
      "link": "https://app.firmeasy.legal/...",
      "placements": [
        {
          "document_ref": "main",
          "type": "signature",
          "page_number": 1,
          "relative_position_left": 36.5,
          "relative_position_top": 39.25,
          "relative_size_width": 25,
          "relative_size_height": 8
        }
      ],
      "standard_flow": [
        {
          "state": "pending",
          "flow_name": "Firma Holográfica",
          "flow_key": "holographic_signature"
        }
      ],
      "advanced_flow": []
    }
  ],
  "created_through": "api",
  "created_at": "2026-06-23T10:00:00.000000Z",
  "updated_at": "2026-06-23T10:00:00.000000Z"
}

Nombre	Tipo	Descripción
`token`	string	Identificador único del sobre generado por FirmEasy. Guárdalo en tu base de datos para consultas y operaciones futuras.
`external_id`	string	El mismo ID externo enviado en la petición original, devuelto para validación de tu sistema.
`name`	string	Nombre normalizado del documento (en MAYÚSCULAS con extensión '.pdf').
`status`	string	Estado actual del sobre. Valores posibles: 'pending', 'signed', 'rejected'.
`original_file`	string	URL firmada para visualizar el PDF original en el navegador.
`original_download_file`	string	URL firmada para descargar directamente el PDF original.
`signed_file`	string	URL del documento firmado. Será null mientras el sobre no esté completamente firmado.
`signatures_made`	integer	Número de firmas estampadas hasta el momento. Inicia en 0.
`signers`	array	Lista de firmantes registrados, con su token individual, estado, link de firma y configuración de flujo.
`extra_docs_count`	integer	Cantidad de documentos anexos incluidos en el sobre.
`created_at`	datetime	Fecha y hora exacta de creación del sobre en formato UTC ISO 8601.

token

string

Identificador único del sobre generado por FirmEasy. Guárdalo en tu base de datos para consultas y operaciones futuras.

external_id

string

El mismo ID externo enviado en la petición original, devuelto para validación de tu sistema.

name

string

Nombre normalizado del documento (en MAYÚSCULAS con extensión '.pdf').

status

string

Estado actual del sobre. Valores posibles: 'pending', 'signed', 'rejected'.

original_file

string

URL firmada para visualizar el PDF original en el navegador.

original_download_file

string

URL firmada para descargar directamente el PDF original.

signed_file

string

URL del documento firmado. Será null mientras el sobre no esté completamente firmado.

signatures_made

integer

Número de firmas estampadas hasta el momento. Inicia en 0.

signers

array

Lista de firmantes registrados, con su token individual, estado, link de firma y configuración de flujo.

extra_docs_count

integer

Cantidad de documentos anexos incluidos en el sobre.

created_at

datetime

Fecha y hora exacta de creación del sobre en formato UTC ISO 8601.

Errores posibles

Código	Estado	Descripción
`400`	Bad Request	Request inválido (parámetros de cuerpo con sintaxis incorrecta o faltantes).
`401`	Unauthorized	No autorizado (Token JWT inválido, expirado o ausente en las cabeceras).
`422`	Unprocessable Entity	Error de validación de negocio (múltiples fuentes de archivo, flujos incompatibles).
`500`	Server Error	Error interno de los servidores de FirmEasy.

Crear Documento Síncrono