Ir al contenido

Obtener documento

GET {{base_url}}/v1/documents/{{token}}

Obtener documento

Obtiene el detalle completo, el estado de las firmas y los enlaces de un documento (sobre) específico mediante su token identificador.

Autenticación

Parámetro	Tipo	Descripción	Límites
`Authorization*`	string	Token de acceso obtenido en el proceso de login, con el prefijo 'Bearer'.	Obligatorio

Parámetros de Ruta

Parámetro	Tipo	Descripción	Límites
`token*`	string	Identificador único (UUID) del documento devuelto al momento de crearlo.	Obligatorio

Parámetros de Consulta

Parámetro	Tipo	Descripción	Límites
`include[]`	string[]	Permite expandir relaciones del objeto. Usa 'children' para incluir el array completo de anexos (extra_docs). Ej: ?include[]=children	Opcional

Respuesta Exitosa (200 OK)

Devuelve el objeto Documento con su estado actual. Si se incluye ?include[]=children en la consulta, el array extra_docs vendrá poblado con los detalles de los anexos.

{
  "external_id": "ERP-123",
  "token": "abcdef01-...",
  "name": "CONTRATO DE PRESTACIÓN DE SERVICIOS N°9.pdf",
  "folder": { "token": "uuid", "name": "Carpeta" },
  "status": "pending",
  "lang": "es",
  "size": 245100,
  "original_file": "{{base_url}}/v1/files/...?intent=view&signature=...",
  "signed_file": null,
  "original_download_file": "{{base_url}}/v1/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": [
    {
      "token": "anexo-token",
      "name": "Anexo 1 - Tarifario 2026.pdf",
      "original_file": "{{base_url}}/v1/files/.../?intent=view&...",
      "signed_file": null,
      "original_download_file": "{{base_url}}/v1/files/.../?intent=download&...",
      "signed_download_file": null,
      "uploaded_by": { "email": "[email protected]" }
    }
  ],
  "extra_docs_count": 1,
  "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",
      "identifier": "...",
      "link": "https://app.firmeasy.legal/...",
      "signed_at_hour": null,
      "signed_at": null,
      "position_x": null,
      "position_y": null,
      "page": null,
      "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 Digital Local",
          "flow_key": "digital_certificate_local"
        }
      ],
      "advanced_flow": [],
      "created_through": "api",
      "send_automatic_invitations": true,
      "send_signed_document_by_whatsapp": false,
      "geo_latitude": null,
      "geo_longitude": null,
      "lang": "es",
      "created_at": "2026-06-23T10:00:00.000000Z",
      "updated_at": "2026-06-23T10:00:00.000000Z"
    }
  ],
  "tracking": [],
  "created_through": "api",
  "reminder_every_n_days": 0,
  "send_automatic_invitations": true,
  "send_signed_document_by_whatsapp": false,
  "is_rejection_allowed": true,
  "is_signature_order_active": false,
  "redirect_link": null,
  "observers": [],
  "metadata": { "order_id": "12345" },
  "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.
`external_id`	string	ID externo asignado por el integrador al momento de crear el documento.
`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. Expira en 60 minutos.
`signed_file`	string	URL del documento firmado. Null mientras el sobre no esté completamente firmado.
`original_download_file`	string	URL firmada para descargar directamente el PDF original. Expira en 60 minutos.
`signed_download_file`	string	URL para descargar el documento firmado. Null hasta que todas las firmas estén completas.
`signatures_made`	integer	Número de firmas estampadas hasta el momento.
`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. Se puebla solo si se envía ?include[]=children en la consulta.
`signers`	array	Lista de firmantes con su estado, link de firma, flujos configurados y posiciones de firma.
`tracking`	array	Historial de eventos del sobre.
`metadata`	object	Objeto JSON libre de llave-valor con metadatos personalizados enviados al crear el sobre.
`created_at`	datetime	Fecha y hora exacta de creación del sobre en formato UTC ISO 8601.
`updated_at`	datetime	Fecha y hora de la última modificación del sobre en formato UTC ISO 8601.

¿Dónde aparecen `extra_docs` y `extra_docs_count`?

Endpoint / Contexto	`extra_docs`	`extra_docs_count`
`POST /v1/documents` (201)	siempre	—
Webhooks `document_created` / `document_completed`	siempre	—
`GET /v1/documents/{{token}}`	con `?include[]=children`	—
`GET /v1/documents` (listado)	con `?include[]=children`	siempre

extra_docs es un array de anexos con sus tokens, nombres y URLs de descarga. extra_docs_count es un contador entero que siempre se incluye en el listado para conocer la cantidad de anexos sin necesidad de expandir la relación.

Errores posibles

Código	Estado	Descripción
`401`	Unauthorized	El token de autenticación es inválido, expiró o no fue enviado.
`404`	Not Found	El `token` del documento no existe o no pertenece a la organización asociada.