> ## 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. # Create sale (v2) > Same as `POST /sales` in v1, plus currency (`currency_code`, `exchange_rate`), `tax_ids` required per line, and strict tax validation (an amount different from the recalculated one returns 422 `tax_invalid`). Document amounts are in the currency of `currency_code`; the server converts them to the base currency and the DTE is issued in the country's legal currency. `data.total` is the total to pay in base currency and `foreign_total` is in the document's currency. Accepts the optional `Idempotency-Key` header to retry without duplicating the document (see the parameter). **Required permission:** `sales` ## OpenAPI ````yaml /api-reference/openapi.en.json post /v2/sales 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/sales: post: tags: - API v2 · Sales summary: Create sale (v2) description: >- Same as `POST /sales` in v1, plus currency (`currency_code`, `exchange_rate`), `tax_ids` required per line, and strict tax validation (an amount different from the recalculated one returns 422 `tax_invalid`). Document amounts are in the currency of `currency_code`; the server converts them to the base currency and the DTE is issued in the country's legal currency. `data.total` is the total to pay in base currency and `foreign_total` is in the document's currency. Accepts the optional `Idempotency-Key` header to retry without duplicating the document (see the parameter). **Required permission:** `sales` parameters: - $ref: '#/components/parameters/V2IdempotencyKey' requestBody: required: true content: application/json: schema: $ref: '#/components/schemas/V2SaleRequest' example: branch_id: 9d1c5a3e-4b7f-4e2a-9c1d-2f6b8a0e7c11 customer_id: 3b8e2f10-7c4d-4a9e-b1f2-5d6c7e8f9a01 document_type: ccf date: '2026-10-21T10:00:00' currency_code: GTQ exchange_rate: 0.128 payment_details: - payment_method_id: 9d1c5a3e-4b7f-4e2a-9c1d-2f6b8a0e7c11 amount: 863.13 products: - id: 9d1c5a3e-4b7f-4e2a-9c1d-2f6b8a0e7c11 name: Servicio de transporte quantity: 5 price_before_taxes: 100 discount: 0 subtotal: 500 sale_taxed: 500 sale_exent: 0 sale_not_suject: 0 tax_ids: - 3b8e2f10-7c4d-4a9e-b1f2-5d6c7e8f9a01 - 5d7e9f10-2a3b-4c5d-8e6f-7a8b9c0d1e2f - id: 9d1c5a3e-4b7f-4e2a-9c1d-2f6b8a0e7c11 name: Servicio de carga quantity: 5 price_before_taxes: 50 discount: 0 subtotal: 250 sale_taxed: 250 sale_exent: 0 sale_not_suject: 0 tax_ids: - 3b8e2f10-7c4d-4a9e-b1f2-5d6c7e8f9a01 - 5d7e9f10-2a3b-4c5d-8e6f-7a8b9c0d1e2f totals: netTotals: 750 saleTotalNotSuject: 0 saleTotalExent: 0 saleTotalTax: 750 totalTax: 97.5 totalRetein: 0 totalRent: 0 saleTotalToPayment: 863.13 taxes: - tax_id: 3b8e2f10-7c4d-4a9e-b1f2-5d6c7e8f9a01 amount: 97.5 - tax_id: 5d7e9f10-2a3b-4c5d-8e6f-7a8b9c0d1e2f amount: 15.63 withholdings: [] responses: '200': description: Document issued content: application/json: example: status: true message: Invoice created successfully data: sale_id: 9d1c5a3e-4b7f-4e2a-9c1d-2f6b8a0e7c11 generation_code: 6F1E2D3C-8A4B-4C5D-9E6F-0A1B2C3D4E5F control_number: DTE-03-M001P001-000000000000045 status: PROCESADO issue_time: '2026-10-21 10:00:00' stamp: 2026A1B2C3D4E5F6 point_of_sale_id: 9d1c5a3e-4b7f-4e2a-9c1d-2f6b8a0e7c11 establishment_code: M001 point_of_sale_code: P001 total: 110.48 currency_code: GTQ exchange_rate: '0.12800000' foreign_total: '863.13' 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, tax or idempotency error content: application/json: schema: $ref: '#/components/schemas/V2Error' examples: tax_invalid: summary: Impuestos distintos al recalculado value: status: false code: tax_invalid message: Impuestos inválidos errors: - field: invoiceResumenDetail.totalTax code: tax_amount_mismatch message: totalTax enviado (20) difiere del calculado (13). validation_error: summary: Falta tax_ids en una línea value: status: false code: validation_error message: Validation errors errors: products.0.tax_ids: - The products.0.tax_ids field must be present. 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. exchange_rate_invalid: summary: Tasa inválida value: status: false code: exchange_rate_invalid message: >- La tasa de cambio del documento debe ser un número mayor que cero. errors: exchange_rate: Debe ser mayor que cero. base_currency_not_legal: summary: Base distinta de la moneda legal value: status: false code: base_currency_not_legal message: >- El documento electrónico debe emitirse en GTQ (moneda legal de GT) y la moneda base del negocio es USD. Corrija la moneda base del negocio antes de emitir en moneda extranjera. errors: currency_code: La moneda base (USD) no es la moneda legal (GTQ). country_data_invalid: summary: country_data inválido para el país value: status: false code: country_data_invalid message: country_data inválido para GT errors: periodos: Debe ser un entero mayor o igual a 1. 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: V2SaleRequest: type: object properties: branch_id: type: string format: uuid description: Issuing branch (GET /branches). customer_id: type: string format: uuid description: Receiving customer. document_type: type: string description: 'SV: fc, ccf, fex, nc, nd, nr. US: inv, cm, dm.' enum: - fc - ccf - fex - nc - nd - nr - inv - cm - dm date: type: string description: 'ISO 8601 date and time. Default: now.' observation: type: string description: Notes. is_credit: type: boolean description: Credit sale. credit_days: type: integer description: Credit days. project_id: type: string format: uuid description: Associated project. point_of_sale_id: type: string format: uuid description: >- Issuing point of sale (of the branch and active). Default: the branch's default. cost_center_id: type: string format: uuid description: >- Cost center of the sale (leaf and active; GET /accounting/cost-centers). Applied to income lines when posting. incoterm_id: type: string format: uuid description: Incoterm (export). payment_details: type: array items: type: object properties: payment_method_id: type: string format: uuid description: >- Payment method id, from the country's catalog (`GET /v2/countries/{code}` → `payment_methods[].id`). Recommended: the code is not unique across countries. It must exist and be valid for the branch's country (`payment_method_invalid` otherwise). code: type: string description: >- Deprecated; fallback only if `payment_method_id` is not sent. It is resolved within the branch's country; if it does not exist, `payment_method_invalid`. amount: type: number description: Amount in the document's currency. reference: type: string description: Reference. required: - amount products: type: array items: type: object properties: id: type: string format: uuid description: Product in FileXpress (deducts inventory). sku: type: string description: Code. name: type: string description: Description. quantity: type: number description: Quantity. price_before_taxes: type: number description: Unit price before taxes. sale_not_suject: type: number description: Not subject. sale_exent: type: number description: Exempt. sale_taxed: type: number description: Taxable. subtotal: type: number description: Subtotal before taxes. discount: type: number description: Discount. type: type: string description: Good or service. enum: - phisical - service cost_center_id: type: string format: uuid description: Cost center of the line; if missing, that of the sale. 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 sale'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 (GET /taxes/branch/{id}). 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: - name - quantity - price_before_taxes - tax_ids totals: type: object properties: netTotals: type: number description: netTotals saleTotalNotSuject: type: number description: saleTotalNotSuject saleTotalExent: type: number description: saleTotalExent saleTotalTax: type: number description: saleTotalTax totalTax: type: number description: totalTax totalRetein: type: number description: totalRetein totalRent: type: number description: totalRent freight: type: number description: freight insurance: type: number description: insurance saleTotalToPayment: type: number description: saleTotalToPayment taxes: type: array items: type: object properties: tax_id: type: string format: uuid amount: type: number required: - tax_id - amount description: Taxes applied to the document, in the document's currency. withholdings: type: array items: type: object properties: tax_id: type: string format: uuid amount: type: number required: - tax_id - amount description: Withholdings and income tax applied, in the document's currency. description: >- Calculated mode: if `totals.saleTotalToPayment` is omitted, the server calculates line amounts, taxes, withholdings and totals; only quantity, price before taxes, discount and `tax_ids` are needed. Not available for `fc` (`totals_required`). cost_center_distribution_id: type: string format: uuid nullable: true description: >- Active distribution (GET /accounting/cost-center-distributions): income 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.`). country_data: type: object additionalProperties: true description: >- Country-specific fields of the branch's country for this document (for example, in Guatemala those of `fcam`, `nabn`, `ncre`, `ndeb` and `nev`). Must be an object, not a list. Its schema per document type is in `adapter.country_data_schema` of `GET /v2/countries/{code}`. It is validated before transmission, and only if the business has electronic invoicing active; an invalid field returns 422 `country_data_invalid`. In Guatemala the alias `gt` is also accepted; if both are sent, `country_data` prevails. El Salvador does not use `country_data`. 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 - customer_id - document_type - products - payment_details 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.