๐Ÿงพ 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

OperationEndpointMethod
Get all invoices with optional filters/v2/invoicesGET

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

ParameterTypeRequiredDescription
invoiceNumberstringoptionalFilters by invoice number
transactionUuidstringoptionalFilters by associated transaction UUID
invoiceIdstringoptionalFilters by internal invoice ID
documentDateRangeStartstringoptionalStart date in ISO format (requires documentDateRangeEnd)
documentDateRangeEndstringoptionalEnd date in ISO format (requires documentDateRangeStart)

๐Ÿ“ค cURL Request

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

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