code estable que tu integración puede evaluar sin leer el texto del mensaje.
URL base
X-API-Key) y los mismos permisos que v1, más el permiso nuevo currencies. La autenticación, el límite de peticiones y el alcance por negocio son idénticos.
v2 no reemplaza a v1: solo expone los endpoints que cambian. Todo lo demás (clientes, proveedores, productos, inventario, RRHH, contabilidad, cuentas por cobrar y pagar, etc.) sigue únicamente en
/api/external/v1. Una integración puede usar v1 y v2 a la vez con la misma API Key.Endpoints disponibles
El permiso
currencies se asigna en Integraciones externas, igual que sales y expenses: una integración con acceso total (heredado) ya lo incluye; una con permisos seleccionados debe tenerlo marcado. Si llamas a un endpoint de monedas sin él, recibes 403 con required_scope: "currencies".
Qué cambia respecto a v1
Dentro de v2 el resto del contrato (campos de la venta y la compra, totales, centros de costo, punto de venta, etc.) es el mismo que en v1: consulta Ventas y Compras para los campos que no cambian.
Cómo funciona la moneda
1
El negocio tiene una moneda base
Es la moneda en la que FileXpress guarda y contabiliza todo. Consúltala con
GET /currencies (base_currency_code).2
Envías el documento en su moneda
Pasas
currency_code (por ejemplo GTQ) y todos los montos del documento (líneas, impuestos, pagos y totales) en esa moneda. Si omites currency_code o envías la moneda base, el documento se trata como en v1.3
El servidor convierte a la moneda base
Aplica la tasa del documento (
exchange_rate enviada, o la vigente a la fecha del documento), valida los impuestos y emite. El documento electrónico (DTE) sale en la moneda legal del país, siempre en moneda base.0.128 para GTQ, 1 GTQ = 0.128 USD y 1,000 GTQ = 128.00 USD.
Errores y códigos
Toda respuesta de error de v2 sigue este formato:errors es opcional y su forma depende del error: un objeto campo → mensaje(s) en validación y monedas, o una lista de objetos { field, code, message, tax_id? } en tax_invalid. Evalúa siempre code; el texto de message puede cambiar.
Las respuestas que genera la propia capa de acceso antes de llegar al endpoint (API Key ausente o inválida, integración desactivada, permiso faltante, límite de peticiones) y el
404 de un recurso que pertenece a otro negocio (por ejemplo, GET /sales/{id} con un id ajeno) mantienen el formato { "status": false, "message": ... } y pueden no incluir code. Si falta code, usa el código HTTP (401, 403, 404, 429) como respaldo. El 403 por permiso faltante agrega required_scope.Siguientes pasos
Monedas y tasas
Consulta monedas activas y tasas.
Ventas
Emite ventas en moneda extranjera.
Compras
Registra compras en moneda extranjera.