Changelog

v1.5 — 2026-08-06 (current state)

moneda in responses is now the ISO code ("CRC" / "USD"), as it was always documented and as it is sent when issuing. Previously the internal code was returned ("01" / "02"): an integrator would send "CRC" and receive "02". If the integrator’s code compared against "01"/"02", it must be updated to "CRC"/"USD".

GET /api/v1/facturas/{clave}/respuesta — the XML acknowledgment signed by Hacienda, which was already stored but could not be downloaded. Also available for purchase invoices.
GET /api/v1/facturas-compra/{clave}/xml — did not exist; only the PDF was available.

Credit and debit notes could not be retrieved. The API issued them, but GET /facturas/{clave}, /pdf, and /xml responded 404: the lookup by key only queried the invoice and ticket tables. It now resolves all four types.

Receiver message: POST /api/v1/mensajes-receptor and GET /api/v1/mensajes-receptor/{clave}. Accept, partially accept, or reject a supplier’s electronic invoice before Hacienda. New scopes: mensajes:write and mensajes:read.

The receiver message was sent to Hacienda with an empty consecutive number. When the procedure was migrated to PostgreSQL, the INSERT stopped writing numero_consecutivo, the field that travels as NumeroConsecutivoReceptor in the signed XML. It had been affecting the POS since then; it was fixed across all 16 tenants before the flow was exposed via API.

Product catalog: POST /api/v1/productos (upsert by the integrator’s own codigo) and GET /api/v1/productos/{codigo}.
Customer catalog: POST /api/v1/clientes (upsert by identificacion, with partial updates) and GET /api/v1/clientes/{identificacion}.
Code catalogs: GET /api/v1/catalogos/{medios-pago, condiciones-venta, unidades-medida, actividades, puntos-venta, tipos-codigo, marcas}. Economic activities, points of sale, and brands are tenant-specific, and there was previously no way to query them without requesting them from LX Systems.
Brand creation: POST /api/v1/marcas, upsert by name.
Two new scopes: catalogo:write and catalogo:read. See Scopes.
idPuntoVenta optional when issuing, both for sales and purchase invoices: sets which stock the sale is deducted from and which branch or terminal carries the consecutive number and key. Omitting it keeps the v1.2 behavior.

In-memory caches were keyed by hostname. In the POS each tenant enters through its own subdomain, but in the API all of them enter through api.pos.lxsyscr.com, so two tenants shared the same cache entry: a product resolved by codigoProducto — with its name, price, and CABYS — could cross over from one tenant to another and end up on a fiscal document that wasn’t its own. This never happened in production (only one key had been issued) and was fixed before a second one existed.
POST /api/v1/productos on an existing code would respond with the product without the changes just applied for about 30 seconds, even though the database was already correct. An immediate issuance by codigoProducto would also pick up the previous price.
A nonexistent idMarca, idProveedor, or tipoCodigo when saving a product responded with "No se pudo guardar el producto.", without saying which field was wrong. Now all three are validated beforehand and the error names the field and where to look up valid values.

Issuing NC/ND now requires the notas:write scope. Previously facturas:write was enough. A key with facturas:write but without notas:write still issues FE and TE without issue, but receives 403 when sending tipo: "NotaCredito" or "NotaDebito". The rationale for this separation is detailed in Scopes.

Purchase electronic invoice (type 08) — the self-billed invoice issued on behalf of a special-regime supplier. Three new endpoints: POST /api/v1/facturas-compra, GET /api/v1/facturas-compra/{clave}, and /pdf. Two new scopes: facturas-compra:write and facturas-compra:read.
The scope catalog is now served as data instead of remaining hardcoded in the admin UI — the CRM consumes it directly from that source.

idUsuario is required in POST /api/v1/facturas. It identifies the tenant user the document is attributed to in POS reports. A request without it responds 400.

Customer by ID number (cliente.identificacion), with automatic creation if it doesn’t exist: it is no longer necessary to sync internal ids before invoicing. See FacturaApiClienteDto.
Product by catalog code (linea.codigoProducto) as an alternative to idProducto. See FacturaApiLineaDto.
Final base URL: https://api.pos.lxsyscr.com
tipo accepts both the name ("FacturaElectronica") and the numeric code.

Documents issued through the API were not being sent to Hacienda: they were persisted with a key and consecutive number, but the XML was never generated or signed. Issuance now queues the submission and the final status arrives via webhook as documented.
A failed issuance could respond 201 with an empty clave. It now responds 400.