Documentos multi-archivo

La API de Signatura permite cargar documentos que contienen múltiples archivos PDF. Esto es útil cuando un proceso de firma involucra varios documentos que deben ser firmados en conjunto, por ejemplo, un contrato principal junto con sus anexos.

Diferencias con documentos de un solo archivo

Aspecto	Un solo archivo	Múltiples archivos
Campo de carga	file_content	files
Descarga de PDF	Devuelve el archivo directamente	Requiere el parámetro file para elegir qué archivo descargar
Certificado de auditoría	Un certificado por documento	Un certificado por cada archivo
Archivo ZIP	Contiene todo en un solo paquete	Contiene todos los archivos y sus firmas

Cargar un documento multi-archivo

Para cargar un documento con múltiples archivos, usa el campo files en lugar de file_content. Ambos campos son mutuamente excluyentes.

Endpoint

POST /api/v2/documents/create
Content-Type: application/json
Authorization: Bearer <apikey>

Ejemplo de solicitud

{
  "title": "Contrato de locación con anexos",
  "files": [
    {
      "name": "contrato_principal.pdf",
      "content": "<base64-del-contrato>"
    },
    {
      "name": "anexo_condiciones.pdf",
      "content": "<base64-del-anexo>"
    }
  ],
  "signatures": [
    {
      "validations": {"EM": "inquilino@example.com"},
      "invite_channel": ["EM"]
    }
  ]
}

Campos del objeto files

Campo	Tipo	Descripción
name	string (máx. 254 caracteres)	Nombre del archivo, incluyendo extensión .pdf
content	string (base64)	Contenido del archivo PDF codificado en base64

Importante

No puedes combinar file_content y files en la misma solicitud. Si necesitas cargar un solo archivo, puedes usar cualquiera de los dos campos.

Requisitos de los archivos

Cada archivo en el array files debe cumplir los mismos requisitos que un documento de archivo único:

• Debe ser un PDF válido
• No puede estar protegido por contraseña
• Debe estar codificado en base64 según el RFC 4648
• No debe contener errores de formato
• El peso total de todos los archivos no debe superar los 50 MB

Obtener los IDs de cada archivo

Al consultar un documento con GET /api/v2/documents/{id}, la respuesta incluye un array files con la información de cada archivo:

{
  "id": "497f6eca-6276-4993-bfeb-53cbbbba6f08",
  "title": "Contrato de locación con anexos",
  "status": "PE",
  "files": [
    {
      "id": "8a3b5c7d-1234-5678-abcd-ef0123456789",
      "name": "contrato_principal.pdf",
      "digest": "a1b2c3d4e5f6...",
      "order": 0
    },
    {
      "id": "c4d5e6f7-8901-2345-bcde-f67890123456",
      "name": "anexo_condiciones.pdf",
      "digest": "f6e5d4c3b2a1...",
      "order": 1
    }
  ],
  "signatures": [...]
}

Campo	Tipo	Descripción
id	UUID	Identificador único del archivo, necesario para descargarlo individualmente
name	string	Nombre del archivo tal como fue enviado en la carga
digest	string	Hash del contenido del archivo, útil para verificar integridad
order	integer	Posición del archivo dentro del documento (comienza en 0)

Descargar archivos individuales

En un documento multi-archivo, los endpoints de descarga de PDF y certificado de auditoría aceptan un parámetro opcional file para especificar qué archivo descargar. Si se omite, se devuelve el primer archivo (el de order: 0).

Descargar un PDF específico

GET /api/v2/documents/{id}/download/document?file={file_id}
Authorization: Bearer <apikey>

# Descargar un archivo específico por su ID
curl -X GET "https://connect.signatura.co/api/v2/documents/497f6eca-6276-4993-bfeb-53cbbbba6f08/download/document?file=8a3b5c7d-1234-5678-abcd-ef0123456789" \
  -H "Authorization: Bearer <apikey>" \
  -o contrato_principal.pdf

Si omitís el parámetro file, se descarga el primer archivo del documento:

# Descargar el primer archivo (sin especificar file)
curl -X GET "https://connect.signatura.co/api/v2/documents/497f6eca-6276-4993-bfeb-53cbbbba6f08/download/document" \
  -H "Authorization: Bearer <apikey>" \
  -o primer_archivo.pdf

Descargar el certificado de auditoría de un archivo

Cada archivo de un documento multi-archivo tiene su propio certificado de auditoría. Usá el mismo parámetro file para descargar el certificado correspondiente:

GET /api/v2/documents/{id}/download/pdf-certificate?file={file_id}
Authorization: Bearer <apikey>

# Certificado de auditoría del contrato principal
curl -X GET "https://connect.signatura.co/api/v2/documents/497f6eca-6276-4993-bfeb-53cbbbba6f08/download/pdf-certificate?file=8a3b5c7d-1234-5678-abcd-ef0123456789" \
  -H "Authorization: Bearer <apikey>" \
  -o certificado_contrato.pdf

# Certificado de auditoría del anexo
curl -X GET "https://connect.signatura.co/api/v2/documents/497f6eca-6276-4993-bfeb-53cbbbba6f08/download/pdf-certificate?file=c4d5e6f7-8901-2345-bcde-f67890123456" \
  -H "Authorization: Bearer <apikey>" \
  -o certificado_anexo.pdf

Descargar el ZIP completo

El archivo ZIP siempre contiene todos los archivos del documento junto con sus firmas digitales y metadatos, sin necesidad de especificar un archivo individual:

curl -X GET "https://connect.signatura.co/api/v2/documents/497f6eca-6276-4993-bfeb-53cbbbba6f08/download/zipfile" \
  -H "Authorization: Bearer <apikey>" \
  -o documento_completo.zip

tip

El archivo ZIP es la forma más sencilla de obtener todos los archivos y sus pruebas de firma en una sola descarga. No requiere conocer los IDs individuales de cada archivo.

Resumen de endpoints de descarga

El parámetro file corresponde al id de cada archivo obtenido al consultar el documento.

Endpoint	Parámetro file	Comportamiento si se omite
download/document	Opcional (UUID)	Devuelve el primer archivo
download/pdf-certificate	Opcional (UUID)	Devuelve el certificado del primer archivo
download/zipfile	No aplica	Siempre incluye todos los archivos

Códigos de respuesta

Código	Descripción
200	Archivo descargado correctamente
400	Error en la solicitud (por ejemplo, UUID de archivo inválido)
404	El documento o archivo no existe
429	Demasiadas solicitudes (rate limiting)

Buenas prácticas

• Usá nombres descriptivos: Asigná nombres claros a cada archivo en el campo name para facilitar su identificación posterior.
• Descargá el ZIP para archivar: El archivo ZIP es la prueba más completa y no requiere descargar cada archivo por separado.
• Automatizá con webhooks: Configurá un webhook para descargar automáticamente cuando el documento alcance el estado CO (completado).
• Respetá los límites: El peso total de todos los archivos no debe superar los 50 MB. Tené en cuenta los límites de tasa al descargar múltiples archivos.