Documents & attachments

📘
Conventions
In the examples, $API_URL stands for the api_url of the connected license and $ACCESS_TOKEN for a valid access token. See Quickstart.

The API offers three ways to send files to Horus Office, depending on what should happen with them:

Goal	Endpoint
Let Horus process the document automatically into a book entry	`documents.new`
Send structured data and the document in one call	`invoices..new`, `book-entries..new` (with `multipart/form-data`)
Attach a document to an existing book entry	`book-entries.documents.new`, `book-entries.documents.annexes.new`
Store a document in the folder's library, without any book entry	`library.documents.new`

Supported file types

Pdf, Xml, CODA, SODA, and images (.jpg, .jpeg, .png).

Uploading with multipart/form-data

All uploads use the multipart/form-data content type with two fields:

Field	Content
`file`	The file's bytes.
`body`	The JSON-formatted request, the same object as the `application/json` version of the endpoint.

Always set FileName in the JSON body, including the extension.

curl -X POST "$API_URL/documents.new" \
  -H "Authorization: Bearer $ACCESS_TOKEN" \
  -F "[email protected]" \
  -F 'body={"FolderId":"83f26e75-f474-4b09-a1d3-aa698e18fbf0","FileName":"supplier-invoice.pdf","Remark":"Invoice 230601"}'

using var form = new MultipartFormDataContent();
form.Add(new ByteArrayContent(File.ReadAllBytes("supplier-invoice.pdf")), "file", "supplier-invoice.pdf");
form.Add(new StringContent(JsonSerializer.Serialize(new {
    FolderId = folderId,
    FileName = "supplier-invoice.pdf",
    Remark = "Invoice 230601"
})), "body");

var response = await http.PostAsync($"{apiUrl}/documents.new", form);

Automatic processing: documents.new

documents.new inserts a document that is processed automatically and transformed into a book entry. This is the simplest option when you only have the file, such as a scanned purchase invoice.

Field	Description
`FolderId`	Required.
`FileName`	Required, with extension.
`UserComment`	Comment from the client for the accountant.
`Remark`	Free remark, e.g. the invoice reference.
`VehicleId`	Related vehicle, if any.

The response contains the generated document Id. Use documents.info and documents.list to follow it.

Attaching to existing book entries

Endpoint	When
`book-entries.documents.new`	The entry has no document yet. Fails if a main document already exists.
`book-entries.documents.annexes.new`	The entry already has a main document; adds an annex. Fails if there is no main document yet.

{ "BookEntryId": "5b1e8a4c-3d2f-4e6a-9c7b-1f0d2e3a4b5c", "FileName": "my-invoice.pdf" }

Library documents

Library documents are stored in the folder's library and are not linked to any book entry: VAT returns, administrative or social documents, accounting reports, bank documents, permanent folder…

{
  "FolderId": "83f26e75-f474-4b09-a1d3-aa698e18fbf0",
  "Title": "VAT return Q3 2024",
  "Category": "Vat",
  "FileName": "vat-q3-2024.pdf",
  "KeyWords": ["vat", "2024"],
  "ReferenceDateMonth": 9,
  "ReferenceDateYear": 2024
}

Categories: Undefined, Vat, Admin, Social, AccountReport, Bank, PermanentFolder.

Action	Endpoint
List / get	`library.documents.list`, `library.documents.info`
Download	`library.documents.download`
Delete	`library.documents.delete`

Downloading documents

documents.download and library.documents.download return the raw bytes of the file, not JSON. Read the response as a binary stream.