Information about File ID:
The property fileId used in the fileattachments API is fetched using the /3/inbox endpoint or the /3/archive endpoint where the field ArchiveFileId is given.
Files that can be connected:
Only the file type: PDF are allowed to be connected as attachments to Offers/orders/invoices.
Files located in the following inboxes can be connected to an entity:
- inbox/inbox_kf (invoices)
- inbox/inbox_o (orders)
- inbox/inbox_of (offers)
Listing already connected files via ext. API:
Examples:
- All folders for already connected files for 2019: GET /3/archive/fndoc2019
- All already connected files for invoices in March 2019: GET /3/archive/fndoc201903f
O = Orders
OF = Offers
F = Invoices
Maximum number of attachments:
There is a maximum of 5 attachments that has the field “IncludeOnSend” as true.
The next attachment that is attached will get the value “false” on “IncludeOnSend”.
The maximum space for attachments is 15 Mb and the maximum size of a file is 5 Mb.
Fetching a file from archive:
When you have received the Id from the connection you use it with Archive to fetch it.
Example: GET – https://api.fortnox.se/3/archive?fileid={fileId from fileattachments}
List number of attachments
Note: Only JSON payload is supported and you should use /api/ instead of /3/.
The Entity Type is O = Orders, OF = Offers, F = Invoices
The Entity Id is the DocumentNumber that was returned when the entity was created or retrieved from the list of invoices, orders and offers.
Note: Entities without connections will not be listed.
Description
Retrieves a list showing how many attachments the entities have
URL structure
Method
GET
Version
API
Examples
Request
curl -X "GET" "https://api.fortnox.se/api/fileattachments/attachments-v1/numberofattachments?entitytype=F&entityids=195,194,189,188" \ -H "Access-Token: 61cf63ae-4ab9-4a95-9db5-753781c4f41f" \ -H "Client-Secret: 3Er4kHXZTJ" \ -H "Content-Type: application/json" \ -H "Accept: application/json"
Response
[ { "entityId": 189, "numberOfAttachments": 1 }, { "entityId": 195, "numberOfAttachments": 4 } ]
Get attached files on an entity
Retrieves the details of the attachments on an entity. You need to supply the unique entity id and entity type.
The Entity Id is the DocumentNumber that was returned when the entity was created or retrieved from the list of invoices, orders and offers.
The Entity Type is O = Orders, OF = Offers, F = Invoices
Description
Retrieves a list of attachments connected to an entity
Method
GET
Examples
Request
curl -X "GET" "https://api.fortnox.se/api/fileattachments/attachments-v1/?entityid=195&entitytype=F" \ -H "Access-Token: 61cf63ae-4ab9-4a95-9db5-753781c4f41f" \ -H "Client-Secret: 3Er4kHXZTJ" \ -H "Content-Type: application/json" \ -H "Accept: application/json"
Response
[ { "id": "21487397-9c08-4310-8b07-2b54e9d36399", "entityId": 195, "entityType": "F", "fileId": "643d6cd5-02b4-4830-a6a5-4d8be4413ab3", "includeOnSend": false }, { "id": "e777753c-3888-42f4-9e2a-3dcb3acb7ecc", "entityId": 195, "entityType": "F", "fileId": "884f4148-6c9b-4b7f-9d14-d3cefcb6cb03", "includeOnSend": true } ]
Attach files to one or more entities
The Entity Id is the DocumentNumber that was returned when the entity was created or retrieved from the list of invoices, orders and offers.
The Entity Type is O = Orders, OF = Offers, F = Invoices
Examples
Request (Single Attachment)
curl -X "POST" "https://api.fortnox.se/api/fileattachments/attachments-v1/" \ -H "Access-Token: 61cf63ae-4ab9-4a95-9db5-753781c4f41f" \ -H "Client-Secret: 3Er4kHXZTJ" \ -H "Content-Type: application/json" \ -H "Accept: application/json" \
[ { "fileId":"4744ee4f-056a-4259-a8db-2df1fb5a89dd", "entityType":"F", "entityId":172, "includeOnSend":true } ]
Response
[ { "id": "523b7a6f-123d-483e-aca0-c12c0e54fe97", "entityId": 172, "entityType": "F", "fileId": "4744ee4f-056a-4259-a8db-2df1fb5a89dd", "includeOnSend": true } ]
Request (Multiple Attachments)
curl -X "POST" "https://api.fortnox.se/api/fileattachments/attachments-v1/" \ -H "Access-Token: 61cf63ae-4ab9-4a95-9db5-753781c4f41f" \ -H "Client-Secret: 3Er4kHXZTJ" \ -H "Content-Type: application/json" \ -H "Accept: application/json" \
[ { "fileId":"4744ee4f-056a-4259-a8db-2df1fb5a89dd", "entityType":"F", "entityId":172, "includeOnSend":true }, { "fileId":"2982997e-148c-4b31-86de-ccc816a4845c", "entityType":"F", "entityId":172, "includeOnSend":false } ]
Response
[ { "id": "523b7a6f-123d-483e-aca0-c12c0e54fe97", "entityId": 172, "entityType": "F", "fileId": "4744ee4f-056a-4259-a8db-2df1fb5a89dd", "includeOnSend": true }, { "id":"8d53a67a-716a-4bda-b01a-181632aea14c", "entityId":172, "entityType":"F", "fileId":"2982997e-148c-4b31-86de-ccc816a4845c", "includeOnSend":false } ]
Update a file connection
The updated file connection will be returned if everything succeeded, if there was any problems an error will be returned.
You need to specify the attachment id of the attachment that you want to update.
URL
https://api.fortnox.se/api/fileattachments/attachments-v1/<Id>
Method
PUT
Examples
Request
curl -X "PUT" "https://api.fortnox.se/api/fileattachments/attachments-v1/a0d847a4-7482-413a-90fc-70f4614f8192" \ -H "Access-Token: 61cf63ae-4ab9-4a95-9db5-753781c4f41f" \ -H "Client-Secret: 3Er4kHXZTJ" \ -H "Content-Type: application/json" \ -H "Accept: application/json" \ { "includeOnSend": true }
Response
{ "entityId": 196, "entityType": "F", "fileId": "25f38c0d-8414-4109-ac07-bd5211f5de61", "id": "a0d847a4-7482-413a-90fc-70f4614f8192", "includeOnSend": true }
Delete a file connection
You need to specify the attachment id of the attachment that you want to delete.
Note: This removes the connection but does not remove the file from the archive.
Examples
URL
https://api.fortnox.se/api/fileattachments/attachments-v1/<Id>
Method
DELETE
Request
curl -X "DELETE" "https://api.fortnox.se/api/fileattachments/attachments-v1/a0d847a4-7482-413a-90fc-70f4614f8192" \ -H "Access-Token: 61cf63ae-4ab9-4a95-9db5-753781c4f41f" \ -H "Client-Secret: 3Er4kHXZTJ" \ -H "Content-Type: application/json" \ -H "Accept: application/json" \
Response
204 No content
Properties
Property | Description |
entityId | long ID of the document. Can be used as “entityids” to fetch attachments from multiple entities |
numberOfAttachments | long, read-only Number of attachments on the document (also the ones set as not included for send) |
entityType | long Document type (“F”, “O” or “OF”) O = Orders OF = Offers F = Invoices |
fileId | UUID ID of the file. Use ArchiveFileId from Inbox/Archive endpoint in this field. |
includeOnSend | boolean Flag if the attachment should be included on send or only visible in Fortnox |
id | UUID ID of the connection. Used against Archive to fetch the file. |
Exceptions
Http Code | Code | Description |
404 | document_not_found | The document with the given ID could not be found |
404 | attachment_not_found | The attachment with the given ID could not be found |
404 | file_not_found | The file with the given ID could not be found |
400 | could_not_retrieve_document | The request to find the file failed. Could be because the document resource is unavailable or internal server error occurred. |
400 | file_too_big | An attachment can be no more the 5 MB |
400 | wrong_file_location | Can only attach files located in a folder that matches the document type (invoice, order, offer) |
400 | mixed_documents | Cannot add attachments on different documents in the same request |
400 | wrong_file_type | Only PDF file type is allowed |
400 | attachment_files_max_count_exceeded | Max 5 attachments can be included for send on a document |
400 | attachment_files_max_size_exceeded | Max 15 MB total can be included for send on a document |
400 | attachment_files_max_pages_exceeded | Max 25 pages total can be included for send on a document |
400 | field_not_writable | Payload contains field that is not writeable in PUT request. Can only contain id (optinal), includeOnSend (mandatory). |
400 | mismatch_attachment_id | Id in path for update request does not match the id in payload. |
400 | missing_mandatory_field | Missing includeOnSend in PUT request. |
400 | no_attachment_provided | No attachment was provided in the request |