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

# Extracted Documents

> Retrieve structured fiscal documents (XML invoices, receipts) tied to transactions.

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

## Authentication Requirements

To access this endpoint, ensure the following:

* Use **mutual TLS (MTLS)** for secure two-way certificate validation.
* Obtain an **OAuth2 access token** via the `/oauth/token` endpoint.
* Include the **Bearer token** in the `Authorization` header of your request.

<br />

## Endpoint

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

* **Base URL examples**:
  * `https://public-api.mx.clara.com`
  * `https://public-api.br.clara.com`
  * `https://public-api.co.clara.com`
  <br />

## Path Parameter

| Name | Type   | Required | Description             |
| ---- | ------ | -------- | ----------------------- |
| uuid | string | ✅ Yes    | UUID of the transaction |

<br />

## Query Parameters (Optional)

| Name             | Type    | Description                                                                           |
| ---------------- | ------- | ------------------------------------------------------------------------------------- |
| page             | integer | Page index, zero-based. Default: 0                                                    |
| size             | integer | Items per page. Default: 20                                                           |
| uuid             | uuid    | Filter by extracted document UUID                                                     |
| type             | enum    | Filter by document type: MEXICAN\_FISCAL\_INVOICE, INVOICE, RECEIPT, OTHER            |
| validationStatus | enum    | Filter by validation status: VALIDATED\_BY\_CLARA, VALIDATED\_BY\_USER, NOT\_VERIFIED |

<br />

## Response

Returns a paginated list of extracted documents associated with the transaction. Each document includes metadata and content such as:

### Example Document Object

```json theme={null}
{
  "uuid": "123e4567-e89b-12d3-a456-426614174000",
  "type": "INVOICE",
  "userUuid": "cd22be0b-c074-41d3-8645-77e1507c8562",
  "data": {
    "folioFiscalUuid": "123e4567-e89b-12d3-a456-426614174000",
    "invoiceId": "INV-2023-001",
    "receiptDate": "2023-10-15",
    "issueDate": "2023-10-15",
    "billingDate": "2023-10-31",
    "country": "MX",
    "issuer": {
      "legalName": "ACME Corporation",
      "taxIdentifier": "ABC123456XYZ"
    },
    "items": [
      {
        "name": "Office Chair",
        "unitPrice": 149.99,
        "quantity": 2,
        "total": 299.98
      }
    ],
    "itemsDescription": "Office supplies",
    "amount": {
      "currency": "USD",
      "subTotal": 100.0,
      "taxesAmount": 16.0,
      "tipAmount": 10.0,
      "total": 126.0,
      "taxPercentage": 16.0,
      "tipPercentage": 10.0
    }
  },
  "fileValidation": {
    "status": "VALIDATED_BY_CLARA",
    "date": "2023-10-15T14:30:00",
    "user": "John Doe",
    "userUuid": "123e4567-e89b-12d3-a456-426614174000"
  }
}
```

<br />

## Validation Status Details

| Status               | Description                          |
| -------------------- | ------------------------------------ |
| VALIDATED\_BY\_CLARA | Automatically validated successfully |
| VALIDATED\_BY\_USER  | Validated manually by a user         |
| NOT\_VERIFIED        | Document could not be validated      |

<br />

## Successful Response

| Status | Meaning                                   |
| ------ | ----------------------------------------- |
| 200    | OK - List of extracted documents returned |

<br />

## Error Responses

| Status | Meaning      |
| ------ | ------------ |
| 400    | Bad Request  |
| 401    | Unauthorized |
| 403    | Forbidden    |

<br />

## Example cURL Request

```bash theme={null}
curl --location --request GET 'https://public-api.mx.clara.com/api/v3/transactions/{uuid}/extracted-documents' \
--header 'Authorization: Bearer {your_access_token}' \
--cert {client_cert_path} \
--key {client_key_path}
```

Replace `{uuid}`, `{your_access_token}`, `{client_cert_path}`, and `{client_key_path}` with actual values.

<br />

## Summary

This endpoint enables retrieval of structured, validated financial documents (invoices, receipts, etc.) tied to a transaction. It supports robust filtering and pagination, and enforces secure access through MTLS and OAuth2.

***

## Endpoint Reference

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