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

Overview

Conventions

Guides

Resources

API Reference

MCP

VCN

Extracted Documents API

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`

​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

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`