Extracted Documents API

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.com
- https://public-api.br.clara.com
- https://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}

Replace {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

`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

​Authentication Requirements

​Endpoint

​Path Parameter

​Query Parameters (Optional)

​Response

​Example Document Object

​Validation Status Details

​Successful Response

​Error Responses

​Example cURL Request

​Summary

​Endpoint Reference

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