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

# Países y capacidades (v2)

> Consulta qué documentos, impuestos, medios de pago y reglas tiene cada país, y envía los datos propios de cada país en country_data

**Permiso requerido:** `countries` (para `GET /countries/{code}`). Enviar `country_data` en una venta solo requiere `sales`.

Cada país tiene sus propios tipos de documento, impuestos y formas de pago, y cada sistema fiscal pide datos distintos. Este endpoint le dice a su integración **qué existe y qué se exige** en un país, para que arme sus formularios y valide antes de emitir, sin tener código específico por país.

## Consultar un país

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

`{code}` es el código ISO de dos letras del país (`SV`, `GT`, `US`). Devuelve el catálogo del país **para el negocio de su integración** (por ejemplo, la moneda base del negocio).

```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": { "…": "…" }
    }
  }
}
```

| Campo | Descripción |
| - | - |
| `legal_currency` | Moneda en la que se emite el documento electrónico del país. |
| `base_currency_of_business` | Moneda base de su negocio. Si difiere de la legal, no se pueden emitir documentos electrónicos en moneda extranjera. |
| `document_types[].code` | Valor para `document_type` al crear una venta. |
| `document_types[].requires` | Campos obligatorios de ese tipo de documento, con la ruta en el cuerpo de la solicitud. |
| `taxes[]` | Impuestos del país. Tienen `percent` (porcentuales) o `value` (monto fijo por unidad, en moneda base). Los `id` son los que usa `tax_ids`. |
| `tax_rules[]` | Resumen de retenciones y renta que se aplican automáticamente. No incluye las condiciones que dependen del cliente. |
| `payment_methods[]` | Formas de pago del país, con su `id`: es el valor de `payment_details[].payment_method_id` en las ventas. Vacío si el país no tiene catálogo propio. |
| `identification_types[]` | Tipos de identificación de clientes y proveedores. Hoy vacío: se guardan como texto libre. |
| `adapter` | Cómo se comporta la emisión en ese país (ver abajo). |

### `adapter`

| Campo | Significado |
| - | - |
| `signs` | El país exige firma electrónica del documento. |
| `async` | El resultado de la emisión llega después (hoy `false` en todos). |
| `void_mode` | Cómo se anula un documento: `invalidate` (invalidación con motivo, El Salvador), `cancel` (anulación o cancelación simple), `credit_note_only` (solo con nota de crédito) o `none`. |
| `supports_draft` | Una emisión rechazada queda guardada como borrador para corregirla y retransmitirla. |
| `supports_skip_transmission` | Permite registrar el documento sin transmitirlo. |
| `country_data_schema` | Campos propios del país que acepta `country_data`, por tipo de documento. |

### Errores

| `code` | HTTP | Cuándo |
| - | - | - |
| `country_not_supported` | `404` | No hay emisión configurada para ese país. |
| — | `403` | La integración no tiene el permiso `countries` (la respuesta trae `required_scope`). |
| — | `401` | Falta la API Key. |

## `country_data`: los datos propios de un país

Los campos que solo existen en un país van dentro de `country_data` en `POST /sales`. Cada país define su estructura, que usted obtiene en `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": [ … ]
}
```

* Se valida **antes de transmitir**: si algo no cumple, no se crea la venta ni se consume un número de documento.
* Para Guatemala, `gt` se sigue aceptando como sinónimo de `country_data`. Si envía los dos, manda `country_data`.
* Solo se valida con facturación electrónica activa, porque sin ella el país no usa esos campos.

| `code` | HTTP | Cuándo |
| - | - | - |
| `country_data_invalid` | `422` | El objeto no cumple las reglas del país. `errors` indica cada campo, por ejemplo `country_data.periodos`. |
| `validation_error` | `422` | `country_data` no es un objeto. |

Los tipos de documento válidos en v2 son los del país de la sucursal (por ejemplo `fact`, `fcam` y `nev` en Guatemala), no la lista fija de v1.


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