Crear Documento Síncrono

1. API
2. ›Documentos
3. ›Crear documento síncrono

POST {{base_url}}/v1/documents

Entornos

Variable {{base_url}}: Consulta los servidores en Entornos.

RequestDemoResponse

Copiar

cURLNode.jsPythonPHPGo

curl -X POST {{base_url}}/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

Probar en vivo

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

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.

Síncrono

	Síncrono POST /v1/documents
Documentos por sobre	hasta 5 (principal + 4 anexos)
Peso	50 MB total del sobre
Fuente del archivo	base64, URL
Respuesta	201 con el sobre completo
Cuándo	caso interactivo / pocos docs

---

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'

---

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)

Nota

El modelo es por peso total: un solo documento puede consumir los 50 MB completos, o distribuirse entre el principal y los anexos (ej. 2×25 MB, 5×10 MB). Para lotes más grandes, utiliza el endpoint asíncrono.

---

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. Recomendado	Excluyente
document_pdf_base64	string	Archivo PDF codificado en formato Base64.	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)

---

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

---

Documentos Adicionales

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. Recomendado	Excluyente si se usa base64 o 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[].standard_flow	array<string>	Métodos primarios de firma electrónica. Valores válidos: 'holographic_signature', 'otp_email', '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', 'video_firma', 'face_recognition'.	Máximo 2 flujos activos

Reglas Críticas de Validación (Error 422)

• Exclusividad del Certificado: Si usas digital_certificate_local, este no puede combinarse con ningún otro flujo estándar ni avanzado para ese firmante.
• Alta Seguridad: face_recognition requiere obligatoriamente el llenado correcto de document_type y document_number. Enviar este campo de identidad sin activar un flujo avanzado de alta seguridad arrojará 422.
• Límite de placements con certificado digital: Si usas digital_certificate_local, se admite máximo 1 placement por documento. Si envías varios placements al mismo documento, el sistema se queda con el primero.

---

Posicionamiento de Firma (Formatos Excluyentes)

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)

Resolución Dinámica de Referencias

En este flujo síncrono, si envías un document_ref inexistente, con un error tipográfico o vacío, el backend no arrojará error; por seguridad y consistencia, aplicará un fallback automático y colocará la firma de forma silenciosa en el documento principal (main). (Nota: Para firmas con certificado digital, se admite un límite estricto de máximo 1 placement por archivo).

"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
  }
]

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": ["holographic_signature"],
      "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
        }
      ]
    }
  ]
}

cert-only

Si el PDF enviado ya viene precargado con una firma digital, el sistema detecta el origen api y auto-corrige el flujo del firmante a digital_certificate_local, asegurando la consistencia del documento.

---

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.

---

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.