🧾 Invoices API: How to Use It

🔍 What is the Invoices API?

The Invoices API v2 allows you to retrieve invoice records associated with transactions made through Clara. These invoices may be manually uploaded by users or automatically extracted from provider documents such as CFDI XML files (in Mexico).

This API is useful for:

• Reviewing fiscal documents linked to card transactions
• Building tax compliance or expense reconciliation tools
• Filtering invoices by multiple criteria such as number, transaction, date, or document ID

📌 Available Endpoints

Operation	Endpoint	Method
Get all invoices with optional filters	/v2/invoices	GET

1️⃣ Find all invoices with optional filters

Use this endpoint to fetch a paginated list of invoices, optionally filtered by:

• invoiceNumber
• transactionUuid
• invoiceId
• documentDateRangeStart
• documentDateRangeEnd

📌 Note: The date range filter is only applied if both documentDateRangeStart and documentDateRangeEnd are present

🔗 Endpoint

GET /v2/invoices

🧩 Available Query Parameters

Parameter	Type	Required	Description
invoiceNumber	string	optional	Filters by invoice number
transactionUuid	string	optional	Filters by associated transaction UUID
invoiceId	string	optional	Filters by internal invoice ID
documentDateRangeStart	string	optional	Start date in ISO format (requires documentDateRangeEnd)
documentDateRangeEnd	string	optional	End date in ISO format (requires documentDateRangeStart)

📤 cURL Request

cURL

curl -X GET \
"https://public-api.mx.clara.com/api/v2/invoices?transactionUuid=txn-123&documentDateRangeStart=2024-06-01&documentDateRangeEnd=2024-06-30" \
-H "Authorization: Bearer YOUR_ACCESS_TOKEN"

📥 Sample JSON Response

JSON

{
  "content": [
    {
      "uuid": "inv-001",
      "invoiceNumber": "A123",
      "transactionUuid": "txn-123",
      "amount": 400.00,
      "currency": "MXN",
      "documentDate": "2024-06-15",
      "xmlStatus": "Valid",
      "issuer": {
        "rfc": "ABC123456T89",
        "businessName": "Proveedor S.A. de C.V."
      }
    }
  ],
  "page": 0,
  "size": 20,
  "totalElements": 1,
  "totalPages": 1
}

💡 Tip: You can combine filters to narrow down invoices by vendor, date, or linked transactions.

⚠️ Note: This endpoint uses pagination, so be sure to handle page and size parameters or iterate through results if needed.