Países y capacidades (v2)

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

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

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

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

Primeros Pasos

API v2

Facturación

Recursos Humanos

Contabilidad

Inventario

Proyectos

Cuentas por cobrar y pagar

Precios y promociones

Caja

Referencia interactiva

Países y capacidades (v2)

Consultar un país

`adapter`

Errores

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

​Consultar un país

​adapter

​Errores

​country_data: los datos propios de un país

Consultar un país

`adapter`

Errores

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