> ## Documentation Index > Fetch the complete documentation index at: https://docs.filexpress.app/llms.txt > Use this file to discover all available pages before exploring further. # Register purchase (v2) > Same as `POST /expenses` in v1, plus currency (`currency_code`, `exchange_rate`) and `tax_ids` required per line (they must exist). Saving purchases **does not recalculate taxes**: it stores what the client sends (converted to base if a currency is given). `data.total` repeats the `expenseTotalToPayment` sent (in the document's currency). Accepts the optional `Idempotency-Key` header to retry without duplicating the document (see the parameter). **Required permission:** `expenses` ## OpenAPI ````yaml /api-reference/openapi.en.json post /v2/expenses openapi: 3.0.3 info: title: FileXpress External API version: 1.0.0 description: >- API for integrating third-party systems with FileXpress: billing, HR, accounting, inventory, projects, accounts receivable and payable, treasury, pricing and promotions, and cash. Current base URL: /api/external/v1. The legacy unversioned path (/api/external) will be removed on January 1, 2027; migrate to /api/external/v1 (same endpoints, only the base URL changes). The v2 API (/api/external/v2) exposes currencies and exchange rates, sales and purchases in foreign currency, taxes by id, payrolls with branch, and errors with a stable `code`; its operations carry the /v2 prefix in the path. We suggest migrating to the available v2 routes before March 30, 2027. servers: - url: https://api.filexpress.app/api/external/v1 description: Production security: - ApiKey: [] tags: - name: General - name: Billing · Sales - name: Billing · Purchases - name: Billing · Customers - name: Billing · Suppliers - name: Billing · Products - name: Catalogs - name: HR · Employees - name: HR · Attendance - name: HR · Labor rules - name: HR · Schedules - name: HR · Holidays - name: HR · Attendance results - name: HR · Leave requests - name: HR · Payrolls - name: Accounting - name: Inventory - name: Projects - name: Accounts receivable - name: Accounts payable - name: Treasury - name: Pricing and promotions - name: Cash - name: Points of sale - name: API v2 · General - name: API v2 · Currencies and rates - name: API v2 · Countries - name: API v2 · Sales - name: API v2 · Purchases - name: API v2 · Payrolls paths: /v2/expenses: post: tags: - API v2 · Purchases summary: Register purchase (v2) description: >- Same as `POST /expenses` in v1, plus currency (`currency_code`, `exchange_rate`) and `tax_ids` required per line (they must exist). Saving purchases **does not recalculate taxes**: it stores what the client sends (converted to base if a currency is given). `data.total` repeats the `expenseTotalToPayment` sent (in the document's currency). Accepts the optional `Idempotency-Key` header to retry without duplicating the document (see the parameter). **Required permission:** `expenses` parameters: - $ref: '#/components/parameters/V2IdempotencyKey' requestBody: required: true content: application/json: schema: $ref: '#/components/schemas/V2ExpenseRequest' example: branch_id: 9d1c5a3e-4b7f-4e2a-9c1d-2f6b8a0e7c11 provider_id: 3b8e2f10-7c4d-4a9e-b1f2-5d6c7e8f9a01 document_type: ccf date: '2026-10-21T10:00:00' is_credit: true credit_days: 30 number_control: DTE-03-M001P001-000000000000123 generation_code: A1B2C3D4-5E6F-4A7B-8C9D-0E1F2A3B4C5D currency_code: GTQ exchange_rate: 0.128 products: - sku: COM-001 name: Diésel type: goods quantity: 5 price_before_taxes: 100 expense_taxed: 500 expense_exent: 0 expense_not_suject: 0 subtotal: 500 tax_ids: - 3b8e2f10-7c4d-4a9e-b1f2-5d6c7e8f9a01 - 5d7e9f10-2a3b-4c5d-8e6f-7a8b9c0d1e2f - sku: COM-002 name: Gasolina type: goods quantity: 5 price_before_taxes: 50 expense_taxed: 250 expense_exent: 0 expense_not_suject: 0 subtotal: 250 tax_ids: - 3b8e2f10-7c4d-4a9e-b1f2-5d6c7e8f9a01 - 8c1d2e3f-4a5b-4c6d-9e7f-0a1b2c3d4e5f - sku: SRV-010 name: Servicio exento type: services quantity: 1 price_before_taxes: 125 expense_taxed: 0 expense_exent: 125 expense_not_suject: 0 subtotal: 125 tax_ids: [] - sku: SRV-011 name: Servicio no sujeto type: services quantity: 1 price_before_taxes: 62.5 expense_taxed: 0 expense_exent: 0 expense_not_suject: 62.5 subtotal: 62.5 tax_ids: [] totals: netTotals: 937.5 charge_1: 15.63 charge_2: 7.81 expenseTotalTax: 750 expenseTotalExent: 125 expenseTotalNotSuject: 62.5 totalTax: 97.5 totalRetein: 7.5 totalRent: 10 expenseTotalToPayment: 1040.94 responses: '200': description: Purchase registered content: application/json: example: status: true message: Expense created successfully data: expense_id: 9d1c5a3e-4b7f-4e2a-9c1d-2f6b8a0e7c11 generation_code: A1B2C3D4-5E6F-4A7B-8C9D-0E1F2A3B4C5D control_number: DTE-03-M001P001-000000000000123 status: processed issue_time: '2026-10-21 10:00:00' total: 1040.94 currency_code: GTQ exchange_rate: '0.12800000' foreign_total: '1040.94' base_currency_code: USD headers: Idempotent-Replay: $ref: '#/components/headers/IdempotentReplay' '401': $ref: '#/components/responses/E401' '403': $ref: '#/components/responses/E403' '409': description: >- Another request with the same `Idempotency-Key` is still in progress. Wait and retry with the same key. content: application/json: schema: $ref: '#/components/schemas/V2Error' example: status: false code: idempotency_in_progress message: Hay otra solicitud en curso con la misma Idempotency-Key. '422': description: Validation, currency or idempotency error content: application/json: schema: $ref: '#/components/schemas/V2Error' examples: currency_not_enabled: summary: Moneda no activa value: status: false code: currency_not_enabled message: La moneda GTQ no está activa para este negocio. errors: currency_code: La moneda GTQ no está activa. exchange_rate_not_found: summary: Sin tasa vigente value: status: false code: exchange_rate_not_found message: >- No hay tasa de cambio para GTQ a la fecha 2026-10-21 ni anterior. Registre una tasa de cambio o envíe exchange_rate en el documento. errors: exchange_rate: Sin tasa de cambio para GTQ al 2026-10-21. validation_error: summary: Falta tax_ids o el id no existe value: status: false code: validation_error message: Validation errors errors: products.0.tax_ids: - The products.0.tax_ids field must be present. idempotency_key_reused: summary: Idempotency-Key usada con otro cuerpo value: status: false code: idempotency_key_reused message: La Idempotency-Key ya se usó con una solicitud distinta. idempotency_key_too_long: summary: Idempotency-Key de más de 120 caracteres value: status: false code: validation_error message: Validation errors errors: Idempotency-Key: - Máximo 120 caracteres. headers: Idempotent-Replay: $ref: '#/components/headers/IdempotentReplay' '429': $ref: '#/components/responses/E429' '500': $ref: '#/components/responses/E500' servers: - url: https://api.filexpress.app/api/external description: Production (v2 routes are prefixed with /v2) components: parameters: V2IdempotencyKey: name: Idempotency-Key in: header required: false description: >- Optional. Unique key per operation (max. 120 characters; more than 120 returns 422 `validation_error`). Valid for 24 h per integration. A retry with the same key and the same body returns the original response (same code and body) with the header `Idempotent-Replay: true`, without issuing again. With a different body or endpoint it returns 422 `idempotency_key_reused`; while the first request is still in progress, 409 `idempotency_in_progress`. Only 2xx and 422 responses are stored; a 5xx, 401, 403, 404 or 429 error is not stored and can be retried with the same key. schema: type: string maxLength: 120 example: venta-2026-10-21-000123 schemas: V2ExpenseRequest: type: object properties: branch_id: type: string format: uuid description: Branch. provider_id: type: string format: uuid description: Supplier. document_type: type: string description: Document type. enum: - ccf - fse - ticket date: type: string format: date description: Date. is_credit: type: boolean description: On credit. credit_days: type: integer description: Credit days. observation: type: string description: Notes. number_control: type: string description: DTE control number. generation_code: type: string description: Generation code. stamp: type: string description: Stamp. cost_center_id: type: string format: uuid description: >- Cost center of the purchase (leaf and active; GET /accounting/cost-centers). products: type: array items: type: object properties: sku: type: string name: type: string type: type: string description: Good or service. enum: - goods - services quantity: type: number price_before_taxes: type: number expense_not_suject: type: number expense_exent: type: number expense_taxed: type: number subtotal: type: number cost_center_id: type: string format: uuid description: >- Cost center of the line; if missing, that of the purchase. The expense is grouped by account and center. cost_center_distribution_id: type: string format: uuid nullable: true description: >- Distribution of the line; if the line has neither a center nor a distribution, the purchase's is used. Mutually exclusive with `cost_center_id` at the same level (422 `Indique centro de costo o distribución, no ambos.`). tax_ids: type: array items: type: string format: uuid description: >- Tax IDs of the line (they must exist). Required: the key must be present; it may be []. taxability: type: string description: Calculated mode only. Treatment of the line. enum: - taxed - exempt - not_subject discount_percent: type: number minimum: 0 maximum: 1 description: >- Calculated mode only. Discount as a fraction (0.10 = 10 %). Do not combine with `discount`. required: - sku - name - type - quantity - price_before_taxes - tax_ids totals: type: object properties: netTotals: type: number charge_1: type: number charge_2: type: number expenseTotalTax: type: number totalRent: type: number totalTax: type: number totalRetein: type: number expenseTotalToPayment: type: number expenseTotalExent: type: number description: Exempt total (optional; 0 if omitted). expenseTotalNotSuject: type: number description: Not-subject total (optional; 0 if omitted). description: >- Calculated mode: if `totals.expenseTotalToPayment` is omitted, the server calculates line amounts, VAT (IVA), fixed charges and total; `totalRetein` and `totalRent` are sent by you. cost_center_distribution_id: type: string format: uuid nullable: true description: >- Active distribution: the expense is split among its centers by percentage. Mutually exclusive with `cost_center_id` at the same level (422 `Indique centro de costo o distribución, no ambos.`). currency_code: type: string minLength: 3 maxLength: 3 description: >- Document currency (3 letters, for example GTQ). Must be active for the business (GET /v2/currencies). If omitted or equal to the base currency, the document is in base currency. All amounts are in this currency. exchange_rate: type: number exclusiveMinimum: true minimum: 0 description: >- Units of base currency per 1 unit of `currency_code`. If omitted, the rate in effect on the document date is used. required: - branch_id - provider_id - document_type - date - is_credit - products V2Error: type: object properties: status: type: boolean example: false code: type: string description: >- Stable error code. Evaluate this field instead of the `message` text. Responses from the access layer (API Key, permission, rate limit) and the 404 for a resource of another business may not include it: use the HTTP code. enum: - currency_not_enabled - exchange_rate_not_found - exchange_rate_invalid - base_currency_not_legal - validation_error - tax_invalid - payment_method_invalid - tax_not_supported_in_expenses - country_not_supported - country_data_invalid - idempotency_key_reused - idempotency_in_progress - unauthorized - forbidden - not_found - rate_limited - error message: type: string errors: oneOf: - type: object additionalProperties: true description: Field -> message(s) (validation and currency). - type: array description: 'Only in `tax_invalid`: one entry per tax problem.' items: type: object properties: field: type: string code: type: string description: Detail of the tax problem. enum: - tax_not_found - tax_wrong_effect - tax_country_mismatch - tax_not_in_lines - tax_totals_inconsistent - tax_amount_mismatch - withholding_totals_inconsistent - withholding_amount_mismatch message: type: string tax_id: type: string format: uuid required: - field - code - message description: Optional. Its shape depends on the error. required: - status - message headers: IdempotentReplay: description: >- `true` when the response is the exact replay (same code and body) of a previous request with the same Idempotency-Key. API v2. schema: type: string enum: - 'true' responses: E401: description: Missing or invalid API Key content: application/json: example: status: false message: Invalid API Key. E403: description: Integration without the required permission or deactivated content: application/json: example: status: false message: This integration does not have the 'hr.employees' permission. required_scope: hr.employees E429: description: Rate limit exceeded content: application/json: example: status: false message: Rate limit exceeded. Please try again later. rate_limit: 100 E500: description: Internal error content: application/json: example: status: false message: An error occurred while creating the invoice securitySchemes: ApiKey: type: apiKey in: header name: X-API-Key description: Integration API Key (Integrations → New Integration). ```` This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.