Snapbooks logo Snapbooks Developer

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