> ## Documentation Index > Fetch the complete documentation index at: https://developers.clara.team/llms.txt > Use this file to discover all available pages before exploring further. # Invoices > Access CFDI fiscal invoice data linked to transactions (Mexico only). Recommended for all new integrations. ## When a Transaction Has an Invoice If a transaction has invoice: * The `hasInvoice` field is set to `true` * You'll receive a **link to download them** * URLs are valid for **12 hours**
## Endpoint Format `GET /v3/transactions/{uuid}/invoices` Use this endpoint to retrieve XML invoice details and metadata associated with a specific transaction.
## Example: Getting Invoices for a Transaction In the following example, we will get the invoice information for the transaction with the UUID "47f8ed9e-4d7b-450b-ad6a-f1d83e3ce4e1" in Mexico. ### cURL Request ```curl cURL theme={null} curl -X GET "https://public-api.mx.clara.com/api/v3/transactions/47f8ed9e-4d7b-450b-ad6a-f1d83e3ce4e1/invoices" \ -H "Authorization: Bearer YOUR_ACCESS_TOKEN" ``` ### Sample JSON Response ```curl JSON theme={null} { "transactionUuid": "47f8ed9e-4d7b-450b-ad6a-f1d83e3ce4e1", "invoices": [ { "invoiceId": "54cd6b23-5146-437f-b133-879c432e6776", "invoiceNumber": null, "taxRegime": "621", "issuer": { "rfc": "CLARA123XML", "businessName": "CLARA" }, "taxReceipts": { "cfdi": "G03", "paymentMethod": "Q4" }, "tax": { "retained": { "isr": 0.75, "iva": null, "ieps": null }, "transferred": { "iva": 0.0, "ieps": 0.0 } }, "amount": { "total": 400.00, "subTotal": 300.00, "currency": "MXN" }, "documentDate": "2024-10-01", "xmlStatus": "Vigente", "xmlCode": "S – Comprobante obtenido satisfactoriamente." } ] } ``` ⚠️ The download URL is temporary and will expire 12 hours after generation. Ensure you download and store the file before it expires. ℹ️ Note: The example provided contains mock data and does not reflect real tax calculations or financial details. *** ## Endpoint Reference ### `GET /api/v3/transactions/{uuid}/invoices` Get a transaction by UUID **Parameters:** | Parameter | In | Type | Required | Description | | --------- | ---- | ------ | -------- | ---------------- | | `uuid` | path | string | ✅ | Transaction UUID | **Response Schema (`TransactionInvoiceResponse`):** | Field | Type | Example | | ----------------- | ------------------------ | -------------------------------------- | | `transactionUuid` | string | `4ea5a94a-2c3c-4601-b623-c30260c21dbc` | | `invoices` | array of InvoiceResponse | | ### `GET /api/v3/invoices` Find all Invoices with optional filters **Parameters:** | Parameter | In | Type | Required | Description | | ------------------------ | ----- | ------- | -------- | ------------------------------------------------------------------------------------------ | | `page` | query | integer | | Zero-based page index (0..N) | | `size` | query | integer | | The size of the page to be returned | | `invoiceNumber` | query | string | | Invoice number to filter invoices | | `issuerRfc` | query | string | | RFC Issuer number to filter invoices | | `transactionUuid` | query | string | | Transaction UUID to filter invoices | | `invoiceId` | query | string | | Invoice ID to filter invoices | | `documentDateRangeStart` | query | string | | Start date for invoice date range filter (must be used together with documentDateRangeEnd) | | `documentDateRangeEnd` | query | string | | End date for invoice date range filter (must be used together with documentDateRangeStart) | **Response Schema (`InvoicePageV3`):** | Field | Type | Example | | ------------------ | ----------------------- | ------- | | `totalPages` | integer (int32) | | | `totalElements` | integer (int64) | | | `first` | boolean | | | `last` | boolean | | | `size` | integer (int32) | | | `content` | array of InvoiceV3 | | | `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 | | ## 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 |
## 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 theme={null} 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 JSON theme={null} { "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.