Crear Documento Asíncrono

POST

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

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.

curl -X POST https://api.firmeasy.legal/api/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

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

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)

Idempotency-Key

uuid

Identificador único generado por el cliente. Si la ingesta original aún está en proceso y reintentas, devolverá código 409.

Límites: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[].file_format`	enum	Formato del archivo.	Solo admite 'pdf'
`documents[].role`	enum	Rol del archivo dentro del sobre.	Solo admite 'sign'
`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

name

string

Nombre del sobre (se normaliza a MAYÚSCULAS y se le añade .pdf).

Límites:Obligatorio

documents

array

Lista de 1 a 100 documentos. El primer elemento (posición 0) siempre será considerado el documento principal.

Límites:Obligatorio

documents[].ref_id

string

Identificador único. Para el principal es opcional (por defecto 'main'). Para los anexos es obligatorio y único.

Límites:Obligatorio en anexos

documents[].source_type

enum

Tipo de fuente del archivo.

Límites:Solo admite 'url'

documents[].file_format

enum

Formato del archivo.

Límites:Solo admite 'pdf'

documents[].role

enum

Rol del archivo dentro del sobre.

Límites:Solo admite 'sign'

documents[].source_payload.url

url

URL pública desde donde se descargará el documento.

Límites:Máx: 2048 caracteres

callback_url

url

Webhook de un solo uso (one-shot) que será invocado cuando la ingesta termine (éxito o fallo).

Límites: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.

Límites:Opcional

external_id

string(255)

ID externo libre asignado por el integrador (pass-through). Se copia al documento resultante.

Límites:Opcional

metadata

object

Objeto JSON libre de almacenamiento llave-valor para guardar metadatos personalizados. Se copia al documento resultante.

Límites: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
`lang`	enum	Idioma de la interfaz y comunicaciones. Valores: 'es', 'en', 'pt'.	Por defecto: 'es'
`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

folder_token

uuid

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

Límites:Debe ser un UUID válido

lang

enum

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

Límites:Por defecto: 'es'

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

is_signature_order_active

bool

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

Límites:Por defecto: false

is_rejection_allowed

bool

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

Límites:Por defecto: false

is_original_download_allowed

bool

Permite al firmante descargar el PDF original limpio antes de firmar.

Límites:Por defecto: true

disable_owner_notifications

bool

Desactiva alertas por correo hacia el propietario del sobre.

Límites:Por defecto: false

disable_signer_notifications

bool

Desactiva alertas automáticas hacia los firmantes.

Límites:Por defecto: false

send_automatic_invitations

bool

Dispara invitaciones al crear el sobre.

Límites:Por defecto: true

send_automatic_invitations_by

enum

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

Límites:Opcional

send_signed_document_by_whatsapp

bool

Envía copia del documento finalizado por WhatsApp.

Límites:Por defecto: false

reminder_every_n_days

int

Frecuencia en días para recordatorios automáticos (0 a 30).

Límites:0 para desactivar

observers

array<string>

Lista de correos de observadores con acceso de solo lectura (máx 20).

Límites:Array de emails

redirect_link

string(255)

URL de redirección post-firma.

Límites:Debe ser una URL válida

created_by

Correo del usuario creador de la solicitud.

Límites:Formato de email

sender_name

string(150)

Nombre del solicitante mostrado al firmante. Si se omite, se usa el del propietario.

Límites:Máx 150 caracteres

reply_to_email

Dirección para recibir respuestas de las notificaciones.

Límites:Formato de email

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": "[https://api.firmeasy.legal/api/v1/documents/envelopes/01234567-89ab-cdef-0123-456789abcdef/status](https://api.firmeasy.legal/api/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.

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

{
  "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.

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.