> ## 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.

# Countries and capabilities (v2)

> Find out which documents, taxes, payment methods, and rules each country has, and send each country's own data in country_data

**Required permission:** `countries` (for `GET /countries/{code}`). Sending `country_data` in a sale only requires `sales`.

Each country has its own document types, taxes, and payment methods, and each tax system asks for different data. This endpoint tells your integration **what exists and what is required** in a country, so you can build your forms and validate before issuing, without country-specific code.

## Get a country

```http theme={null}
GET /countries/{code}
```

`{code}` is the country's two-letter ISO code (`SV`, `GT`, `US`). It returns the country catalog **for your integration's business** (for example, the business's base currency).

```json theme={null}
{
  "status": true,
  "data": {
    "country_code": "GT",
    "name": "Guatemala",
    "legal_currency": "GTQ",
    "base_currency_of_business": "GTQ",
    "timezone": "America/Guatemala",
    "document_types": [
      { "code": "fact", "name": "Factura", "number_code": "FACT", "applicable_to": "sales", "requires": [] },
      { "code": "ncre", "name": "Nota de crédito", "number_code": "NCRE", "applicable_to": "sales", "requires": ["related_documents.0.number"] },
      { "code": "nev",  "name": "Nota de envío",   "number_code": "NEV",  "applicable_to": "sales", "requires": ["country_data.traslado.placa", "…"] }
    ],
    "payment_methods": [],
    "taxes": [
      { "id": "…", "name": "IVA", "number_code": "20", "tax_type": "percentage", "percent": 0.12, "effect": "add" }
    ],
    "tax_rules": [
      { "code": "…", "name": "…", "tax_id": "…", "applies_to": "sales", "effect": "retention", "rate": 0.01, "base": "tax_exclusive", "scope": "header", "document_types": ["fact"] }
    ],
    "identification_types": [],
    "adapter": {
      "signs": false,
      "async": false,
      "void_mode": "cancel",
      "supports_draft": false,
      "supports_skip_transmission": false,
      "country_data_schema": { "…": "…" }
    }
  }
}
```

| Field | Description |
| - | - |
| `legal_currency` | Currency in which the country's electronic document is issued. |
| `base_currency_of_business` | Your business's base currency. If it differs from the legal currency, electronic documents cannot be issued in a foreign currency. |
| `document_types[].code` | Value for `document_type` when creating a sale. |
| `document_types[].requires` | Required fields for that document type, with the path in the request body. |
| `taxes[]` | The country's taxes. They have `percent` (percentage-based) or `value` (fixed amount per unit, in base currency). The `id` values are the ones used by `tax_ids`. |
| `tax_rules[]` | Summary of withholdings and income tax that are applied automatically. It does not include conditions that depend on the customer. |
| `payment_methods[]` | The country's payment methods, with their `id`: it is the value of `payment_details[].payment_method_id` in sales. Empty if the country has no catalog of its own. |
| `identification_types[]` | Identification types for customers and suppliers. Currently empty: they are stored as free text. |
| `adapter` | How issuing behaves in that country (see below). |

### `adapter`

| Field | Meaning |
| - | - |
| `signs` | The country requires an electronic signature on the document. |
| `async` | The issuing result arrives later (currently `false` for all). |
| `void_mode` | How a document is voided: `invalidate` (invalidation with a reason, El Salvador), `cancel` (simple voiding or cancellation), `credit_note_only` (only with a credit note), or `none`. |
| `supports_draft` | A rejected issuance is saved as a draft so it can be corrected and retransmitted. |
| `supports_skip_transmission` | Allows recording the document without transmitting it. |
| `country_data_schema` | Country-specific fields that `country_data` accepts, by document type. |

### Errors

| `code` | HTTP | When |
| - | - | - |
| `country_not_supported` | `404` | No issuing is configured for that country. |
| — | `403` | The integration does not have the `countries` permission (the response includes `required_scope`). |
| — | `401` | The API Key is missing. |

## `country_data`: a country's own data

Fields that exist only in one country go inside `country_data` in `POST /sales`. Each country defines its own structure, which you get from `adapter.country_data_schema`.

```json theme={null}
{
  "branch_id": "…",
  "customer_id": "…",
  "document_type": "fcam",
  "date": "2026-10-23T10:00:00",
  "country_data": { "periodos": 3, "abono": 100.00, "fecha_fin": "2026-12-31" },
  "products": [ … ]
}
```

* It is validated **before transmitting**: if anything fails, the sale is not created and no document number is consumed.
* For Guatemala, `gt` is still accepted as a synonym of `country_data`. If you send both, `country_data` wins.
* It is only validated with electronic invoicing active, because without it the country does not use those fields.

| `code` | HTTP | When |
| - | - | - |
| `country_data_invalid` | `422` | The object does not meet the country's rules. `errors` indicates each field, for example `country_data.periodos`. |
| `validation_error` | `422` | `country_data` is not an object. |

The valid document types in v2 are those of the branch's country (for example `fact`, `fcam`, and `nev` in Guatemala), not the fixed list from v1.


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.