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