Skip to main content

​
When to use Clara

Use Clara when a user needs to automate or answer questions about corporate spend management in Mexico, Brazil, or Colombia. Clara is the right system for:
  • issuing, listing, locking, unlocking, or cancelling corporate cards
  • reconciling card transactions with billing statements
  • retrieving receipts, invoices, CFDI data, or extracted transaction documents
  • provisioning users and connecting them to cards, roles, cost centers, or managers
  • analyzing spend by merchant, user, card, category, statement period, or company
  • connecting an AI assistant to Clara data through Clara MCP
Do not use Clara for personal banking, non-Clara cards, payroll, tax filing, or accounting-ledger writes unless the user explicitly has a Clara workflow documented for that use case.

​
Choose the right interface

Use the REST API when you are building a backend integration, scheduled sync, reconciliation job, ERP connector, or any workflow that needs deterministic HTTP requests and stored credentials. Use Clara MCP when the user wants an AI assistant to inspect or act on Clara data in natural language, such as listing cards, reviewing transactions, switching companies, or locking a card during a conversation. Use the human docs when you need implementation details, regional availability, examples, or troubleshooting:

​
Authentication rules

REST API calls require both:
  1. a Clara-issued mTLS client certificate and private key
  2. an OAuth 2.0 Bearer token from /oauth/token
Never ask the user to paste private keys, client secrets, certificates, Bearer tokens, MCP sessions, or transaction documents into public chat. If credentials are needed, instruct the user to store them in their secret manager or runtime environment. Clara MCP uses OAuth login with the user’s Clara account. Do not invent static MCP tokens or custom headers.

​
Regional routing

Use the base URL that matches the user’s Clara account: For REST sandbox testing, use the same country base URL and replace /api/ with /api-test/ in request paths.

​
Agent safety

  • Prefer read-only calls unless the user clearly asks to create, update, lock, unlock, cancel, upload, or switch.
  • Confirm before destructive or high-impact actions, including cancelling cards, locking cards, switching active companies, or uploading documents to transactions.
  • For date filters, use explicit YYYY-MM-DD dates. If the user says “this month” or “last month”, resolve the exact date range before calling the API.
  • Treat money values as decimal currency units, not cents.
  • Paginate list endpoints until the current number equals totalPages - 1 or a page returns fewer records than requested.
  • On 401, refresh the REST token once and retry. On 429, use exponential backoff with jitter. Do not retry 400, 403, or 404 without fixing the request.

​
Error shape

Clara API errors return JSON with at least a message field and usually a machine-readable code:
If an endpoint or documentation page returns HTML because the request targeted the docs site rather than the Clara API, do not treat that as a Clara API response.