Documents

Commercial documents represent various types of business documents such as invoices, credit notes, and other financial documents. They can include both item lines for goods/services and payment lines for payment instructions.

Endpoints

Query Parameters

The GET /documents endpoint supports the following query parameters:

Document Attributes

Document Line Attributes

Payment Line Attributes

Relationships

Payment Line Types

Reconciliation Line Attributes

Reconciliation Category

The category is written from the document’s point of view: what the line is about, as the issuer presents it. It fixes the ledger sign and, per country, the accounts a sign-off may use; the document supplies the dimension (its business partner for businesspartner, its bank account for bankacc) where a target account requires one. The sign reads the printed amount — positive when the item increases the issuer’s running balance for the client — into ledger terms (debit positive). If extraction got a printed sign wrong, correct the line’s amount while it is OPEN; the category rule never bends.

Lines of an AP_STATEMENT are always TRADE_PAYABLE. Annual report extraction classifies each line, leaving null where nothing applies (revenue, payroll cost and other financial statement lines). A line without a category cannot be signed off. An invalid value is refused with 400 Invalid reconciliation category.

Reconciliation Line Status

Reconciliation lines are attested through External Reconciliations: a record compares the line’s printed amount with journal entry lines (for TRANSACTIONAL lines) or an account balance (for BALANCE lines). The status is recomputed on every read by re-running that comparison against the current ledger.

A line referenced by a live external reconciliation cannot have its amount, currency_code, transaction_date, reconciliation_type or category changed, and neither the line nor its document can be deleted, until the reconciliation is retired (400 Reconciliation line is reconciled).

File Relationships

Documents can have multiple associated files:

• A primary voucher file (through voucher_id)
• Additional attached files (through the files relationship)
• Files can be accessed through their download URLs with appropriate permissions

Example Response

Example shown with with=files,item_lines,payment_lines — these relations are omitted unless requested.

{
    "id": 1,
    "created_at": "2023-05-10T12:00:00Z",
    "client_account_id": 1,
    "business_partner_id": 2,
    "document_date": "2023-05-10",
    "due_date": "2023-06-09",
    "document_type": "ARINV",
    "document_status": "OPEN",
    "document_number": "INV-2023-001",
    "document_description": "Monthly services",
    "gross_amount": "1200.00",
    "net_amount": "1000.00",
    "currency_code": "EUR",
    "exchange_rate": "1.0000",
    "payment_status": "NONE",
    "stated_payment_status": null,
    "is_draft": false,
    "is_active": true,
    "is_payable": true,
    "is_unpaid": true,
    "is_available_for_payment": true,
    "is_being_paid": false,
    "is_reconcilable": true,
    "is_unreconciled": true,
    "files": [
        {
            "id": 1,
            "file_name": "invoice.pdf",
            "download_url": "https://example.com/files/invoice.pdf",
            "thumbnail_url": "https://example.com/thumbnails/invoice.jpg"
        }
    ],
    "item_lines": [
        {
            "id": 1,
            "document_id": 1,
            "line_id": 1,
            "item_id": null,
            "item_no": null,
            "item_name": "Consulting Services",
            "description": "Professional consulting May 2023",
            "price": "1000.000000",
            "currency_code": "EUR",
            "quantity": "1.000000",
            "unit_id": 5,
            "tax_code_id": 3,
            "tax_rate": "25.000000",
            "tax_amount_lc": "250.000000",
            "tax_amount_fc": "250.000000",
            "total_lc": "1250.000000",
            "total_fc": "1250.000000",
            "item_collection_entry_id": null
        }
    ],
    "payment_lines": [
        {
            "id": 1,
            "document_id": 1,
            "line_type": "SUPPLIER_PAYMENT",
            "requested_execution_date": "2023-06-09",
            "debtor_business_partner_id": null,
            "debtor_bank_account_id": 24,
            "creditor_business_partner_id": 2,
            "creditor_bank_account_id": null,
            "amount": "1250.000000",
            "currency_code": "EUR",
            "creditor_reference": "12345678901"
        }
    ]
}

Notes

• The client_account_id must be one of the eligible client accounts for the authenticated user
• When creating or updating a document, the created_by_id/updated_by_id is automatically set to the authenticated user’s ID
• Documents marked with send_document will be automatically sent when created or updated from draft status
• The preview endpoint generates a PDF preview without saving the document
• All amounts are returned as string representations of decimal numbers
• Dates are returned in ISO 8601 format
• Relationships can be included by specifying them in the with query parameter
• Draft documents can be modified or deleted; finalized documents have restrictions
• Files associated with documents can be accessed through their download URLs which expire after one hour