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

# Documents

> Retrieve documents (receipts, invoices) associated with transactions.

<Note>This service is available in **v3** only.</Note>

## When a Transaction Has Attachments

If a transaction has attachments:

* The `hasAttachments` field is set to `true`
* You'll receive a\*\* link to download them\*\*
* URLs are valid for **12 hours**

Format: `.../v3/transactions/{uuid}/documents`

<br />

## Endpoint Format

`GET /v3/transactions/{uuid}/documents`

Use this endpoint to retrieve the download links for all attachments related to a specific transaction.

<br />

## Example: Getting Attachments for a Transaction

In the following example, we will get the URLs for the transaction with the UUID "47f8ed9e-4d7b-450b-ad6a-f1d83e3ce4e1" in Mexico.

### cURL Request

```curl cURL theme={null}
curl -X GET
"https://public-api.mx.clara.com/api/v3/transactions/47f8ed9e-4d7b-450b-ad6a-f1d83e3ce4e1/documents" \ 
-H "Authorization: Bearer YOUR_ACCESS_TOKEN"	
```

### Sample JSON Response

```curl JSON theme={null}
{
  "transactionUuid": "47f8ed9e-4d7b-450b-ad6a-f1d83e3ce4e1",
  "attachments": [
    {
      "uuid": "18589896-d30e-4cca-a4e6-716ba323b937",
      "fileName": "receipt.jpg",
      "updateAt": "2024-12-09T01:35:26.426484Z",
      "format": "jpeg",
      "download": {
        "urlExpiration": "2024-12-14T07:40:15.144358891Z",
        "url": "https://company-9fefb4f5-491d-4028-8c4d-f7b20ff98e29.s3.amazonaws.com/user_docs/1dbf684e-4cdd-467d-b240-3e8e45d63887/51/5465258?response-content-disposition=attachment%3B%20filename%3D%22oneOoneHuixquilucan_241208193512.jpg%22&response-content-type=jpeg&X-Amz-Security-Token=FwoGZXIvYXdzEDUaDJAr429nJB6KRbni%2FiKwAbLEsGgPIsSE8kV0DdR905%2FXd4wYq9zQ2P99MHz06fykkTuaylb7xbpkANXyqQpTJw2M23Q%2FabFuakuazkVDPCQ%2BHwDM3LmJ%2BqWhng87m1q6p6JlacCyMqlQbVtpwYFcts1hMjSXASha79Cs%2FLm9onR2txbq6rTn5%2BW0vtKFk%2FyD7x%2FhGhfmMuZyUgD37dp7FSzUo0Z4ZjLhHjrc6tt%2F2f2C15sN1ps9tCtoyyCiKJ2b8roGMi0W6DxWRVjX7xCGyIT07lfVCMnw9v1MsbpscZ5%2BORVmaTq9CfU3kezypy%2B0M%3D&X-Amz-Algorithm=AWS4-HMAC-SHA256&X-Amz-Date=20241213T194014Z&X-Amz-SignedHeaders=host&X-Amz-Expires=43199&X-Amz-Credential=ASIASUFA8KD3C1GJLWK%2F20241213%2Fus-east-1%2Fs3%2Faws4_request&X-Amz-Signature=3038ebf880b3cd0a0e8b24a0440f047e52ec1f4c1b88f210c637928747a688cc"
      }
    }
  ]
}

```

⚠️ The download URL is time-sensitive and will expire 12 hours after it's generated. Make sure to use it within that window.

***

## Endpoint Reference

### `GET /api/v3/transactions/{uuid}/documents`

Get a transaction by UUID

**Parameters:**

| Parameter | In   | Type   | Required | Description      |
| --------- | ---- | ------ | -------- | ---------------- |
| `uuid`    | path | string | ✅        | Transaction UUID |

**Response Schema (`AttachmentDocuments`):**

| Field             | Type                            | Example                                |
| ----------------- | ------------------------------- | -------------------------------------- |
| `transactionUuid` | string                          | `5ea3a09a-5c1c-9303-b833-c93780c21dbc` |
| `attachments`     | array of AttachmentTransactions |                                        |

### `GET /api/v3/transactions/{uuid}/extracted-documents`

Find extracted documents for a Transaction by uuid

**Parameters:**

| Parameter          | In    | Type                                                          | Required | Description                              |
| ------------------ | ----- | ------------------------------------------------------------- | -------- | ---------------------------------------- |
| `uuid`             | path  | string                                                        | ✅        | Transaction UUID                         |
| `page`             | query | integer                                                       |          | Zero-based page index (0..N)             |
| `size`             | query | integer                                                       |          | The size of the page to be returned      |
| `uuid`             | query | string                                                        |          | Unique identifier of the document        |
| `type`             | query | enum: `MEXICAN_FISCAL_INVOICE`/`INVOICE`/`RECEIPT`/`OTHER`    |          | Type of the extracted document           |
| `validationStatus` | query | enum: `VALIDATED_BY_CLARA`/`VALIDATED_BY_USER`/`NOT_VERIFIED` |          | Status of the validation of the document |

**Response Schema (`ExtractedDocumentPage`):**

| Field              | Type                       | Example |
| ------------------ | -------------------------- | ------- |
| `totalPages`       | integer (int32)            |         |
| `totalElements`    | integer (int64)            |         |
| `first`            | boolean                    |         |
| `last`             | boolean                    |         |
| `size`             | integer (int32)            |         |
| `content`          | array of ExtractedDocument |         |
| `number`           | integer (int32)            |         |
| `sort`             | object (SortObject)        |         |
| `pageable`         | object (PageableObject)    |         |
| `numberOfElements` | integer (int32)            |         |
| `empty`            | boolean                    |         |

**`sort` object (SortObject):**

| Field      | Type    | Example |
| ---------- | ------- | ------- |
| `empty`    | boolean |         |
| `sorted`   | boolean |         |
| `unsorted` | boolean |         |

**`pageable` object (PageableObject):**

| Field        | Type                | Example |
| ------------ | ------------------- | ------- |
| `offset`     | integer (int64)     |         |
| `sort`       | object (SortObject) |         |
| `paged`      | boolean             |         |
| `pageNumber` | integer (int32)     |         |
| `pageSize`   | integer (int32)     |         |
| `unpaged`    | boolean             |         |