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).

Document Reference Attributes

A document reference records that a document refers to another document: a credit note to the invoice it credits, a debt collection notice to the invoices it collects, a receipt to the invoice it belongs to. The reference is first stored as printed on the document (referenced_document_*). Saving a document resolves its references both ways — each unresolved reference is looked up by type and number within the same client account (narrowed to the document’s business partner, or for a debt collection to its business partner or collector), and references on other documents that name the document being saved are resolved against it. A resolved reference gets relation_type and relation_id pointing at the referenced document. Saving an ARCRN credit note also closes the invoices its resolved references point at.

References are read with with=document_references and written as a nested document_references array on create and update. The API neither returns nor accepts an id for a reference, so the array you send replaces the document’s references and entries are matched to the existing ones by position.

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