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

# Attachments Retrieval in Accounting Integrations

> How to retrieve PDF or image files linked to invoices and journal entries through the Unified API.

## Understanding attachments in accounting systems

Most accounting systems let users attach supporting documents (PDFs, scanned images, receipts) to their bookkeeping records — typically on **invoices** (sales / purchase entries) and on **journal entries** (G/L entries).

How those files are exposed varies a lot between connectors:

* Some providers return a **direct download URL** for each attachment.
* Others only signal that a document exists and require an **additional API call** to fetch the file content (returned as a base64-encoded string).
* A few connectors don't expose attachment information at all.

With the Unified API, you don't need to know which behaviour applies to which connector — Chift normalises everything behind a single `attachments_info` object and a single retrieval endpoint.

***

## How Chift handles attachments

Every invoice and every journal entry returned by the Accounting API includes an `attachments_info` object that tells you what to expect:

```json theme={null}
"attachments_info": {
  "status": "yes | yes_to_request | no | unknown",
  "attachments": []
}
```

### Status values

| Status           | Meaning                                                                                                                           |
| ---------------- | --------------------------------------------------------------------------------------------------------------------------------- |
| `yes`            | An attachment is directly accessible. Each entry in `attachments` contains a `filename` and a `url` you can download immediately. |
| `yes_to_request` | An attachment exists but requires a separate API call to retrieve the file content.                                               |
| `no`             | No attachment is linked to this entry.                                                                                            |
| `unknown`        | The connector does not support attachment detection for this provider.                                                            |

The recommended pattern is always the same: **inspect `attachments_info.status` first**, then either download the URL directly or call the dedicated attachments endpoint.

***

## Retrieving invoice attachments

Invoices returned by the following endpoints include the `attachments_info` object:

* [Get invoices](/api-reference/endpoints/accounting/get-invoices-by-type-salepurchase-entries)
* [Get one invoice](/api-reference/endpoints/accounting/get-one-invoice-salepurchase-entry)
* [Get invoices (multiple analytic plans)](/api-reference/endpoints/accounting/get-invoices-by-type-salepurchase-entries--multiple-analytic-plans)
* [Get one invoice (multiple analytic plans)](/api-reference/endpoints/accounting/get-one-invoice-salepurchase-entry--multiple-analytic-plans)

### 1. When `status` is `yes`

The `attachments` array contains one or more entries with a direct URL. You can download the file straight from that URL — no additional API call needed.

```json theme={null}
"attachments_info": {
  "status": "yes",
  "attachments": [
    { "filename": "invoice_2024_001.pdf", "url": "https://..." }
  ]
}
```

### 2. When `status` is `yes_to_request`

The `attachments` array may be empty — the status only signals that a file is available. To get the actual content, call the [Get attachments endpoint](/api-reference/endpoints/accounting/get-attachments) with `type=invoice`:

```http theme={null}
GET /consumers/{consumer_id}/accounting/attachments?type=invoice&document_id={invoice_id}
```

The response returns a list of objects with the file as a base64-encoded string:

```json theme={null}
[
  {
    "id": "12345",
    "base64_string": "JVBERi0xLjQK..."
  }
]
```

You can then decode `base64_string` on your end to reconstruct the original PDF or image file.

<Note>
  Connectors such as **Odoo** typically fall into the `yes_to_request` category for invoices.
</Note>

***

## Retrieving journal entry attachments

Journal entries follow the **exact same pattern** as invoices. The `attachments_info` object is available on:

* [Get journal entries](/api-reference/endpoints/accounting/get-journal-entries)
* [Get one journal entry](/api-reference/endpoints/accounting/get-one-journal-entry)
* [Get journal entries (multiple analytic plans)](/api-reference/endpoints/accounting/get-journal-entries-multiple-analytic-plans)

The only difference is the `type` query parameter you pass when `status` is `yes_to_request`. Use `type=entry`:

```http theme={null}
GET /consumers/{consumer_id}/accounting/attachments?type=entry&document_id={journal_entry_id}
```

The response shape is identical to the invoice case — a list of objects with an `id` and a `base64_string`.

***

## End-to-end flow

A typical retrieval flow looks like this, regardless of whether you're dealing with an invoice or a journal entry:

1. Fetch the document (invoice or journal entry) from the corresponding `GET` endpoint.
2. Read `attachments_info.status`.
3. Branch on the status:
   * `yes` → download each file from the `url` in `attachments`.
   * `yes_to_request` → call `GET /consumers/{consumer_id}/accounting/attachments` with the right `type` (`invoice` or `entry`) and the `document_id` of the record, then decode `base64_string`.
   * `no` → no file to retrieve.
   * `unknown` → the connector does not expose attachment metadata; skip or surface this to the end user.