Crear Documento Asíncrono

1. API
2. ›Documentos
3. ›Crear Documento Asíncrono

POST {{base_url}}/v1/documents/envelopes/async

Entornos

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

RequestDemoResponse

Copiar

cURLNode.jsPythonPHPGo

curl -X POST {{base_url}}/v1/documents/envelopes/async \
-H "Authorization: Bearer TU_TOKEN_AQUI" \
-H "Content-Type: application/json" \
-d '{
  "name": "Contrato de Servicios",
  "documents": [{
    "ref_id": "main",
    "source_type": "url",
    "file_format": "pdf",
    "role": "sign",
    "source_payload": { "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 Asíncrono

A diferencia del método síncrono, este endpoint acepta lotes masivos en una sola llamada y responde inmediatamente con un código 202 Accepted y un ingest_token. El sobre se arma en segundo plano (background) descargando los archivos en paralelo.

---

---

Límites de Ingesta Asíncrona

Límite	Valor
Documentos máximos por sobre	100
Peso máximo por documento	~100 MB
Peso máximo total del sobre	1 GB
Fuente soportada (V1)	Solo URL

---

Cabecera Opcional (Idempotencia)

Para evitar duplicados en caso de fallas de red, puedes enviar una llave de idempotencia. Si reintentas la misma llamada, el servidor devolverá la misma respuesta cacheada (TTL de 30 minutos).

Parámetro	Tipo	Descripción	Límites
Idempotency-Key	uuid	Identificador único generado por el cliente. Si la ingesta original aún está en proceso y reintentas, devolverá código 409.	Cabecera HTTP (Header)

---

Cuerpo de la solicitud

Parámetro	Tipo	Descripción	Límites
name*	string	Nombre del sobre (se normaliza a MAYÚSCULAS y se le añade .pdf).	Obligatorio
documents*	array	Lista de 1 a 100 documentos. El primer elemento (posición 0) siempre será considerado el documento principal.	Obligatorio
documents[].ref_id	string	Identificador único. Para el principal es opcional (por defecto 'main'). Para los anexos es obligatorio y único.	Obligatorio en anexos
documents[].source_type	enum	Tipo de fuente del archivo.	Solo admite 'url'
documents[].source_payload.url*	url	URL pública desde donde se descargará el documento.	Máx: 2048 caracteres
callback_url	url	Webhook de un solo uso (one-shot) que será invocado cuando la ingesta termine (éxito o fallo).	Máx: 2048 caracteres
callback_secret	string	Llave secreta. Si se envía, el payload del webhook irá firmado mediante HMAC-SHA256 en la cabecera X-Firmeasy-Signature-SHA256.	Opcional
external_id	string(255)	ID externo libre asignado por el integrador (pass-through). Se copia al documento resultante.	Opcional
metadata	object	Objeto JSON libre de almacenamiento llave-valor para guardar metadatos personalizados. Se copia al documento resultante.	Pass-through

Configuración del sobre (opcional)

El endpoint asíncrono acepta los mismos campos de configuración que el endpoint síncrono:

Parámetro	Tipo	Descripción	Límites
folder_token	uuid	Token de la carpeta destino donde se guardará el documento.	Debe ser un UUID válido
signature_deadline	ISO8601	Fecha y hora límite futura para completar las firmas (ej. '2026-12-31T23:59:59.000Z').	Formato UTC completo
is_signature_order_active	bool	Fuerza a que los firmantes sigan estrictamente el orden jerárquico establecido.	Por defecto: false
is_rejection_allowed	bool	Habilita el botón para que un firmante pueda rechazar formalmente el documento.	Por defecto: false
is_original_download_allowed	bool	Permite al firmante descargar el PDF original limpio antes de firmar.	Por defecto: true
disable_owner_notifications	bool	Desactiva alertas por correo hacia el propietario del sobre.	Por defecto: false
disable_signer_notifications	bool	Desactiva alertas automáticas hacia los firmantes.	Por defecto: false
send_automatic_invitations	bool	Dispara invitaciones al crear el sobre.	Por defecto: true
send_automatic_invitations_by	enum	Medio de envío de invitaciones. Valores: 'email' o 'whatsapp'.	Opcional
send_signed_document_by_whatsapp	bool	Envía copia del documento finalizado por WhatsApp.	Por defecto: false
reminder_every_n_days	int	Frecuencia en días para recordatorios automáticos (0 a 30).	0 para desactivar
observers	array<string>	Lista de correos de observadores con acceso de solo lectura (máx 20).	Array de emails
redirect_link	string(255)	URL de redirección post-firma.	Debe ser una URL válida
created_by	email	Correo del usuario creador de la solicitud.	Formato de email
sender_name	string(150)	Nombre del solicitante mostrado al firmante. Si se omite, se usa el del propietario.	Máx 150 caracteres
reply_to_email	email	Dirección para recibir respuestas de las notificaciones.	Formato de email

Firmantes (Signers)

El endpoint asíncrono acepta exactamente la misma estructura de firmantes y placements (signers[]) que el endpoint Síncrono, incluyendo flujos estándar/avanzado, placements con porcentajes y posiciones legacy.

Estricto con Referencias

A diferencia del método síncrono, el asíncrono es estricto: si en placements[].document_ref envías una referencia que no existe en tu arreglo de documents[], la API devolverá un error 422 en lugar de auto-asignarlo al principal.

---

Respuesta de Ingesta

Si la solicitud es válida, el sistema responde inmediatamente con un token de ingesta. El tiempo estimado se calcula como min(1800, 10 + n·5) segundos, donde n es el número de documentos.

Si la solicitud es válida, el sistema responderá que ha comenzado el proceso.

{
  "ingest_token": "01234567-89ab-cdef-0123-456789abcdef",
  "status": "ingesting",
  "documents_total": 2,
  "credits_cost": 2,
  "status_url": "[{{base_url}}/v1/documents/envelopes/01234567-89ab-cdef-0123-456789abcdef/status]({{base_url}}/v1/documents/envelopes/01234567-89ab-cdef-0123-456789abcdef/status)",
  "estimated_processing_time_seconds": 20
}

Nombre	Tipo	Descripción
ingest_token	string	Identificador único de la ingesta. Guárdalo para consultar el estado o cancelar el proceso.
status	string	Estado inicial de la ingesta. Valor devuelto: 'ingesting'.
documents_total	integer	Cantidad total de documentos recibidos para procesar en este lote.
credits_cost	integer	Créditos que se descontarán al finalizar exitosamente. Si la ingesta falla, no se cobra.
status_url	string	URL para consultar el progreso del armado del sobre en tiempo real.
estimated_processing_time_seconds	integer	Estimación en segundos del tiempo que tomará completar la ingesta.

Nota sobre facturación: Se cobra 1 crédito por documento recién al finalizar exitosamente el armado. Si la ingesta falla, no se descuentan créditos. Si el saldo de la organización es firmas_disponibles < -500, la operación se rechaza con código 402.

---

Consultar Estado de la Ingesta

Permite verificar el progreso del armado del sobre. Cuando alcanza el estado ready, el sistema te devolverá el document_token real definitivo.

Consulta la página dedicada para más detalle: Estado de la ingesta.

Endpoint: GET /v1/documents/envelopes/{{ingest_token}}/status

Estados posibles: ingesting → assembling → ready (éxito) | failed | cancelled.

Códigos de error adicionales: 402 si la organización tiene saldo insuficiente (firmas_disponibles < -500).

---

Cancelar Ingesta en Curso

Si el documento aún está en proceso, puedes enviar la orden de abortar.

Consulta la página dedicada para más detalle: Cancelar ingesta.

Endpoint: POST /v1/documents/envelopes/{{ingest_token}}/cancel

Responderá con código 200 si se cancela correctamente. Si el sobre ya está en estado terminal (ready, failed o cancelled), devolverá un error 409.

---

Objeto Documento (Respuesta Final / Webhooks)

Una vez que el documento es procesado, el sistema consolida el sobre completo. Esta es la estructura que obtendrás al consultar el documento mediante la API (o a través de Webhooks de creación).

cert-only

Si durante la ingesta se detecta que algún PDF ya viene prefirmado, el sistema auto-corrige el flujo de esos firmantes a digital_certificate_local para mantener la consistencia del documento.

Novedad: Anexos y Conteos

El objeto ahora incluye extra_docs (arreglo de los anexos y sus links temporales, siempre presente en el create y webhooks) y extra_docs_count (cantidad de anexos agregados). Las URLs de descarga expiran en 60 minutos por seguridad.

{
  "external_id": "ERP-123",
  "token": "abcdef01-2345-6789-abcd-ef0123456789",
  "name": "CONTRATO_LOTE_MASIVO.pdf",
  "folder": { "token": "uuid", "name": "Carpeta" },
  "status": "pending",
  "lang": "es",
  "size": 245100,
  "original_file": "https://.../files/...?intent=view&signature=...",
  "signed_file": null,
  "original_download_file": "https://.../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": 2,
  "extra_docs": [
    {
      "token": "anexo-token",
      "name": "Anexo 1 - Tarifario 2026.pdf",
      "original_file": "https://.../?intent=view&...",
      "signed_file": null,
      "original_download_file": "https://.../?intent=download&...",
      "signed_download_file": null,
      "uploaded_by": { "email": "[email protected]" }
    }
  ],
  "signers": [
    {
      "external_id": null,
      "token": "signer-api-id",
      "status": "pending",
      "rejection_reason": null,
      "order": 1,
      "name": "Jane Doe",
      "email": "[email protected]",
      "phone": "900000001",
      "country_code": "+51",
      "document_type": "dni",
      "document_number": "900000003",
      "role": "signer",
      "link": "[https://app.firmeasy.legal/](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 para consultas y operaciones futuras.
external_id	string	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. Valor inicial: 'pending'.
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. Null mientras el sobre no esté completamente firmado.
signatures_made	integer	Número de firmas estampadas hasta el momento. Inicia en 0.
extra_docs_count	integer	Cantidad de documentos anexos incluidos en el sobre.
extra_docs	array	Lista de anexos con sus tokens y URLs de descarga. Las URLs expiran en 60 minutos.
signers	array	Lista de firmantes registrados con su token individual, estado, link de firma y configuración de flujo.
created_at	datetime	Fecha y hora exacta de creación del sobre en formato UTC ISO 8601.