Ir al contenido
FirmEasy
← Inicio

Obtener documento

GET
https://api.firmeasy.legal/api/v1/documents/{{token}}

Obtener documento

Sección titulada «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

Sección titulada «Autenticación»
Authorization
string
Token de acceso obtenido en el proceso de login, con el prefijo 'Bearer'.
Límites:Obligatorio

Parámetros de Ruta

Sección titulada «Parámetros de Ruta»
token
string
Identificador único (UUID) del documento devuelto al momento de crearlo.
Límites:Obligatorio

Parámetros de Consulta

Sección titulada «Parámetros de Consulta»
include[]
string[]
Permite expandir relaciones del objeto. Usa 'children' para incluir el array completo de anexos (extra_docs). Ej: ?include[]=children
Límites:Opcional

Respuesta Exitosa (200 OK)

Sección titulada «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": "https://api.firmeasy.legal/api/v1/files/...?intent=view&signature=...",
  "signed_file": null,
  "original_download_file": "https://api.firmeasy.legal/api/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": "https://api.firmeasy.legal/api/v1/files/.../?intent=view&...",
      "signed_file": null,
      "original_download_file": "https://api.firmeasy.legal/api/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"
}
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?

Sección titulada «¿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

Sección titulada «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.