> ## Documentation Index > Fetch the complete documentation index at: https://api-doc.fidly.be/llms.txt > Use this file to discover all available pages before exploring further. # Add Document Attachments > Attach one or more files to a document the company issued (droit `document:u`). **Strictly additive.** The files already attached are never touched, and there is no way to remove one — that is deliberate, not an oversight. **All or nothing.** Every file is checked before a single byte reaches S3: one refused extension and the whole call fails, leaving the document exactly as it was. The stored media type is derived from the extension and never from the multipart header, which the caller controls. A file whose name is already attached to this document is refused (`409 duplicate_attachment`): storing it would overwrite the first, which nothing could then bring back. A document the company *received* carries no attachment (`409`). Attaching is not a correction: it changes nothing of what the document says, so it stays possible on a document already sent or already handed to the accounting — the same reasoning that lets a payment through. In sandbox mode the files are validated exactly as in live mode but nothing is uploaded nor stored. ## OpenAPI ````yaml /openapi.json post /documents/{document_uuid}/attachments openapi: 3.1.0 info: title: Fidly API version: 1.0.0 servers: - url: https://api.fidly.be description: Production security: [] paths: /documents/{document_uuid}/attachments: post: tags: - documents summary: Add Document Attachments description: >- Attach one or more files to a document the company issued (droit `document:u`). **Strictly additive.** The files already attached are never touched, and there is no way to remove one — that is deliberate, not an oversight. **All or nothing.** Every file is checked before a single byte reaches S3: one refused extension and the whole call fails, leaving the document exactly as it was. The stored media type is derived from the extension and never from the multipart header, which the caller controls. A file whose name is already attached to this document is refused (`409 duplicate_attachment`): storing it would overwrite the first, which nothing could then bring back. A document the company *received* carries no attachment (`409`). Attaching is not a correction: it changes nothing of what the document says, so it stays possible on a document already sent or already handed to the accounting — the same reasoning that lets a payment through. In sandbox mode the files are validated exactly as in live mode but nothing is uploaded nor stored. operationId: add_document_attachments_documents__document_uuid__attachments_post parameters: - name: document_uuid in: path required: true schema: type: string title: Document Uuid requestBody: required: true content: multipart/form-data: schema: $ref: >- #/components/schemas/Body_add_document_attachments_documents__document_uuid__attachments_post responses: '201': description: Successful Response content: application/json: schema: $ref: '#/components/schemas/DocumentOut' '422': description: Validation Error content: application/json: schema: $ref: '#/components/schemas/HTTPValidationError' security: - HTTPBearer: [] components: schemas: Body_add_document_attachments_documents__document_uuid__attachments_post: properties: files: items: type: string contentMediaType: application/octet-stream type: array title: Files description: >- The files to attach. Allowed extensions: .pdf, .csv, .png, .jpg, .jpeg, .xlsx, .ods — up to 10 per call, 10 MB for the whole call. type: object required: - files title: Body_add_document_attachments_documents__document_uuid__attachments_post DocumentOut: properties: id: type: string title: Id description: Opaque unique identifier of the document. type: type: string title: Type description: >- Document type. One of: `sale_invoice`, `sale_credit_note`, `purchase_invoice`, `purchase_credit_note`, `other_document`, `unknown`. origin: type: string title: Origin description: >- Channel the document came in through. One of: `fidly` (generated in Fidly), `manual`, `peppol`, `mail`, `odoo`, `billit`, `api` (or `unknown`). relation_type: anyOf: - type: string - type: 'null' title: Relation Type description: >- Nature of `relation_id`: `company` (a registered business relation) or `contact` (an individual contact). `null` when there is no linked third party. relation_id: anyOf: - type: string - type: 'null' title: Relation Id description: >- Opaque identifier of the third party the document is linked to (resolvable via `GET /relations/{id}`). Its nature is given by `relation_type`. `null` when the document has no linked third party. journal_id: anyOf: - type: string - type: 'null' title: Journal Id description: >- Opaque identifier of the journal the document is booked in (resolvable via `GET /journals/{id}`). `null` when the document has no linked journal. delivery_location_id: anyOf: - type: string - type: 'null' title: Delivery Location Id description: >- Opaque identifier of the saved delivery address the document is delivered to (resolvable via `GET /delivery-locations/{id}`). `null` when none is set. document_number: anyOf: - type: string - type: 'null' title: Document Number description: The document's own number (e.g. invoice number). order_number: anyOf: - type: string - type: 'null' title: Order Number description: Purchase/sales order number referenced by the document. despatch_reference: anyOf: - type: string - type: 'null' title: Despatch Reference description: >- Reference of the despatch advice (delivery note) related to the document. buyer_reference: anyOf: - type: string - type: 'null' title: Buyer Reference description: >- Reference given by the buyer, to be quoted back on the document (e.g. a cost centre). issue_date: anyOf: - type: string format: date - type: 'null' title: Issue Date description: Date the document was issued (ISO `YYYY-MM-DD`). due_date: anyOf: - type: string format: date - type: 'null' title: Due Date description: Payment due date (ISO `YYYY-MM-DD`). payment_terms: anyOf: - type: string - type: 'null' title: Payment Terms description: >- Payment terms the `due_date` follows from, as `-` (e.g. `30-df`). Always `null` on a received document: only documents Fidly issues carry them. tax_point_date: anyOf: - type: string format: date - type: 'null' title: Tax Point Date description: >- Date the VAT becomes chargeable, when it differs from the issue date (ISO `YYYY-MM-DD`). delivery_date: anyOf: - type: string format: date - type: 'null' title: Delivery Date description: Date the goods/services were actually delivered (ISO `YYYY-MM-DD`). period_start: anyOf: - type: string format: date - type: 'null' title: Period Start description: First day of the period the document bills (ISO `YYYY-MM-DD`). period_end: anyOf: - type: string format: date - type: 'null' title: Period End description: Last day of the period the document bills (ISO `YYYY-MM-DD`). legal_notice: anyOf: - type: string - type: 'null' title: Legal Notice description: >- Legal mention printed at the bottom of the document (e.g. a VAT exemption wording). Always `null` on received documents. payment_remittance: anyOf: - type: string - type: 'null' title: Payment Remittance description: >- Communication to quote when paying the document. `null` when the document carries none. is_remittance_structured: type: boolean title: Is Remittance Structured description: >- `true` when `payment_remittance` is a structured communication (a bank-checked reference such as a Belgian OGM/VCS) rather than free text. Always `true` for documents issued by Fidly. create_date: anyOf: - type: string format: date-time - type: 'null' title: Create Date description: >- Timestamp the document was created in Fidly (ISO 8601). May be `null` on rare legacy rows where it was never set. currency: anyOf: - type: string - type: 'null' title: Currency description: ISO 4217 currency code of all amounts (e.g. `EUR`). tax_exclusive_amount: anyOf: - type: number - type: 'null' title: Tax Exclusive Amount description: Total amount excluding tax. tax_amount: anyOf: - type: number - type: 'null' title: Tax Amount description: Total tax (VAT) amount. total_amount: anyOf: - type: number - type: 'null' title: Total Amount description: Total amount payable, tax included. paid_amount: anyOf: - type: number - type: 'null' title: Paid Amount description: Amount already paid. remaining_amount: anyOf: - type: number - type: 'null' title: Remaining Amount description: Amount still to be paid (`total_amount` minus `paid_amount`). payment_status: type: string title: Payment Status description: 'Payment state. One of: `unpaid`, `partial`, `paid` (or `unknown`).' accounting_status: type: string title: Accounting Status description: >- Accounting workflow state. One of: `waiting`, `accepted`, `transfered`, `exported`, `export_error`, `imported`, `validated`, `hidden`, `exporting`, `posting`, `posting_error`, `deleted` (or `unknown`). pdf_available: type: boolean title: Pdf Available description: >- `true` if a PDF is stored for this document (retrievable via the file endpoint). xml_available: type: boolean title: Xml Available description: >- `true` if a structured XML version (e.g. Peppol/UBL) is stored for this document. peppol_status: anyOf: - type: string - type: 'null' title: Peppol Status description: >- Peppol send state of an issued document. One of: `not_sent`, `sending`, `sent` (delivered to the network), `accepted` (acknowledged by the recipient), `rejected` (refused by the recipient), `failed` (or `unknown`). `rejected` and `failed` can be sent again. Always `null` on a received document. mail_status: anyOf: - type: string - type: 'null' title: Mail Status description: >- E-mail send state of an issued document. One of: `not_sent`, `sent`, `failed` (or `unknown`). Always `null` on a received document. attachments: items: $ref: '#/components/schemas/AttachmentOut' type: array title: Attachments description: >- Files attached to the document, in the order they were added. Attach one with `POST /documents/{id}/attachments`; the API offers no way to remove one. A received document never carries any. allowance_charges: items: $ref: '#/components/schemas/AllowanceChargeOut' type: array title: Allowance Charges description: >- Discounts/surcharges applied to the document as a whole, after the lines and their own. `tax_exclusive_amount` is already net of them. lines: items: $ref: '#/components/schemas/LineOut' type: array title: Lines description: >- Detailed lines of the document (invoiced items/services). Empty when none are stored. additionalProperties: true type: object required: - id - type - origin - document_number - order_number - despatch_reference - buyer_reference - issue_date - due_date - tax_point_date - delivery_date - period_start - period_end - payment_remittance - is_remittance_structured - create_date - currency - tax_exclusive_amount - tax_amount - total_amount - paid_amount - remaining_amount - payment_status - accounting_status - pdf_available - xml_available title: DocumentOut description: >- A document of the company: an invoice/credit note it issued or a document it received (purchase invoice, credit note, other). The source table is hidden — the client sees a single unified document identified by an opaque `id`. Monetary amounts are decimal numbers in the document's `currency`. They may be `null` when the document could not be parsed automatically, or for `other_document` types that have no financial breakdown. Both sources are normalised to this shape by the repository adapters; the validators below map the internal codes to their public values. HTTPValidationError: properties: detail: items: $ref: '#/components/schemas/ValidationError' type: array title: Detail type: object title: HTTPValidationError AttachmentOut: properties: filename: anyOf: - type: string - type: 'null' title: Filename description: Name of the attached file. mimetype: anyOf: - type: string - type: 'null' title: Mimetype description: Media type of the attached file. type: object title: AttachmentOut description: >- A file attached to a document. Where it is stored (bucket and key) stays internal. AllowanceChargeOut: properties: code: anyOf: - type: string - type: 'null' title: Code description: Reason code for the allowance/charge. type: anyOf: - type: string - type: 'null' title: Type description: '`allowance` (discount) or `charge` (surcharge).' amount: anyOf: - type: number - type: 'null' title: Amount description: Monetary amount of the allowance/charge. reason: anyOf: - type: string - type: 'null' title: Reason description: Free-text reason. rate: anyOf: - type: number - type: 'null' title: Rate description: Percentage rate, when expressed as a percentage. type: object title: AllowanceChargeOut description: A discount (allowance) or surcharge (charge) applied to a document line. LineOut: properties: sequence: anyOf: - type: integer - type: 'null' title: Sequence description: Position of the line within the document. quantity: anyOf: - type: number - type: 'null' title: Quantity description: Quantity of the item. vat_rate: anyOf: - type: number - type: 'null' title: Vat Rate description: >- VAT rate applied to the line, in percent. Always `null` on a `not_subject` line: outside the scope of VAT there is no rate at all (Peppol BR-O-05). item_name: anyOf: - type: string - type: 'null' title: Item Name description: Name of the item/service. item_description: anyOf: - type: string - type: 'null' title: Item Description description: Longer description of the item/service. unit_price: anyOf: - type: number - type: 'null' title: Unit Price description: Price for one unit, before tax. unit_code: anyOf: - type: string - type: 'null' title: Unit Code description: Unit of measure code (e.g. `C62` for unit). vat_code: anyOf: - type: string - type: 'null' title: Vat Code description: >- VAT regime of the line: `standard`, `exempted`, `zero_rated`, `reverse_charge`, `intra_community`, `export` or `not_subject`. Legacy documents may carry the reserved `transferred_vat`, `canary_islands` or `ceuta_melilla`. subtotal: anyOf: - type: number - type: 'null' title: Subtotal description: Line amount before discounts, excluding tax. total: anyOf: - type: number - type: 'null' title: Total description: Line amount after discounts, excluding tax. tax_amount: anyOf: - type: number - type: 'null' title: Tax Amount description: Tax (VAT) amount of the line. section_name: anyOf: - type: string - type: 'null' title: Section Name description: Title of the section this line belongs to, if any. item_properties: anyOf: - additionalProperties: true type: object - type: 'null' title: Item Properties description: Free key/value item properties, kept as-is. item_identification: anyOf: - type: string - type: 'null' title: Item Identification description: Standard item identifier (e.g. GTIN). product_code: anyOf: - type: string - type: 'null' title: Product Code description: Seller's own product code. allowance_charges: items: $ref: '#/components/schemas/AllowanceChargeOut' type: array title: Allowance Charges description: Discounts/surcharges applied to this line. type: object title: LineOut description: A single line of a document (one invoiced item/service). ValidationError: properties: loc: items: anyOf: - type: string - type: integer type: array title: Location msg: type: string title: Message type: type: string title: Error Type input: title: Input ctx: type: object title: Context type: object required: - loc - msg - type title: ValidationError securitySchemes: HTTPBearer: type: http scheme: bearer ````