Countries and capabilities (v2)

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

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

{
  "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.

{
  "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.

Getting Started

API v2

Billing

Human Resources

Accounting

Inventory

Projects

Receivables & Payables

Pricing & Promotions

Cash

Interactive reference

Countries and capabilities (v2)

Get a country

`adapter`

Errors

`country_data`: a country’s own data

​Get a country

​adapter

​Errors

​country_data: a country’s own data

Get a country

`adapter`

Errors

`country_data`: a country’s own data