06 — Archivos adjuntos

La API permite subir archivos (PDFs, imágenes, hojas de cálculo) y vincularlos a registros como facturas, productos, clientes, etc. Útil para adjuntar facturas escaneadas, fotos de productos, contratos firmados, certificados…

El proceso son dos pasos:

1. Subir el archivo → recibes su idfile
2. Vincular el idfile al registro destino (factura, cliente, producto…) mediante attachedfilerelations

Paso 1 — Subir un archivo

POST /api/3/uploadFiles
Content-Type: multipart/form-data
Token: <tu-api-key>

A diferencia del resto de endpoints, este usa multipart/form-data (no form-urlencoded).

Parámetros

Campo	Tipo	Requerido	Descripción
files[]	file	✅	El archivo a subir. Puedes mandar varios usando el mismo campo

Ejemplo con cURL

curl https://miempresa.beply.es/api/3/uploadFiles \
  -H "Token: a1b2c3d4..." \
  -F "files[]=@factura_proveedor.pdf"

Subir varios archivos en una petición

curl https://miempresa.beply.es/api/3/uploadFiles \
  -H "Token: a1b2c3d4..." \
  -F "files[]=@factura1.pdf" \
  -F "files[]=@factura2.pdf" \
  -F "files[]=@anexo.jpg"

Ejemplo con PHP

$ch = curl_init('https://miempresa.beply.es/api/3/uploadFiles');
$body = [
  'files[]' => new CURLFile('/ruta/a/factura.pdf'),
];
curl_setopt($ch, CURLOPT_HTTPHEADER, ['Token: a1b2c3d4...']);
curl_setopt($ch, CURLOPT_POST, 1);
curl_setopt($ch, CURLOPT_POSTFIELDS, $body);
curl_setopt($ch, CURLOPT_RETURNTRANSFER, true);
$response = curl_exec($ch);
$result = json_decode($response, true);

Ejemplo con JavaScript (Node 18+ o navegador)

const fs = require('node:fs')
const form = new FormData()
form.append('files[]', new Blob([fs.readFileSync('factura.pdf')]), 'factura.pdf')

const res = await fetch('https://miempresa.beply.es/api/3/uploadFiles', {
  method: 'POST',
  headers: { Token: 'a1b2c3d4...' }, // ❌ NO añadas Content-Type — fetch lo pone con el boundary correcto
  body: form,
})
const { files } = await res.json()
const idfile = files[0].idfile

Ejemplo con Python

import requests

with open('factura.pdf', 'rb') as f:
    res = requests.post(
        'https://miempresa.beply.es/api/3/uploadFiles',
        headers={'Token': 'a1b2c3d4...'},
        files={'files[]': ('factura.pdf', f, 'application/pdf')},
    )
idfile = res.json()['files'][0]['idfile']

Respuesta de éxito (ejemplo)

{
  "files": [
    {
      "idfile": 432,
      "filename": "factura_proveedor.pdf",
      "size": 145632,
      "uploaded_at": "2026-05-20T11:14:02Z"
    }
  ]
}

El idfile es la pieza clave — guárdalo para el paso 2.

📅 Nota sobre uploaded_at: este campo usa ISO 8601 con hora UTC (2026-05-20T11:14:02Z), distinto al DD-MM-YYYY del resto de fechas. Ver README — Formato de fechas.

Paso 2 — Vincular el archivo a un registro

POST /api/3/attachedfilerelations
Content-Type: application/x-www-form-urlencoded
Token: <tu-api-key>

Parámetros

Campo	Tipo	Requerido	Descripción
idfile	int	✅	El ID devuelto por el paso anterior
model	string	✅	Nombre del modelo destino (FacturaCliente, Cliente, Producto…)
modelcode	string	✅	Clave primaria del registro destino

⚠️ Atención al nombre del modelo: el campo model espera el nombre interno del modelo en PascalCase singular (FacturaCliente), NO el nombre del recurso REST (facturaclientes). Lo mismo para AlbaranCliente, PedidoCliente, Cliente, Producto, etc. Si tienes duda, consulta la tabla de “Otros modelos comunes” más abajo.

Ejemplo: vincular un PDF a una factura

curl https://miempresa.beply.es/api/3/attachedfilerelations \
  -H "Token: a1b2c3d4..." \
  -d "idfile=432" \
  -d "model=FacturaCliente" \
  -d "modelcode=5821"

Otros modelos comunes

Modelo	Para vincular archivos a…
FacturaCliente	Facturas emitidas
FacturaProveedor	Facturas recibidas
AlbaranCliente, AlbaranProveedor	Albaranes
PedidoCliente, PedidoProveedor	Pedidos
PresupuestoCliente, PresupuestoProveedor	Presupuestos
Cliente	Fichas de cliente (ej. contratos firmados)
Proveedor	Fichas de proveedor
Producto	Productos (ej. fotos, fichas técnicas)

Restricciones

• Extensiones bloqueadas: archivos .php están prohibidos por seguridad. Si intentas subir uno, la API rechaza la petición.
• Renombrado automático: los nombres se sanean al guardar en el servidor para evitar colisiones y caracteres problemáticos. El nombre original se conserva como metadato.
• Tamaño máximo: depende de la configuración de la instancia Beply (por defecto suele ser 8-16 MB; consulta a tu administrador o a soporte).

Listar archivos vinculados a un registro

Usa el recurso genérico attachedfilerelations con filtros:

GET /api/3/attachedfilerelations?filter[model]=FacturaCliente&filter[modelcode]=5821

Te devuelve todos los idfile asociados a esa factura. Luego puedes descargar cada uno si lo necesitas.

Próximos pasos

• 04 — Facturas: adjuntar el justificante de pago a una factura
• 07 — Errores y validaciones: qué pasa si el archivo no se sube