Ejemplos — Descarga de documento

Esta sección muestra ejemplos reales de uso del endpoint de descarga de documentos.

Los ejemplos permiten entender:

• Cómo enviar el documentId
• Qué tipo de respuesta esperar
• Cómo manejar correctamente errores

---

Ejemplo 1 — Descarga exitosa de un documento

Request

POST https://www.sandboxadmin.firmaris.co/api/integrations/download/
x-api-key: Bearer sandbox_token_empresa_123

Body (form-data)

key	value
documentId	903ff1a6d093cd4c874dt565g682e785c2cd55e6a52444acf67547a27a8a2ed4ad

---

Respuesta exitosa

La respuesta no es JSON.
El backend devuelve directamente el archivo.

Headers de respuesta

HTTP/1.1 200 OK
Content-Type: application/pdf
Content-Disposition: attachment; filename="contrato_firmado.pdf"
Content-Length: 245678

El cuerpo contiene el binario del PDF.

---

Ejemplo 2 — Manejo de descarga desde navegador

Este ejemplo ilustra el flujo típico cuando el backend responde correctamente.

Flujo esperado

1. El cliente envía el documentId
2. El backend valida permisos
3. El archivo se envía como attachment
4. El navegador fuerza la descarga

No se retorna estructura JSON.

---

Ejemplo 3 — Error por documentId inválido

Sucede cuando el documentId no cumple las reglas de validación.

Request

POST https://www.sandboxadmin.firmaris.co/api/integrations/download/
x-api-key: Bearer sandbox_token_empresa_123

Body (incorrecto)

{
  "documentId": "documento_invalido"
}

---

Respuesta de error

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

---

Ejemplo 4 — Documento no encontrado

Ocurre cuando el documento no existe o fue eliminado.

Respuesta

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

---

Ejemplo 5 — Error por falta de permisos

Sucede cuando el token no pertenece a la empresa dueña del documento.

Respuesta

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

---

Ejemplo 6 — Error interno del sistema

Error inesperado durante la generación o lectura del archivo.

Respuesta

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

---

Resumen rápido

• La respuesta exitosa no es JSON
• El archivo se entrega como application/pdf
• El nombre se obtiene desde Content-Disposition
• Los errores siempre retornan JSON
• El documentId debe existir y pertenecer a la empresa del token

Estos ejemplos cubren los casos reales más comunes al consumir el endpoint de descarga de documentos.