Quickstart

Estimated time: 15 minutes.

Step 1 — Confirm connectivity


curl -s https://api.pos.lxsyscr.com/health

Expected response:


{ "status": "healthy", "timestamp": "2026-05-15T15:30:00Z" }

Important: If this call fails, check your firewall, DNS, and connectivity. Do not continue until you get a 200 OK at this step.

Step 2 — Set the environment variable


export LXS_API_KEY="lxs_live_a1b2c3d4_0011223344556677889900aabbccddeeff00112233445566"

Never commit the key to version control. Use .env, Secret Manager, Vault, or your cloud provider’s secrets manager.

Step 3 — Verify the API key


curl -s https://api.pos.lxsyscr.com/api/v1/consecutivos/proximo?tipo=01 \
  -H "X-Api-Key: $LXS_API_KEY"

Expected response:


{ "tipo": "01", "proximo": 1234 }

Response	Meaning	Action
`200` with `proximo`	Success	You can continue
`401 Unauthorized`	Invalid or malformed key	Check that it is complete and has no extra spaces
`403 Forbidden`	Missing the `facturas:read` scope	Ask your administrator to add the scope

Step 4 — Issue an invoice

idUsuario is required. It is the id of the tenant user the document is attributed to in the POS reports — usually a user dedicated to the integration. Your system administrator provides it along with the API key. It is not the same number as idCliente.


curl -s -X POST https://api.pos.lxsyscr.com/api/v1/facturas \
  -H "X-Api-Key: $LXS_API_KEY" \
  -H "Content-Type: application/json" \
  -H "Idempotency-Key: $(uuidgen)" \
  -d '{
    "tipo": "FacturaElectronica",
    "idUsuario": 7,
    "cliente": { "idCliente": 42 },
    "condicionVenta": "01",
    "medioPago": "01",
    "moneda": "CRC",
    "lineas": [
      { "idProducto": 100, "cantidad": 2 }
    ]
  }' | jq

201 Created response:


{
  "clave": "50615012600310112345600100001010000000123456789012",
  "numeroConsecutivo": "00100001010000000123",
  "tipoDocumento": "01",
  "estadoHacienda": "procesando",
  "totalComprobante": 22600.00,
  "moneda": "CRC",
  "fechaEmision": "2026-05-15T15:32:11Z"
}

Store the clave: it is the unique identifier for future lookups.

Step 5 — Wait for the result from Hacienda

Option A — Polling (not recommended in production):


CLAVE="50615012600310112345600100001010000000123456789012"
curl -s https://api.pos.lxsyscr.com/api/v1/facturas/$CLAVE \
  -H "X-Api-Key: $LXS_API_KEY" | jq '.estadoHacienda'

Repeat the query every 30s until the status is "aceptado" or "rechazado".

Option B — Webhook (recommended): your administrator configured a webhookUrl when the key was created. Hacienda (Costa Rica’s tax authority) usually responds within 30 to 180 seconds. Your endpoint will receive an automatic POST call as soon as the result arrives.

Step 6 — Download the PDF and XML


curl -O -J https://api.pos.lxsyscr.com/api/v1/facturas/$CLAVE/pdf -H "X-Api-Key: $LXS_API_KEY"
curl -O -J https://api.pos.lxsyscr.com/api/v1/facturas/$CLAVE/xml -H "X-Api-Key: $LXS_API_KEY"

Done. You have now issued your first legally valid electronic tax document in Costa Rica.