> ## Documentation Index
> Fetch the complete documentation index at: https://developers.pleo.io/llms.txt
> Use this file to discover all available pages before exploring further.

# 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](/docs/current/platform/exports/attachments)

## Implementation

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

* [How to Transfer Attachments](/docs/current/how-tos/accounting-integrations/how-to-transfer-attachments-for-as-erp-processing)

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

```mermaid theme={null}
%%{init: {"themeVariables": {"fontSize": "12px"}}}%%
flowchart TD
    A[Fetch Export Items] --> B[Validate data]
    B --> C[Resolve bookkeeping method]
    C --> D[Handle attachments #40;this step#41;]
    D --> E[Create accounting entries]

   %% Styling for readability
   style A white-space:normal
   style B white-space:normal
   style C white-space:normal
   style D white-space:normal
```

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

| Scenario                               | Expected Behaviour          |
| -------------------------------------- | --------------------------- |
| No attachments                         | Continue export normally    |
| Attachment download fails              | Retry and log error         |
| Unsupported file type in AS            | Convert or store externally |
| Multiple attachments but AS allows one | Merge files                 |

## Upstream Dependencies

* Export Job has been started (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](/docs/current/integration-design/exports/integration-design-exports-accounting-periods)

***

## Related Reading

* [How to Transfer Attachments](/docs/current/how-tos/accounting-integrations/how-to-transfer-attachments-for-as-erp-processing)
* [Export Integration Workflow Guide](/docs/current/guides/export-integration-workflow-guide)
* [AS/ERP Processing Workflow Guide](/docs/current/guides/accounting-system-processing-workflow-guide)

***