📄 Extracted Documents: How to Use It

This guide outlines the use of the GET /api/v3/transactions/{uuid}/extracted-documents endpoint to retrieve extracted documents related to a specific transaction in the Clara 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

JSON

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

Bash

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.