Attachment Handling

Attachment handling defines how integrations must transfer and associate files from Pleo Export Items to entries created in the Accounting System. Platform capabilities and attachment schema are described in: Platform: Attachments

​

Implementation

See the corresponding how-to article for API usage and step-by-step instructions:

• How to Transfer Attachments

​

When Attachment Handling Occurs

Attachments must be processed:

1. After Export Items are fetched and validated
2. After bookkeeping method resolution
3. Before posting entries to the Accounting System

​

Processing Rules

​

1. Download Attachments

For each Export Item:

• Iterate through data[].files[]
• Download each attachment using files.url
• Preserve original file format and filename when possible

​

2. Associate Attachments

Attachments must be linked to:

• the Journal Entry, or
• the Accounts Payable invoice/payment

created for the same Export Item. The integration must ensure attachments remain traceable to the originating expense.

​

3. Multiple Attachments

If multiple attachments exist:

• Upload all files when the Accounting System supports multiple attachments.

If the Accounting System supports only one attachment:

• Combine files into a single document before upload.

Recommended approaches:

• PDF merge (preferred)
• ZIP archive (fallback)

​

4. Failure Handling

Attachment failures must not silently discard files. Recommended behaviour:

• Retry download on transient failure
• Log failed attachments
• Optionally allow posting without attachment only if accounting entry succeeds

​

5. Idempotency

Integrations should avoid duplicate uploads when exports are retried. Recommended strategies:

• store processed attachment IDs, or
• check existing attachments before upload.

​

Edge Cases

​

Upstream Dependencies

• Export Job has been claimed (status = in_progress)
• Fetch Export Item Data (data layer)
• Bookkeeping method resolved
• Accounts Mapping – determines which GL accounts are debited and credited
• Data Mapping – ensures amounts, dates, dimensions, identifiers, and VAT/tax information are recorded correctly

​

Downstream Dependencies

• Accounting Periods – assigns entries to the correct accounting period
• Posting Behaviour – determines whether entries are created as drafts or finalised
• Export Item status update – updates outcome of Export Item (successful or failed)
• Export Job status update – updates outcome of Export Job (completed, completed_with_errors or failed)

---

​

What Comes Next?

• Accounting Periods

---

​

Related Reading

• How to Transfer Attachments
• Export Integration Workflow Guide
• AS/ERP Processing Workflow Guide

---