This service is available in v3 only.
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.
Endpoint
GET /api/v3/transactions/{uuid}/extracted-documents
- Base URL examples:
https://public-api.mx.clara.comhttps://public-api.br.clara.comhttps://public-api.co.clara.com
Path Parameter
| Name | Type | Required | Description |
|---|
| uuid | string | ✅ Yes | UUID of the transaction |
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 |
Response
Returns a paginated list of extracted documents associated with the transaction. Each document includes metadata and content such as:
Example Document Object
{
"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"
}
}
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 |
Successful Response
| Status | Meaning |
|---|
| 200 | OK - List of extracted documents returned |
Error Responses
| Status | Meaning |
|---|
| 400 | Bad Request |
| 401 | Unauthorized |
| 403 | Forbidden |
Example cURL Request
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}
{uuid}, {your_access_token}, {client_cert_path}, and {client_key_path} with actual values.
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
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 |
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 | |
