Documents

Commercial 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

Method	Endpoint	Description
GET	/documents	List documents
POST	/documents	Create a document
GET	/documents/{id}	Get a specific document
PUT/PATCH	/documents/{id}	Update a document
DELETE	/documents/{id}	Delete a document
POST	/documents/preview	Generate a preview PDF of a document

Query Parameters

The GET /documents endpoint supports the following query parameters:

Parameter	Type	Required	Description
client_account_id	integer	Yes	Filter by client account ID
business_partner_id	integer	No	Filter by business partner ID
from_document_date	date	No	Filter from document date (inclusive)
to_document_date	date	No	Filter to document date (inclusive)
document_type	string	No	Filter by document type
document_status	string	No	Filter by document status
document_number	string	No	Filter by document number
payment_reference	string	No	Filter by payment reference
gross_amount	decimal	No	Filter by gross amount
payment_status	string	No	Filter by payment status
is_active	boolean	No	Filter by active status
order_by	string	No	Sort order
page	integer	No	Page number for pagination (default: 1)
per_page	integer	No	Number of items per page (default: 100)

Document Attributes

Attribute	Type	Description
id	integer	The unique identifier of the document
created_at	date	When the document was created
created_by_id	integer	The ID of the user who created the document
updated_at	date	When the document was last updated
updated_by_id	integer	The ID of the user who last updated the document
client_account_id	integer	The ID of the client account
business_partner_id	integer	The ID of the business partner
payor_id	integer	The ID of the payor
collector_id	integer	The ID of the collector
document_date	date	The date of the document
due_date	date	The payment due date
period_start	date	Start date of the period covered
period_end	date	End date of the period covered
period_description	string	Description of the period
document_type	string	Type of document
document_status	string	Status of the document
document_number	string	Document number
document_uuid	string	Unique identifier for the document
document_description	string	Description of the document
buyer_reference	string	Buyer’s reference number
order_reference	string	Order reference number
note	string	Additional notes
collection_case_number	string	Collection case reference
collection_severity	string	Severity of collection
payment_status	string	Status of payment (read-only)
payment_means	string	Method of payment
payment_ref	string	Payment reference
payment_card_number	string	Card number for card payments
gross_amount	decimal	Total amount including tax
net_amount	decimal	Amount before tax
open_amount	decimal	Remaining unpaid amount (read-only)
pending_payment_amount	decimal	Amount in pending payment requests (read-only)
late_fee_amount	decimal	Late payment fees
interest_amount	decimal	Interest charges
bank_account_id	integer	ID of the associated bank account
voucher_id	integer	ID of the associated file/voucher
currency_id	integer	ID of the currency
currency_code	string	Currency code
exchange_rate	decimal	Exchange rate used
is_draft	boolean	Whether this is a draft document
is_imported	boolean	Whether this was imported
is_archived	boolean	Whether this is archived
archive_category	string	Category for archived documents
send_document	boolean	Whether to send the document

Document Line Attributes

Attribute	Type	Description
id	integer	The unique identifier of the line
document_id	integer	The ID of the parent document
line_id	integer	Line number within the document
item_id	integer	The ID of the item
item_no	string	Item number/code
item_name	string	Name of the item
description	string	Description of the line
price	decimal	Unit price
currency_code	string	Currency code
quantity	decimal	Quantity
unit_id	integer	ID of the unit of measure
tax_code_id	integer	ID of the tax code
tax_rate	decimal	Tax rate percentage
tax_amount_lc	decimal	Tax amount in local currency
tax_amount_fc	decimal	Tax amount in foreign currency
total_lc	decimal	Total amount in local currency
total_fc	decimal	Total amount in foreign currency
item_collection_entry_id	integer	ID of collection entry

Payment Line Attributes

Attribute	Type	Description
id	integer	The unique identifier of the payment line
document_id	integer	The ID of the parent document
line_type	string	Type of payment line
requested_execution_date	date	Requested date for execution
debtor_business_partner_id	integer	ID of the debtor
debtor_bank_account_id	integer	ID of debtor’s bank account
creditor_business_partner_id	integer	ID of the creditor
creditor_bank_account_id	integer	ID of creditor’s bank account
amount	decimal	Payment amount
currency_code	string	Currency code
creditor_reference	string	Creditor’s reference

Relationships

Relationship	Type	Description
business_partner	BusinessPartner	The associated business partner
payor	BusinessPartner	The payor business partner
collector	BusinessPartner	The collector business partner
bank_account	BankAccount	The associated bank account
files	UploadedFile	Associated files and attachments
structured_data	object	Additional structured data
item_lines	[DocumentLine]	The item lines in the document
payment_lines	[PaymentLine]	The payment lines in the document
document_references	[DocumentReference]	References to other documents
payment_requests	PaymentRequest	Associated payment requests

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

{
    "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": "INVOICE",
    "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",
    "is_draft": false,
    "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,
            "line_id": 1,
            "item_name": "Consulting Services",
            "description": "Professional consulting May 2023",
            "price": "1000.00",
            "quantity": "1.00",
            "tax_rate": "20.00",
            "tax_amount": "200.00",
            "total": "1200.00"
        }
    ],
    "payment_lines": [
        {
            "id": 1,
            "line_type": "BANK_TRANSFER",
            "requested_execution_date": "2023-06-09",
            "amount": "1200.00",
            "currency_code": "EUR"
        }
    ]
}

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_relations 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