{ "openapi": "3.1.0", "info": { "title": "Clara API", "summary": "Corporate card and spend management API for Mexico, Brazil, and Colombia.", "description": "Use the Clara API to manage corporate cards, retrieve transactions, provision users, reconcile billing statements, download transaction documents, and automate spend-management workflows. Every API request requires both mutual TLS and an OAuth 2.0 Bearer token. This docs-published schema is derived from the current Clara developer documentation and should be checked against backend-owned API contracts before being treated as exhaustive.", "version": "3.0.0", "contact": { "name": "Clara Integration Support", "email": "integration.support.mx@clara.team", "url": "https://developers.clara.team" } }, "x-source": "Derived from the developers.clara.team documentation in this repository. Replace with the backend-owned OpenAPI contract if one is available.", "servers": [ { "url": "https://public-api.mx.clara.com", "description": "Mexico production" }, { "url": "https://public-api.br.clara.com", "description": "Brazil production" }, { "url": "https://public-api.co.clara.com", "description": "Colombia production" }, { "url": "https://public-api.mx.clara.com/api-test", "description": "Mexico sandbox. Use the same paths without the leading /api segment when testing, for example /v3/transactions." }, { "url": "https://public-api.br.clara.com/api-test", "description": "Brazil sandbox. Use the same paths without the leading /api segment when testing, for example /v3/transactions." }, { "url": "https://public-api.co.clara.com/api-test", "description": "Colombia sandbox. Use the same paths without the leading /api segment when testing, for example /v3/transactions." } ], "security": [ { "MutualTLS": [], "BearerAuth": [] } ], "tags": [ { "name": "Authentication", "description": "OAuth token exchange. Requests also require mutual TLS." }, { "name": "Cards", "description": "Create, list, retrieve, lock, unlock, update, and cancel corporate cards." }, { "name": "Transactions", "description": "Search card transactions and retrieve linked documents or fiscal data." }, { "name": "Users", "description": "Create, update, retrieve, delete, and filter users by identity, role, status, manager, or location." }, { "name": "Invoices", "description": "Retrieve Mexico CFDI invoice metadata linked to transactions." }, { "name": "Extracted Documents", "description": "Retrieve structured invoice, receipt, and other document data extracted from transactions." }, { "name": "Reimbursements", "description": "Retrieve reimbursement data for out-of-pocket expenses." }, { "name": "Billing Statements", "description": "Retrieve billing statements and statement transactions for reconciliation." }, { "name": "Digital Account", "description": "Brazil-only digital account movement search." } ], "paths": { "/oauth/token": { "post": { "operationId": "createOAuthToken", "summary": "Create an OAuth access token", "description": "Exchange client credentials for a short-lived Bearer token. Send the client ID and secret with HTTP Basic authentication and present the mTLS client certificate on the request.", "tags": [ "Authentication" ], "security": [ { "MutualTLS": [], "BasicAuth": [] } ], "responses": { "200": { "description": "Access token created.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/OAuthTokenResponse" } } } }, "401": { "$ref": "#/components/responses/Unauthorized" } } } }, "/api/v3/cards": { "get": { "operationId": "listCardsV3", "summary": "List cards", "description": "List corporate cards with optional filters for cardholder, card status, periodicity, type, or ERP user ID.", "tags": [ "Cards" ], "parameters": [ { "$ref": "#/components/parameters/Page" }, { "$ref": "#/components/parameters/Size" }, { "name": "userUuid", "in": "query", "description": "Filter cards that belong to a specific user UUID. Do not combine with userErpId.", "schema": { "type": "string", "format": "uuid" } }, { "name": "username", "in": "query", "description": "Filter by the cardholder username or email.", "schema": { "type": "string" } }, { "name": "status", "in": "query", "description": "Filter by card status.", "schema": { "type": "string", "enum": [ "ACTIVE", "BLOCKED", "CANCELLED", "EXPIRED" ] } }, { "name": "periodicity", "in": "query", "description": "Filter by spending-limit reset frequency.", "schema": { "$ref": "#/components/schemas/Periodicity" } }, { "name": "type", "in": "query", "description": "Filter by card product and format type.", "schema": { "$ref": "#/components/schemas/CardListType" } }, { "name": "userErpId", "in": "query", "description": "Filter by the cardholder ERP identifier. Do not combine with userUuid.", "schema": { "type": "string" } } ], "responses": { "200": { "description": "Paginated cards.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/CardPageV3" } } } }, "400": { "$ref": "#/components/responses/BadRequest" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" } } }, "post": { "operationId": "createCardV3", "summary": "Create a card", "description": "Create one virtual or physical card for an active user. Use webhooks or listCardsV3 to confirm asynchronous downstream state changes where applicable.", "tags": [ "Cards" ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/CreateCardRequestV3" } } } }, "responses": { "200": { "description": "Created card.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/CardV3" } } } }, "400": { "$ref": "#/components/responses/BadRequest" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "422": { "$ref": "#/components/responses/BusinessValidation" } } } }, "/api/v3/cards/{uuid}": { "get": { "operationId": "getCardV3", "summary": "Get a card", "description": "Retrieve a single card by UUID.", "tags": [ "Cards" ], "parameters": [ { "$ref": "#/components/parameters/CardUuid" } ], "responses": { "200": { "description": "Card details.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/CardV3" } } } }, "404": { "$ref": "#/components/responses/NotFound" } } }, "delete": { "operationId": "deleteCardV3", "summary": "Cancel a card", "description": "Cancel a card permanently. The card cannot be recovered after deletion.", "tags": [ "Cards" ], "parameters": [ { "$ref": "#/components/parameters/CardUuid" } ], "responses": { "204": { "description": "Card cancelled." }, "404": { "$ref": "#/components/responses/NotFound" } } } }, "/api/v3/cards/{uuid}/lock": { "patch": { "operationId": "setCardLockV3", "summary": "Lock or unlock a card", "description": "Lock or unlock one card. Use lockCode 16 for standard API-initiated locks.", "tags": [ "Cards" ], "parameters": [ { "$ref": "#/components/parameters/CardUuid" } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/SetCardLockRequestV3" } } } }, "responses": { "200": { "description": "Updated card.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/CardV3" } } } }, "404": { "$ref": "#/components/responses/NotFound" } } } }, "/api/v3/cards/{uuid}/threshold": { "patch": { "operationId": "updateCardThresholdV3", "summary": "Update a card threshold", "description": "Update the spending limit for a card. The value is decimal currency units, not cents.", "tags": [ "Cards" ], "parameters": [ { "$ref": "#/components/parameters/CardUuid" } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/UpdateCardThresholdRequestV3" } } } }, "responses": { "200": { "description": "Updated card.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/CardV3" } } } }, "422": { "$ref": "#/components/responses/BusinessValidation" } } } }, "/api/v3/transactions": { "get": { "operationId": "listTransactionsV3", "summary": "List transactions", "description": "Search transactions by date range, card, user, status, type, or last update. Use this operation for reconciliation and spend analysis workflows.", "tags": [ "Transactions" ], "parameters": [ { "$ref": "#/components/parameters/Page" }, { "$ref": "#/components/parameters/Size" }, { "$ref": "#/components/parameters/OperationDateRangeStart" }, { "$ref": "#/components/parameters/OperationDateRangeEnd" }, { "$ref": "#/components/parameters/AccountingDateRangeStart" }, { "$ref": "#/components/parameters/AccountingDateRangeEnd" }, { "name": "userUuid", "in": "query", "description": "Filter by cardholder UUID.", "schema": { "type": "string", "format": "uuid" } }, { "name": "cardUuid", "in": "query", "description": "Filter by card UUID.", "schema": { "type": "string", "format": "uuid" } }, { "name": "cardLastDigits", "in": "query", "description": "Filter by the last four digits of the card number.", "schema": { "type": "string", "pattern": "^[0-9]{4}$" } }, { "name": "status", "in": "query", "description": "Filter by transaction status.", "schema": { "$ref": "#/components/schemas/TransactionStatus" } }, { "name": "operationTypeCode", "in": "query", "description": "Filter by Clara operation type code.", "schema": { "type": "string" } } ], "responses": { "200": { "description": "Paginated transactions.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/TransactionPageV3" } } } }, "400": { "$ref": "#/components/responses/BadRequest" } } } }, "/api/v3/transactions/{uuid}": { "get": { "operationId": "getTransactionV3", "summary": "Get a transaction", "description": "Retrieve a single transaction by UUID.", "tags": [ "Transactions" ], "parameters": [ { "$ref": "#/components/parameters/TransactionUuid" } ], "responses": { "200": { "description": "Transaction details.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/TransactionV3" } } } }, "404": { "$ref": "#/components/responses/NotFound" } } } }, "/api/v3/transactions/{uuid}/documents": { "get": { "operationId": "listTransactionDocumentsV3", "summary": "List transaction documents", "description": "Retrieve documents attached to a transaction, including pre-signed download URLs that expire after 12 hours.", "tags": [ "Transactions" ], "parameters": [ { "$ref": "#/components/parameters/TransactionUuid" } ], "responses": { "200": { "description": "Attached transaction documents.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/TransactionDocumentsResponseV3" } } } }, "404": { "$ref": "#/components/responses/NotFound" } } } }, "/api/v3/users": { "get": { "operationId": "listUsersV3", "summary": "List users", "description": "List Clara users with filters for identity, role, status, tax identifier, ERP ID, location, manager, or creation date.", "tags": [ "Users" ], "parameters": [ { "$ref": "#/components/parameters/Page" }, { "$ref": "#/components/parameters/Size" }, { "name": "email", "in": "query", "description": "Filter by email address.", "schema": { "type": "string", "format": "email" } }, { "name": "fullName", "in": "query", "description": "Filter by full name.", "schema": { "type": "string" } }, { "name": "uuid", "in": "query", "description": "Filter by user UUID.", "schema": { "type": "string", "format": "uuid" } }, { "name": "name", "in": "query", "description": "Filter by first name.", "schema": { "type": "string" } }, { "name": "lastName", "in": "query", "description": "Filter by last name.", "schema": { "type": "string" } }, { "name": "mobilePhone", "in": "query", "description": "Filter by mobile phone number.", "schema": { "type": "string" } }, { "name": "taxIdentifier", "in": "query", "description": "Filter by tax identifier.", "schema": { "type": "string" } }, { "name": "erpId", "in": "query", "description": "Filter by ERP identifier.", "schema": { "type": "string" } }, { "name": "createdAtStart", "in": "query", "description": "Filter users created on or after this date.", "schema": { "type": "string", "format": "date" } }, { "name": "createdAtEnd", "in": "query", "description": "Filter users created on or before this date.", "schema": { "type": "string", "format": "date" } }, { "name": "locationUuid", "in": "query", "description": "Filter by location UUID.", "schema": { "type": "string", "format": "uuid" } }, { "name": "locationName", "in": "query", "description": "Filter by location name.", "schema": { "type": "string" } }, { "name": "managerUuid", "in": "query", "description": "Filter by manager UUID.", "schema": { "type": "string", "format": "uuid" } }, { "name": "status", "in": "query", "description": "Filter by user status.", "schema": { "$ref": "#/components/schemas/UserStatus" } }, { "name": "role", "in": "query", "description": "Filter by Clara user role.", "schema": { "$ref": "#/components/schemas/UserRole" } } ], "responses": { "200": { "description": "Paginated users.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/UserPageV3" } } } } } }, "post": { "operationId": "createUserV3", "summary": "Create a user", "description": "Create a user in the company account. Non-company-owner users generally require group and location assignment, and tax identifier length depends on country.", "tags": [ "Users" ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/CreateUserRequestV3" } } } }, "responses": { "201": { "description": "User created.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/CreateUserResponseV3" } } } }, "400": { "$ref": "#/components/responses/BadRequest" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "422": { "$ref": "#/components/responses/BusinessValidation" } } } }, "/api/v3/users/{uuid}": { "get": { "operationId": "getUserV3", "summary": "Get a user", "description": "Retrieve a single user by UUID.", "tags": [ "Users" ], "parameters": [ { "$ref": "#/components/parameters/UserUuid" } ], "responses": { "200": { "description": "User details.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/UserV3" } } } }, "404": { "$ref": "#/components/responses/NotFound" } } }, "patch": { "operationId": "updateUserV3", "summary": "Update a user", "description": "Update user profile, role, hierarchy, location, ERP, tax, or group membership fields. When cleanGroups is true, groupsToAdd must leave the user with at least one group.", "tags": [ "Users" ], "parameters": [ { "$ref": "#/components/parameters/UserUuid" } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/UpdateUserRequestV3" } } } }, "responses": { "200": { "description": "User updated." }, "400": { "$ref": "#/components/responses/BadRequest" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "404": { "$ref": "#/components/responses/NotFound" }, "422": { "$ref": "#/components/responses/BusinessValidation" } } }, "delete": { "operationId": "deleteUserV3", "summary": "Delete a user", "description": "Delete a user by UUID.", "tags": [ "Users" ], "parameters": [ { "$ref": "#/components/parameters/UserUuid" } ], "responses": { "204": { "description": "User deleted." }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "404": { "$ref": "#/components/responses/NotFound" } } } }, "/api/v3/transactions/labels/bulk": { "post": { "operationId": "bulkBindTransactionLabelsV3", "summary": "Bulk bind labels to transactions", "description": "Bind one or more label UUIDs to multiple transactions in a single request.", "tags": [ "Transactions" ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/BulkTransactionLabelsRequestV3" } } } }, "responses": { "200": { "description": "Labels bound to transactions." }, "400": { "$ref": "#/components/responses/BadRequest" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" } } } }, "/api/v3/transactions/{uuid}/invoices": { "get": { "operationId": "listTransactionInvoicesV3", "summary": "List transaction invoices", "description": "Retrieve Mexico CFDI invoice metadata associated with a specific transaction. Invoice download URLs, when returned, are temporary.", "tags": [ "Invoices", "Transactions" ], "parameters": [ { "$ref": "#/components/parameters/TransactionUuid" } ], "responses": { "200": { "description": "Transaction invoice data.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/TransactionInvoiceResponseV3" } } } }, "404": { "$ref": "#/components/responses/NotFound" } } } }, "/api/v3/invoices": { "get": { "operationId": "listInvoicesV3", "summary": "List invoices", "description": "Find invoices with optional filters for invoice number, issuer RFC, transaction UUID, invoice ID, and document date range.", "tags": [ "Invoices" ], "parameters": [ { "$ref": "#/components/parameters/Page" }, { "$ref": "#/components/parameters/Size" }, { "name": "invoiceNumber", "in": "query", "description": "Filter by invoice number.", "schema": { "type": "string" } }, { "name": "issuerRfc", "in": "query", "description": "Filter by issuer RFC.", "schema": { "type": "string" } }, { "name": "transactionUuid", "in": "query", "description": "Filter by transaction UUID.", "schema": { "type": "string", "format": "uuid" } }, { "name": "invoiceId", "in": "query", "description": "Filter by invoice ID.", "schema": { "type": "string" } }, { "name": "documentDateRangeStart", "in": "query", "description": "Invoice document-date range start. Use together with documentDateRangeEnd.", "schema": { "type": "string", "format": "date" } }, { "name": "documentDateRangeEnd", "in": "query", "description": "Invoice document-date range end. Use together with documentDateRangeStart.", "schema": { "type": "string", "format": "date" } } ], "responses": { "200": { "description": "Paginated invoices.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/InvoicePageV3" } } } }, "400": { "$ref": "#/components/responses/BadRequest" } } } }, "/api/v3/transactions/{uuid}/extracted-documents": { "get": { "operationId": "listTransactionExtractedDocumentsV3", "summary": "List transaction extracted documents", "description": "Retrieve structured extracted documents associated with a transaction, with optional filters for document UUID, document type, and validation status.", "tags": [ "Extracted Documents", "Transactions" ], "parameters": [ { "$ref": "#/components/parameters/TransactionUuid" }, { "$ref": "#/components/parameters/Page" }, { "$ref": "#/components/parameters/Size" }, { "name": "documentUuid", "in": "query", "description": "Filter by extracted document UUID. Some docs also refer to this filter as uuid.", "schema": { "type": "string", "format": "uuid" } }, { "name": "type", "in": "query", "description": "Filter by extracted document type.", "schema": { "$ref": "#/components/schemas/ExtractedDocumentType" } }, { "name": "validationStatus", "in": "query", "description": "Filter by document validation status.", "schema": { "$ref": "#/components/schemas/DocumentValidationStatus" } } ], "responses": { "200": { "description": "Paginated extracted documents.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ExtractedDocumentPageV3" } } } }, "400": { "$ref": "#/components/responses/BadRequest" } } } }, "/api/v3/reimbursements": { "get": { "operationId": "listReimbursementsV3", "summary": "List reimbursements", "description": "Retrieve reimbursement records with filters for lifecycle status, requester, creation date, expense date, approval date, payment date, update date, category, and UUID.", "tags": [ "Reimbursements" ], "parameters": [ { "$ref": "#/components/parameters/Page" }, { "$ref": "#/components/parameters/Size" }, { "name": "requestCreationDateStart", "in": "query", "description": "Request creation date start in YYYY-MM-DD format.", "schema": { "type": "string", "format": "date" } }, { "name": "requestCreationDateEnd", "in": "query", "description": "Request creation date end in YYYY-MM-DD format.", "schema": { "type": "string", "format": "date" } }, { "name": "expenseDateStart", "in": "query", "description": "Expense date start in YYYY-MM-DD format.", "schema": { "type": "string", "format": "date" } }, { "name": "expenseDateEnd", "in": "query", "description": "Expense date end in YYYY-MM-DD format.", "schema": { "type": "string", "format": "date" } }, { "name": "finalApprovalDateStart", "in": "query", "description": "Final approval date start in YYYY-MM-DD format.", "schema": { "type": "string", "format": "date" } }, { "name": "finalApprovalDateEnd", "in": "query", "description": "Final approval date end in YYYY-MM-DD format.", "schema": { "type": "string", "format": "date" } }, { "name": "paymentDateStart", "in": "query", "description": "Payment date start in YYYY-MM-DD format.", "schema": { "type": "string", "format": "date" } }, { "name": "paymentDateEnd", "in": "query", "description": "Payment date end in YYYY-MM-DD format.", "schema": { "type": "string", "format": "date" } }, { "name": "lastUpdateDateStart", "in": "query", "description": "Last update date start in YYYY-MM-DD format.", "schema": { "type": "string", "format": "date" } }, { "name": "lastUpdateDateEnd", "in": "query", "description": "Last update date end in YYYY-MM-DD format.", "schema": { "type": "string", "format": "date" } }, { "name": "categoryCodes", "in": "query", "description": "Comma-separated category codes.", "schema": { "type": "array", "items": { "type": "string" } }, "style": "form", "explode": false }, { "name": "requesterUuids", "in": "query", "description": "Comma-separated requester UUIDs.", "schema": { "type": "array", "items": { "type": "string", "format": "uuid" } }, "style": "form", "explode": false }, { "name": "statuses", "in": "query", "description": "Comma-separated reimbursement statuses.", "schema": { "type": "array", "items": { "$ref": "#/components/schemas/ReimbursementStatus" } }, "style": "form", "explode": false }, { "name": "requesterName", "in": "query", "description": "Filter by requester name.", "schema": { "type": "string" } }, { "name": "uuids", "in": "query", "description": "Comma-separated reimbursement UUIDs.", "schema": { "type": "array", "items": { "type": "string", "format": "uuid" } }, "style": "form", "explode": false } ], "responses": { "200": { "description": "Paginated reimbursements.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ReimbursementPageV3" } } } }, "400": { "$ref": "#/components/responses/BadRequest" } } } }, "/api/v3/reimbursements/{uuid}": { "get": { "operationId": "getReimbursementV3", "summary": "Get a reimbursement", "description": "Retrieve a single reimbursement by UUID.", "tags": [ "Reimbursements" ], "parameters": [ { "name": "uuid", "in": "path", "required": true, "description": "Reimbursement UUID.", "schema": { "type": "string", "format": "uuid" } } ], "responses": { "200": { "description": "Reimbursement details.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ReimbursementV3" } } } }, "404": { "$ref": "#/components/responses/NotFound" } } } }, "/api/v3/billing-statements": { "get": { "operationId": "listBillingStatementsV3", "summary": "List billing statements", "description": "List billing statements for reconciliation workflows.", "tags": [ "Billing Statements" ], "responses": { "200": { "description": "Billing statements.", "content": { "application/json": { "schema": { "type": "array", "items": { "$ref": "#/components/schemas/BillingStatementV3" } } } } } } } }, "/api/v3/billing-statements/{uuid}/transactions": { "get": { "operationId": "listBillingStatementTransactionsV3", "summary": "List billing statement transactions", "description": "Retrieve transactions associated with one billing statement. Supports the same pagination and transaction filters as listTransactionsV3.", "tags": [ "Billing Statements", "Transactions" ], "parameters": [ { "name": "uuid", "in": "path", "required": true, "description": "Billing statement UUID.", "schema": { "type": "string", "format": "uuid" } }, { "$ref": "#/components/parameters/Page" }, { "$ref": "#/components/parameters/Size" } ], "responses": { "200": { "description": "Paginated statement transactions.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/TransactionPageV3" } } } }, "404": { "$ref": "#/components/responses/NotFound" } } } }, "/api/v3/digital-accounts": { "get": { "operationId": "listDigitalAccountTransactionsV3", "summary": "List digital account transactions", "description": "Brazil-only endpoint for listing PIX, TED, bill, and transfer movements in the Clara digital account.", "tags": [ "Digital Account" ], "parameters": [ { "name": "startDate", "in": "query", "description": "Start date in YYYY-MM-DD format.", "schema": { "type": "string", "format": "date" } }, { "name": "endDate", "in": "query", "description": "End date in YYYY-MM-DD format.", "schema": { "type": "string", "format": "date" } }, { "name": "transactionTypeName", "in": "query", "description": "Filter by digital account movement type.", "schema": { "type": "string", "enum": [ "PIX", "TED", "BILL", "TRANSACTION" ] } } ], "responses": { "200": { "description": "Digital account movements.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/DigitalAccountTransactionPageV3" } } } } } } } }, "components": { "securitySchemes": { "MutualTLS": { "type": "mutualTLS", "description": "All API requests require a valid Clara-issued X.509 client certificate." }, "BearerAuth": { "type": "http", "scheme": "bearer", "bearerFormat": "JWT", "description": "OAuth 2.0 Bearer token from /oauth/token." }, "BasicAuth": { "type": "http", "scheme": "basic", "description": "Use CLIENT_ID:CLIENT_SECRET when requesting an access token." } }, "parameters": { "Page": { "name": "page", "in": "query", "description": "Zero-based page index.", "schema": { "type": "integer", "minimum": 0, "default": 0 } }, "Size": { "name": "size", "in": "query", "description": "Number of records per page. Use 100 for large exports unless an endpoint documents a lower limit.", "schema": { "type": "integer", "minimum": 1, "maximum": 100, "default": 20 } }, "CardUuid": { "name": "uuid", "in": "path", "required": true, "description": "Card UUID.", "schema": { "type": "string", "format": "uuid" } }, "TransactionUuid": { "name": "uuid", "in": "path", "required": true, "description": "Transaction UUID.", "schema": { "type": "string", "format": "uuid" } }, "UserUuid": { "name": "uuid", "in": "path", "required": true, "description": "User UUID.", "schema": { "type": "string", "format": "uuid" } }, "OperationDateRangeStart": { "name": "operationDateRangeStart", "in": "query", "description": "Inclusive operation-date start in YYYY-MM-DD format.", "schema": { "type": "string", "format": "date" } }, "OperationDateRangeEnd": { "name": "operationDateRangeEnd", "in": "query", "description": "Inclusive operation-date end in YYYY-MM-DD format.", "schema": { "type": "string", "format": "date" } }, "AccountingDateRangeStart": { "name": "accountingDateRangeStart", "in": "query", "description": "Inclusive accounting-date start in YYYY-MM-DD format.", "schema": { "type": "string", "format": "date" } }, "AccountingDateRangeEnd": { "name": "accountingDateRangeEnd", "in": "query", "description": "Inclusive accounting-date end in YYYY-MM-DD format.", "schema": { "type": "string", "format": "date" } } }, "responses": { "BadRequest": { "description": "Bad request. Fix invalid parameters or missing fields before retrying.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "Unauthorized": { "description": "Unauthorized. Refresh the token or verify mTLS certificate configuration.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "Forbidden": { "description": "Forbidden. The token is valid but lacks permission for this resource.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "NotFound": { "description": "Resource not found.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "BusinessValidation": { "description": "Business validation error. The request is well formed but violates a Clara business rule.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } } }, "schemas": { "OAuthTokenResponse": { "type": "object", "required": [ "access_token", "token_type", "expires_in" ], "properties": { "access_token": { "type": "string", "description": "JWT Bearer token." }, "token_type": { "type": "string", "const": "Bearer" }, "expires_in": { "type": "integer", "description": "Token lifetime in seconds." } } }, "ErrorResponse": { "type": "object", "required": [ "message" ], "properties": { "code": { "type": "string", "description": "Machine-readable Clara or HTTP error code when available." }, "message": { "type": "string", "description": "Human-readable error message." }, "timestamp": { "type": "string", "format": "date-time" }, "details": { "type": "array", "items": { "type": "object", "additionalProperties": true } } }, "additionalProperties": true }, "Money": { "type": "object", "properties": { "value": { "type": "number", "description": "Decimal currency units, not cents." }, "amount": { "type": "number", "description": "Decimal currency units, not cents. Some responses use amount instead of value." }, "currency": { "type": "string", "enum": [ "MXN", "BRL", "COP" ] } }, "additionalProperties": true }, "Periodicity": { "type": "string", "enum": [ "DAILY", "WEEKLY", "MONTHLY" ] }, "CardListType": { "type": "string", "enum": [ "MASTER_WORLD_ELITE", "MASTER_CORPORATE", "MASTER_VIRTUAL", "VISA_PHYSICAL", "VISA_VIRTUAL" ] }, "CreateCardType": { "type": "string", "enum": [ "VIRTUAL", "PHYSICAL" ] }, "BusinessType": { "type": "string", "enum": [ "BUSINESS", "WORLD_ELITE" ] }, "CardV3": { "type": "object", "required": [ "uuid", "alias", "status", "maskedPan", "type" ], "properties": { "uuid": { "type": "string", "format": "uuid" }, "alias": { "type": "string" }, "status": { "oneOf": [ { "type": "string" }, { "$ref": "#/components/schemas/StatusObject" } ] }, "claraStatus": { "type": "string", "deprecated": true, "description": "Deprecated as of May 2025. Use status instead." }, "lockCode": { "type": [ "string", "integer", "null" ] }, "maskedPan": { "type": "string" }, "threshold": { "type": "number" }, "periodicity": { "oneOf": [ { "$ref": "#/components/schemas/Periodicity" }, { "type": "object", "properties": { "type": { "$ref": "#/components/schemas/Periodicity" } }, "additionalProperties": true } ] }, "type": { "oneOf": [ { "$ref": "#/components/schemas/CardListType" }, { "type": "object", "additionalProperties": true } ] }, "user": { "$ref": "#/components/schemas/CardUser" } }, "additionalProperties": true }, "CardUser": { "type": "object", "properties": { "uuid": { "type": "string", "format": "uuid" }, "name": { "type": "string" }, "fullName": { "type": "string" }, "username": { "type": "string" }, "email": { "type": "string", "format": "email" } }, "additionalProperties": true }, "CardPageV3": { "type": "object", "required": [ "content", "totalElements", "totalPages", "size", "number" ], "properties": { "content": { "type": "array", "items": { "$ref": "#/components/schemas/CardV3" } }, "totalElements": { "type": "integer" }, "totalPages": { "type": "integer" }, "size": { "type": "integer" }, "number": { "type": "integer" } } }, "CreateCardRequestV3": { "type": "object", "required": [ "type", "alias", "userUuid" ], "properties": { "type": { "$ref": "#/components/schemas/CreateCardType" }, "alias": { "type": "string", "minLength": 1 }, "userUuid": { "type": "string", "format": "uuid" }, "threshold": { "type": "number", "description": "Decimal currency units, not cents." }, "periodicity": { "$ref": "#/components/schemas/Periodicity" }, "businessType": { "$ref": "#/components/schemas/BusinessType" } }, "additionalProperties": false }, "SetCardLockRequestV3": { "type": "object", "required": [ "lockCode" ], "properties": { "lockCode": { "type": "integer", "description": "Use 16 for a standard API-initiated lock." } }, "additionalProperties": false }, "UpdateCardThresholdRequestV3": { "type": "object", "required": [ "threshold" ], "properties": { "threshold": { "type": "number", "minimum": 0, "description": "Decimal currency units, not cents." } }, "additionalProperties": false }, "StatusObject": { "type": "object", "properties": { "code": { "type": "string" }, "description": { "type": "string" } }, "additionalProperties": true }, "TransactionStatus": { "type": "string", "enum": [ "NOTIFICATION", "PRE_AUTHORIZED", "AUTHORIZED", "REJECTED", "SYSTEM_TRANSACTION" ] }, "TransactionType": { "type": "string", "enum": [ "PURCHASE", "REFUND", "FEE", "CREDIT", "PAYMENT" ] }, "TransactionV3": { "type": "object", "required": [ "uuid", "type", "status", "amountValue" ], "properties": { "uuid": { "type": "string", "format": "uuid" }, "type": { "$ref": "#/components/schemas/TransactionType" }, "transactionLabel": { "type": "string" }, "status": { "oneOf": [ { "$ref": "#/components/schemas/TransactionStatus" }, { "$ref": "#/components/schemas/StatusObject" } ] }, "amountValue": { "$ref": "#/components/schemas/Money" }, "originalAmount": { "$ref": "#/components/schemas/Money" }, "merchant": { "type": "object", "properties": { "name": { "type": "string" }, "category": { "type": "string" }, "mcc": { "type": "string" } }, "additionalProperties": true }, "card": { "type": "object", "properties": { "uuid": { "type": "string", "format": "uuid" }, "lastFourDigits": { "type": "string" }, "maskedPan": { "type": "string" } }, "additionalProperties": true }, "user": { "$ref": "#/components/schemas/CardUser" }, "labels": { "type": "array", "items": { "type": "object", "additionalProperties": true } }, "billingStatement": { "$ref": "#/components/schemas/BillingStatementV3" }, "hasInvoice": { "type": [ "boolean", "object" ] }, "hasAttachments": { "type": [ "boolean", "object" ] }, "hasExtractedDocuments": { "type": [ "boolean", "object" ] }, "accountingFields": { "type": "array", "items": { "type": "object", "additionalProperties": true } }, "accountingStatus": { "$ref": "#/components/schemas/AccountingStatus" } }, "additionalProperties": true }, "TransactionPageV3": { "type": "object", "required": [ "content", "totalElements", "totalPages", "size", "number" ], "properties": { "content": { "type": "array", "items": { "$ref": "#/components/schemas/TransactionV3" } }, "totalElements": { "type": "integer" }, "totalPages": { "type": "integer" }, "size": { "type": "integer" }, "number": { "type": "integer" } } }, "TransactionDocumentsResponseV3": { "type": "object", "properties": { "uuid": { "type": "string", "format": "uuid" }, "attachments": { "type": "array", "items": { "type": "object", "properties": { "uuid": { "type": "string", "format": "uuid" }, "fileName": { "type": "string" }, "format": { "type": "string" }, "download": { "type": "object", "properties": { "url": { "type": "string", "format": "uri" }, "urlExpiration": { "type": "string", "format": "date-time" } }, "additionalProperties": true } }, "additionalProperties": true } } }, "additionalProperties": true }, "UserRole": { "type": "string", "enum": [ "EMPLOYEE", "MANAGER", "COMPANY_OWNER", "BOOKKEEPER" ] }, "UserStatus": { "type": "string", "enum": [ "ONBOARDING_CANDIDATE", "WAITING", "DELETED", "ACTIVE", "LOCKED", "INACTIVE", "PENDING", "MASTER_LOCKED", "CLARA_BLOCKED" ] }, "UserV3": { "type": "object", "properties": { "uuid": { "type": "string", "format": "uuid" }, "fullName": { "type": "string" }, "name": { "type": "string" }, "lastName": { "type": "string" }, "email": { "type": "string", "format": "email" }, "mobilePhone": { "type": "string" }, "taxIdentifier": { "type": "string" }, "role": { "$ref": "#/components/schemas/UserRole" }, "status": { "oneOf": [ { "$ref": "#/components/schemas/UserStatus" }, { "$ref": "#/components/schemas/StatusObject" } ] }, "erpId": { "type": "string" }, "createdAt": { "type": "string", "format": "date-time" }, "groups": { "type": "array", "items": { "$ref": "#/components/schemas/LinkedResource" } }, "cards": { "type": "array", "items": { "$ref": "#/components/schemas/CardV3" } }, "manager": { "$ref": "#/components/schemas/CardUser" }, "location": { "$ref": "#/components/schemas/LinkedResource" } }, "additionalProperties": true }, "UserPageV3": { "type": "object", "required": [ "content", "totalElements" ], "properties": { "content": { "type": "array", "items": { "$ref": "#/components/schemas/UserV3" } }, "totalElements": { "type": "integer" }, "totalPages": { "type": "integer" }, "size": { "type": "integer" }, "number": { "type": "integer" } } }, "CreateUserRequestV3": { "type": "object", "required": [ "email", "name", "lastName", "mobilePhone", "role" ], "properties": { "email": { "type": "string", "format": "email" }, "name": { "type": "string" }, "lastName": { "type": "string" }, "groups": { "type": "array", "items": { "type": "string", "format": "uuid" } }, "lada": { "type": "string" }, "mobilePhone": { "type": "string" }, "role": { "$ref": "#/components/schemas/UserRole" }, "managerUuid": { "type": "string", "format": "uuid" }, "locationUuid": { "type": "string", "format": "uuid" }, "erpId": { "type": "string" }, "taxIdentifier": { "type": "string", "description": "Tax identifier. Documented country lengths: MX 11 or 13, CO 7-10, BR 11." }, "foreign": { "type": "boolean", "default": false } }, "additionalProperties": false }, "CreateUserResponseV3": { "type": "object", "required": [ "uuid" ], "properties": { "uuid": { "type": "string", "format": "uuid" } }, "additionalProperties": true }, "UpdateUserRequestV3": { "type": "object", "properties": { "email": { "type": "string", "format": "email" }, "name": { "type": "string" }, "lastName": { "type": "string" }, "lada": { "type": "string", "description": "Must be provided together with mobilePhone when changing phone fields." }, "mobilePhone": { "type": "string", "description": "Must be provided together with lada when changing phone fields." }, "role": { "$ref": "#/components/schemas/UserRole" }, "locationUuid": { "type": "string", "format": "uuid" }, "erpId": { "type": "string" }, "taxIdentifier": { "type": "string", "description": "Tax identifier. Documented country lengths: MX 11 or 13, CO 7-10, BR 11." }, "managerUuid": { "type": "string", "format": "uuid" }, "groupsToAdd": { "type": "array", "items": { "type": "string", "format": "uuid" } }, "groupsToRemove": { "type": "array", "items": { "type": "string", "format": "uuid" } }, "cleanGroups": { "type": "boolean", "default": false } }, "additionalProperties": false }, "BulkTransactionLabelsRequestV3": { "type": "object", "required": [ "transactions" ], "properties": { "transactions": { "type": "array", "minItems": 1, "items": { "type": "object", "required": [ "uuid", "labelsUuid" ], "properties": { "uuid": { "type": "string", "format": "uuid" }, "labelsUuid": { "type": "array", "items": { "type": "string", "format": "uuid" } } }, "additionalProperties": false } } }, "additionalProperties": false }, "InvoiceV3": { "type": "object", "properties": { "invoiceId": { "type": "string" }, "invoiceNumber": { "type": [ "string", "null" ] }, "taxRegime": { "type": "string" }, "issuer": { "type": "object", "properties": { "rfc": { "type": "string" }, "businessName": { "type": "string" } }, "additionalProperties": true }, "taxReceipts": { "type": "object", "additionalProperties": true }, "tax": { "type": "object", "additionalProperties": true }, "amount": { "type": "object", "properties": { "total": { "type": "number" }, "subTotal": { "type": "number" }, "currency": { "type": "string" } }, "additionalProperties": true }, "documentDate": { "type": "string", "format": "date" }, "xmlStatus": { "type": "string" }, "xmlCode": { "type": "string" } }, "additionalProperties": true }, "TransactionInvoiceResponseV3": { "type": "object", "properties": { "transactionUuid": { "type": "string", "format": "uuid" }, "invoices": { "type": "array", "items": { "$ref": "#/components/schemas/InvoiceV3" } }, "content": { "type": "array", "items": { "$ref": "#/components/schemas/InvoiceV3" } }, "totalElements": { "type": "integer" }, "totalPages": { "type": "integer" }, "size": { "type": "integer" }, "number": { "type": "integer" } }, "additionalProperties": true }, "InvoicePageV3": { "type": "object", "properties": { "content": { "type": "array", "items": { "$ref": "#/components/schemas/InvoiceV3" } }, "totalElements": { "type": "integer" }, "totalPages": { "type": "integer" }, "size": { "type": "integer" }, "number": { "type": "integer" }, "first": { "type": "boolean" }, "last": { "type": "boolean" }, "numberOfElements": { "type": "integer" }, "empty": { "type": "boolean" } }, "additionalProperties": true }, "ExtractedDocumentType": { "type": "string", "enum": [ "MEXICAN_FISCAL_INVOICE", "INVOICE", "RECEIPT", "OTHER" ] }, "DocumentValidationStatus": { "type": "string", "enum": [ "VALIDATED_BY_CLARA", "VALIDATED_BY_USER", "NOT_VERIFIED" ] }, "ExtractedDocumentV3": { "type": "object", "properties": { "uuid": { "type": "string", "format": "uuid" }, "type": { "$ref": "#/components/schemas/ExtractedDocumentType" }, "userUuid": { "type": "string", "format": "uuid" }, "data": { "type": "object", "additionalProperties": true }, "fileValidation": { "type": "object", "properties": { "status": { "$ref": "#/components/schemas/DocumentValidationStatus" }, "date": { "type": "string", "format": "date-time" }, "user": { "type": "string" }, "userUuid": { "type": "string", "format": "uuid" } }, "additionalProperties": true } }, "additionalProperties": true }, "ExtractedDocumentPageV3": { "type": "object", "properties": { "content": { "type": "array", "items": { "$ref": "#/components/schemas/ExtractedDocumentV3" } }, "totalElements": { "type": "integer" }, "totalPages": { "type": "integer" }, "size": { "type": "integer" }, "number": { "type": "integer" } }, "additionalProperties": true }, "ReimbursementStatus": { "type": "string", "enum": [ "PENDING", "APPROVED", "SENT_TO_PAY", "PAYMENT_IN_PROGRESS", "PAID", "REJECTED", "FINANCE_REJECTED", "CANCELLED", "NOT_FOUND", "UNAUTHORIZED" ] }, "LinkedResource": { "type": "object", "properties": { "uuid": { "type": "string", "format": "uuid" }, "name": { "type": "string" }, "links": { "type": "array", "items": { "type": "object", "additionalProperties": true } }, "_links": { "type": "object", "additionalProperties": true } }, "additionalProperties": true }, "ReimbursementV3": { "type": "object", "properties": { "uuid": { "type": "string", "format": "uuid" }, "description": { "type": "string" }, "audit": { "type": "object", "additionalProperties": true }, "labels": { "type": "array", "items": { "$ref": "#/components/schemas/LinkedResource" } }, "merchant": { "type": "object", "additionalProperties": true }, "requester": { "$ref": "#/components/schemas/CardUser" }, "groups": { "type": "array", "items": { "$ref": "#/components/schemas/LinkedResource" } }, "locations": { "type": "array", "items": { "$ref": "#/components/schemas/LinkedResource" } }, "amountValue": { "$ref": "#/components/schemas/Money" }, "validationStatus": { "type": "object", "properties": { "status": { "$ref": "#/components/schemas/ReimbursementStatus" }, "comment": { "type": "string" } }, "additionalProperties": true }, "attachments": { "type": "array", "items": { "type": "object", "additionalProperties": true } }, "paymentDetail": { "type": "object", "additionalProperties": true } }, "additionalProperties": true }, "ReimbursementPageV3": { "type": "object", "properties": { "content": { "type": "array", "items": { "$ref": "#/components/schemas/ReimbursementV3" } }, "totalElements": { "type": "integer" }, "totalPages": { "type": "integer" }, "size": { "type": "integer" }, "number": { "type": "integer" } }, "additionalProperties": true }, "BillingStatementV3": { "type": "object", "properties": { "uuid": { "type": "string", "format": "uuid" }, "statementStartDate": { "type": "string", "format": "date" }, "statementEndDate": { "type": "string", "format": "date" }, "currency": { "type": "string", "enum": [ "MXN", "BRL", "COP" ] }, "totalAmount": { "type": "number" }, "status": { "type": "string", "enum": [ "OPEN", "CLOSED" ] }, "generatedAt": { "type": "string", "format": "date-time" } }, "additionalProperties": true }, "DigitalAccountTransactionPageV3": { "type": "object", "properties": { "data": { "type": "array", "items": { "type": "object", "properties": { "id": { "type": "string" }, "transactionDate": { "type": "string", "format": "date-time" }, "amount": { "type": "number" }, "method": { "type": "string" }, "type": { "type": "string" }, "description": { "type": "string" } }, "additionalProperties": true } }, "meta": { "type": "object", "properties": { "totalPages": { "type": "integer" }, "totalItems": { "type": "integer" }, "itemsPerPage": { "type": "integer" }, "currentPage": { "type": "integer" } }, "additionalProperties": true } }, "additionalProperties": true }, "AccountingStatus": { "type": "object", "properties": { "status": { "type": "string", "enum": [ "NEEDS_REVIEW", "READY_TO_EXPORT", "EXPORTED" ], "description": "Accounting Module review status for this transaction, independent from the root-level auth/approval status field." } }, "additionalProperties": true } } }, "externalDocs": { "description": "Clara API documentation", "url": "https://developers.clara.team" } }