Descarga de documento

Este endpoint permite descargar un documento específico asociado a un proceso de firma.

La respuesta no es JSON, sino el archivo binario del documento (generalmente PDF).

Endpoint

POST https://www.sandboxadmin.firmaris.co/api/integrations/download/

Headers requeridos

x-api-key: Bearer {TOKEN_EMPRESA}

Body (form-data)

Parámetro	Tipo	Requerido	Descripción	Validaciones
`documentId`	string	Sí	ID único del documento a descargar	Hash válido de documento existente

Ejemplo en Postman

{
  "method": "POST",
  "url": "https://www.sandboxadmin.firmaris.co/api/integrations/download/",
  "headers": {
    "x-api-key": "Bearer sandbox_token_empresa_123"
  },
  "body": {
    "mode": "formdata",
    "formdata": [
      {
        "key": "documentId",
        "value": "903ff1a6d093cd4c874c3db682e785c2cd55e6a52444acf67547a27a8a2ed4ad"
      }
    ]
  }
}

Respuesta exitosa (200 OK)

Headers de respuesta

HTTP/1.1 200 OK
Content-Type: application/pdf
Content-Disposition: attachment; filename="contrato_firmado.pdf"
Content-Length: 245678
Cache-Control: private, max-age=86400
Last-Modified: Wed, 22 May 2025 16:46:25 GMT

Características de la respuesta

Tipo de contenido: application/pdf
Modo: descarga forzada (attachment)
Nombre del archivo: viene en el header Content-Disposition
Body: binario (no JSON)

Consideraciones importantes

Este endpoint no devuelve JSON cuando es exitoso
El cuerpo de la respuesta es el archivo completo
Si ocurre un error, sí se devuelve JSON
El archivo puede ser grande, se recomienda manejarlo por streams

Respuestas de error

Error 400 — `documentId` inválido

{
  "success": false,
  "status": 400,
  "error": {
    "message": "El parámetro (documentId) no contiene un formato válido."
  }
}

Causas comunes:

documentId vacío
Hash con formato incorrecto
Caracteres inválidos

Error 403 — Acceso denegado

{
  "success": false,
  "status": 403,
  "error": {
    "message": "Acceso denegado. No tiene los permisos necesarios para acceder a este recurso."
  }
}

Causas comunes:

Token inválido o expirado
El documento pertenece a otra empresa

Error 404 — Documento no encontrado

{
  "success": false,
  "status": 404,
  "error": {
    "message": "El recurso al que intenta acceder no existe."
  }
}

Error 500 — Error interno

{
  "success": false,
  "status": 500,
  "error": {
    "message": "Se ha producido un error interno, no ha sido posible descargar el documento, inténtelo de nuevo."
  }
}

Checklist de validación

Antes de descargar un documento, verifica:

Token API válido
documentId con formato correcto
Documento existente
Permisos sobre el documento
Documento no está eliminado ni anulado

Notas técnicas

Seguridad

Cada descarga queda registrada para auditoría
No existe acceso público a documentos
No se recomienda exponer este endpoint directamente al navegador sin backend intermedio

Rendimiento

Para documentos grandes, usar descarga por chunks
Definir timeout adecuado (mínimo 30 segundos)
Evitar múltiples descargas simultáneas del mismo archivo

Buenas prácticas

Validar el documentId localmente antes de enviar
Manejar errores JSON incluso cuando se espera binario
Extraer siempre el nombre del archivo desde headers
No cachear documentos sensibles en cliente

Este endpoint es fundamental para recuperación, archivo y distribución de documentos firmados dentro de cualquier flujo de integración con Firmaris.