📎 Subir ficheros y adjuntarlos a un registro

Con la API pública puedes subir un fichero al almacenamiento del workspace y adjuntarlo a un campo de tipo archivo de cualquier registro. Son dos peticiones: primero subes el fichero y después guardas su referencia en el registro.

Antes de empezar

• Necesitas una clave API del workspace. En los ejemplos se lee de la variable de entorno ZINKEE_API_KEY.
• Necesitas el identificador de la tabla (schemaId) y el slug del campo de tipo archivo. Puedes consultarlos con GET /api/v2/schemas/{schemaId}: los campos de tipo archivo aparecen con el tipo FileField.

---

1. Subir el fichero

Envía el fichero con POST /api/v2/files como multipart/form-data, en una única parte llamada file:

curl https://api-z2.zinkee.com/api/v2/files   
  --header "Authorization: Bearer $ZINKEE_API_KEY"   
  --form "file=@contrato.pdf"

La API responde con el identificador del fichero:

{
  "id": "d290f1ee-6c54-4b01-90e6-d701748f0851"
}

Guarda el nombre y el tipo del fichero

Zinkee solo almacena el contenido del fichero. El nombre y el tipo MIME (por ejemplo, application/pdf) los envías tú en el paso siguiente, así que consérvalos junto al identificador.

2. Adjuntarlo al registro

Un campo de tipo archivo guarda una lista de ficheros. Cada elemento lleva:

Propiedad	Qué contiene
id	El identificador que devolvió la subida.
name	El nombre que Zinkee mostrará en el registro, por ejemplo contrato.pdf.
type	El tipo MIME del fichero, por ejemplo application/pdf.

Para adjuntarlo a un registro que ya existe, usa PATCH /api/v2/schemas/{schemaId}/records/{recordId} con el slug del campo en set. En este ejemplo, el campo se llama adjuntos:

curl https://api-z2.zinkee.com/api/v2/schemas/$SCHEMA_ID/records/$RECORD_ID   
  --request PATCH   
  --header "Authorization: Bearer $ZINKEE_API_KEY"   
  --header "Content-Type: application/json"   
  --data '{
    "set": {
      "adjuntos": [
        {
          "id": "d290f1ee-6c54-4b01-90e6-d701748f0851",
          "name": "contrato.pdf",
          "type": "application/pdf"
        }
      ]
    }
  }'

Para crear un registro con el fichero ya adjunto, envía la misma lista en el campo correspondiente de POST /api/v2/schemas/{schemaId}/records.

La lista sustituye a la anterior

El valor que envías reemplaza todos los ficheros del campo. Para añadir un fichero sin perder los que ya tenía el registro, lee antes el registro e incluye en la lista los elementos existentes junto al nuevo.

3. Leer los ficheros de un registro

Al consultar el registro, el campo de tipo archivo se devuelve como un texto con la lista en formato JSON:

{
  "recordId": "550e8400-e29b-41d4-a716-446655440000",
  "values": {
    "adjuntos": "[{\"id\":\"d290f1ee-6c54-4b01-90e6-d701748f0851\",\"name\":\"contrato.pdf\",\"type\":\"application/pdf\"}]"
  }
}

Interpreta ese texto como JSON para obtener la lista. Con cada id puedes descargar el fichero mediante GET /api/v2/files/{fileId}.

---

Eliminar un fichero

DELETE /api/v2/files/{fileId} borra el fichero del almacenamiento, pero no lo quita de los registros que lo tengan adjunto. Actualiza también el campo del registro con la lista sin ese elemento; si no, el registro seguirá mostrando un fichero que ya no se puede descargar.

Límites

• Cada workspace dispone de 5 GB de almacenamiento para ficheros. Consulta el espacio usado con GET /api/v2/files/storage-info; los valores se expresan en bytes.
• Si una subida supera el espacio disponible, la API responde con el código 400 y el fichero no se guarda.

Consulta todos los parámetros y respuestas en la referencia de la API.