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

Relaterte artikler