# Clara API Documentation

> Clara is a corporate card and spend management platform for Latin America.
> This documentation covers the Clara REST API (v1, v2, v3) for programmatic access to cards, transactions, users, invoices, and more.

## Documentation Variants

- **llms.txt** (this file) — Concise index with links and key concepts. Start here.
- **llms-api.txt** — Complete endpoint reference with required fields, parameter types, and response schemas. Use when generating code.
- **llms-guides.txt** — End-to-end workflow guides with real curl examples. Use when helping users accomplish tasks (reconciliation, card provisioning, VCN payments, Brazil digital account).

## Authentication

Clara API uses **mTLS (mutual TLS) + OAuth 2.0 Bearer token** authentication.
- Every request requires a valid X.509 client certificate (CN=Clara API Certificate Authority)
- Every request requires a JWT Bearer token obtained from the `/oauth/token` endpoint (Auth0)
- Token response includes `expires_in` (seconds). Refresh proactively before expiry — do not wait for a 401.
- Base URLs: `https://public-api.mx.clara.com` (MX), `https://public-api.br.clara.com` (BR), `https://public-api.co.clara.com` (CO)
- Token endpoint: `POST /oauth/token` with `Authorization: Basic base64(CLIENT_ID:CLIENT_SECRET)`
- Multi-entity: include `X-Tax-Identifier: <tax_id>` header to act on behalf of a specific subsidiary

## API Versions

- **v3** — Current version. Recommended for all new integrations.
- **v2** — Stable, still supported.
- **v1** — Legacy.

## Sandbox

Sandbox uses the same base URLs with `/api-test/` instead of `/api/` in the path.
Example: `GET https://public-api.mx.clara.com/api-test/v3/transactions`
Auth is identical to production. Data is isolated and reset periodically.

## Docs

### Getting Started
- [Getting Started](/introduction): Overview of Clara REST API, base URLs, and quick start.
- [Authentication (mTLS + OAuth 2.0)](/authentication): How to obtain credentials, configure mTLS certificates, get a Bearer token, and handle token expiration/refresh.
- [Sandbox](/sandbox): Sandbox URLs, credentials, and differences from production.
- [Code Examples by Language](/code-examples): Auth samples in Python, Node.js, Java, Go, Ruby, PHP, cURL.
- [API Versioning](/versioning): Versioning strategy and changelog.
- [Cards API Guide](/cards-guide): How to use cards — restrictions, limits, card types.
- [Troubleshooting](/troubleshooting): Common errors, mTLS issues, OAuth debugging.

### Guides
- [Reconcile Transactions](/guides/reconcile-transactions): Full monthly reconciliation flow — fetch transactions by date range, paginate, match to billing statement, label, download receipts, export to accounting system.
- [Provision Cards for Employees](/guides/provision-cards): Onboard a user, issue a virtual card, apply spending restrictions, confirm status, and offboard (lock + delete).
- [Generate a VCN for a Purchase](/guides/vcn-purchase): Create a VCN locked to a supplier and amount, use it for payment, verify transaction, cancel unused VCNs.

### API Reference — v3 (Current)

#### Cards API v3 — `POST /api/v3/cards`
Required fields: `type` (string enum: `VIRTUAL`|`PHYSICAL`), `alias` (string), `userUuid` (uuid).
Optional: `threshold` (decimal, currency units), `periodicity` (enum: `MONTHLY`|`WEEKLY`|`DAILY`), `businessType` (enum: `BUSINESS`|`WORLD_ELITE`).
Response (`CardV3`): `uuid`, `alias`, `status` (object: `{ code, description }`), `maskedPan`, `threshold`, `periodicity`, `type`, `user`.
Note: `claraStatus` is deprecated as of May 2025 — use `status` instead.

#### Cards API v3 — `GET /api/v3/cards`
Filters: `userUuid` (uuid), `username` (string), `status` (string), `periodicity` (string), `type` (string), `userErpId` (string).
Response (`CardPageV3`): `content` (array of CardV3), `totalElements`, `totalPages`, `size`, `number`.
Lock/unlock: `PATCH /api/v3/cards/{uuid}/lock` with body `{ "lockCode": 16 }`. Use `lockCode: 16` for API-initiated locks.

#### Transactions API v3 — `GET /api/v3/transactions`
Filters (all optional, dates in `YYYY-MM-DD`): `operationDateRangeStart`, `operationDateRangeEnd`, `accountingDateRangeStart`, `accountingDateRangeEnd`, `lastUpdateDateRangeStart`, `lastUpdateDateRangeEnd`, `userUuid`, `cardUuid`, `cardLastDigits`, `status`, `operationTypeCode`.
Pagination: `page` (0-indexed), `size` (max 100).
Response (`TransactionPageV3`): `content` (array of TransactionResponseV3), `totalElements`, `totalPages`, `size`, `number`.
Key fields per transaction: `uuid`, `type` (PURCHASE|REFUND|FEE|CREDIT|PAYMENT), `status` (object: `{ code, description }`), `amountValue` (object: `{ value, currency }`), `merchant`, `card`, `user`, `labels`, `billingStatement`, `hasInvoice`, `hasAttachments`, `hasExtractedDocuments`, `accountingFields`.
Status codes: `NOTIFICATION` (ON), `PRE_AUTHORIZED` (AU), `AUTHORIZED` (OP), `REJECTED` (RJ), `SYSTEM_TRANSACTION` (EC).

#### Users API v3 — `GET /api/v3/users`
Filters: `email`, `name`, `lastName`, `fullName`, `status` (ACTIVE|LOCKED), `role` (EMPLOYEE|MANAGER|COMPANY_OWNER|BOOKKEEPER), `uuid`, `taxIdentifier`, `erpId`, `locationUuid`, `managerUuid`, `mobilePhone`, `createdAtStart`, `createdAtEnd`.
Response: `totalElements`, `content` (array of users with `uuid`, `fullName`, `email`, `role`, `status`).

#### Billing Statements API v3 — `GET /api/v3/billing-statements`
Response: array of statements with `uuid`, `statementStartDate`, `statementEndDate`, `currency`, `totalAmount`, `status` (OPEN|CLOSED), `generatedAt`.
Get statement transactions: `GET /api/v3/billing-statements/{uuid}/transactions` — same filters as main transactions endpoint.

#### Digital Account API v3 — `GET /api/v3/digital-accounts` (Brazil only)
Filters: `startDate` (YYYY-MM-DD), `endDate` (YYYY-MM-DD), `transactionTypeName` (enum: `PIX`|`TED`|`BILL`|`TRANSACTION`).
Response: `data` (array), `meta` (totalPages, totalItems, itemsPerPage, currentPage).
Key fields per item: `id`, `transactionDate`, `amount` (decimal units), `method` (PIX|TED|Bill|Transfer), `type` (string), `source` (name, taxId, institution), `beneficiary` (name, taxId, institution), `description`, `charges`.

#### Other v3 Endpoints
- [Documents API v3](/v3/documents): `GET /api/v3/transactions/{uuid}/documents` — pre-signed S3 download links, valid 12 hours.
- [Extracted Documents API v3](/v3/extracted-documents): `GET /api/v3/transactions/{uuid}/extracted-documents` — structured fiscal data. Filter by `type` (MEXICAN_FISCAL_INVOICE|INVOICE|RECEIPT|OTHER) and `validationStatus` (VALIDATED_BY_CLARA|VALIDATED_BY_USER|NOT_VERIFIED).
- [Invoices API v3](/v3/invoices): CFDI fiscal invoices. Mexico only.
- [Reimbursements API v3](/v3/reimbursements): Reimbursement records. Filters: date ranges, statuses, requesterUuids, categoryCodes.

### API Reference — v2
- [Card Configurations API v2](/v2/card-configurations): `POST /api/v2/cards/{uuid}/configurations`. Fields: `period` (startDate, endDate, startTime HH:MM, endTime HH:MM, enableAutoDeletion bool), `atmCashLimit` (decimal, physical cards only), `weekdays` (values array, allowedDaysOfUse bool), `merchants` (values array of MCC category strings, allowedMerchants bool).
- [Boleto Payments API v2](/v2/boleto-payments): Create and retrieve boleto bill payments. `POST /api/v2/payments` with `barcodeDigitableLine`. Brazil only.
- [DDA - Authorized Direct Debit API v2](/v2/dda): Authorized direct debit management. Brazil only.
- [Invoices API v2](/v2/invoices): CFDI fiscal invoices linked to transactions. Mexico only.
- [Labels API v2](/v2/labels): Create, update, retrieve, delete transaction labels.
- [Users API v2](/v2/users): Create and retrieve users.
- [Locations API v2](/v2/locations): Retrieve cost centers and locations.
- [Groups API v2](/v2/groups): CRUD for groups/departments.
- [Cards API v2](/v2/cards): Create, update, lock/unlock, delete cards.
- [Transactions API v2](/v2/transactions): Retrieve all transactions or by UUID.
- [Billing Statements API v2](/v2/billing-statements): Access billing statements and their transactions.
- [Attachments API v2](/v2/attachments): Retrieve transaction attachments (receipts) with download links.

### API Reference — v1 (Legacy)
- [Users API v1](/v1/users): Retrieve all users or find by UUID.
- [Locations API v1](/v1/locations): Retrieve company locations.
- [Groups API v1](/v1/groups): Retrieve groups.
- [Cards API v1](/v1/cards): Retrieve all cards or find by UUID.
- [Transactions API v1](/v1/transactions): Retrieve all transactions or find by UUID.
- [Logs API v1](/v1/logs): Retrieve API access logs by month or day.
- [Webhooks API v1](/v1/webhooks): Subscribe to transaction events via webhooks.
- [Webhook Subscribers API v1](/v1/subscribers): Manage webhook subscribers — create, update, add events, delete.

### Clara MCP
- [Clara MCP: Introduction](/mcp/introduction): What Clara MCP is, available tools (Beta), who can use it, how to get a token (self-service at Settings → Integrations → Clara MCP), security model, and FAQ.
- [MCP Quickstart](/mcp/quickstart): Step-by-step setup for Claude Desktop (via supergateway + Node.js), Claude Code CLI, and other MCP-compatible tools. Includes per-country server URLs and troubleshooting.
  - MCP Server URLs: MX `https://api.clara.team/mcp`, BR `https://api-prod.br.clara.com/mcp`, CO `https://api-gw-co-prod.clara.com/mcp`
  - Auth header: `clara-mcp-token: <token>`
  - Transport: Streamable HTTP
- [MCP Tools Reference](/mcp/tools): `list_cards` (no params), `list_transactions` (filters: card name/last4, date ISO 8601, amount decimal, category string), `lock_card` (card name or last4), `unlock_card` (card name or last4). Empty results return `[]`, not an error. Default date range is current billing period.

### VCN API
- [VCN API: Introduction](/vcn/introduction): Virtual Card Numbers for B2B purchasing — key concepts (RCN, VCN, Template, Supplier), authentication, endpoint overview, sandbox.
- [VCN Lifecycle Walkthrough](/vcn/lifecycle): Step-by-step: `GET /api/v1/vcn?companyDetail=ALL` to retrieve rcnId/supplierId/templateId → `POST /api/v1/vcn/card` to create VCN (required: rcnId, supplierId, templateId, amount, validFrom, validTo) → `PUT /api/v1/vcn/card/{id}` to update → `POST /api/v1/vcn/card/{id}/cancel` to cancel.
  - VCN card details (cardNumber, cvv, expirationDate) are returned once at creation — not retrievable again.

## Regional Feature Reference

| Feature | Mexico (MX) | Brazil (BR) | Colombia (CO) |
|---------|:-----------:|:-----------:|:-------------:|
| Corporate cards (physical + virtual) | ✓ | ✓ | ✓ |
| Card configurations (time, MCC, ATM) | ✓ | ✓ | ✓ |
| Reimbursements | ✓ | ✓ | ✓ |
| CFDI fiscal invoices | ✓ | — | — |
| Digital Account (PIX, TED) | — | ✓ | — |
| Boleto payments | — | ✓ | — |
| DDA (Authorized Direct Debit) | — | ✓ | — |
| VCN (Virtual Card Numbers) | ✓ | ✓ | ✓ |
| Currency | MXN | BRL | COP |

## Key Concepts

- **mTLS**: All API calls require a client certificate. Obtain via your Clara dashboard or CSM.
- **Bearer Token**: Exchange client_id + client_secret via POST /oauth/token. Token includes `expires_in` — refresh proactively.
- **Pagination**: `page` (0-indexed) + `size` (max 100). Response includes `totalPages` and `number` (current page). Continue until `number == totalPages - 1` or page returns fewer items than `size`.
- **Amounts**: Decimal currency units (not cents). Use `BigDecimal` or equivalent in typed languages.
- **Date formats**: All date filters use `YYYY-MM-DD`. DateTime fields in responses use ISO 8601 (`YYYY-MM-DDTHH:MM:SSZ`).
- **Environments**: Mexico (MX), Brazil (BR), Colombia (CO) — each has its own base URL and token endpoint.
- **Sandbox**: Path prefix `/api-test/` instead of `/api/`. Same auth, isolated data.
- **CFDI**: Mexico-specific fiscal invoice XML format linked to transactions.
- **PIX/TED**: Brazil-specific payment types in the Digital Account API.
- **Boleto**: Brazil-specific bill payment method.
- **VCN**: Virtual Card Number — single/limited-use card locked to a specific supplier and amount for B2B purchasing.
- **claraStatus**: Deprecated (removed May 2025). Use `status` field instead in cards-v3 responses.