Quickstart

Tiempo estimado: 15 minutos.

Paso 1 — Confirmación de conectividad


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

Respuesta esperada:


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

Importante: Si esta llamada falla, deben revisarse el firewall, el DNS y la conectividad. No debe continuarse hasta obtener 200 OK en este paso.

Paso 2 — Configuración de la variable de entorno


export LXS_API_KEY="lxs_live_a1b2c3d4_0011223344556677889900aabbccddeeff00112233445566"

La key nunca debe incluirse en el control de versiones. Debe utilizarse .env, Secret Manager, Vault o el gestor de secretos del proveedor cloud correspondiente.

Paso 3 — Verificación de la API key


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

Respuesta esperada:


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

Respuesta	Significado	Acción
`200` con `proximo`	Correcto	Puede continuarse
`401 Unauthorized`	Key inválida o malformada	Debe verificarse que esté completa y sin espacios
`403 Forbidden`	Falta scope `facturas:read`	Debe solicitarse al administrador la adición del scope

Paso 4 — Emisión de una factura

idUsuario es obligatorio. Es el id del usuario del tenant al que se atribuye el comprobante en los reportes del POS — normalmente un usuario dedicado a la integración. Lo proporciona el administrador del sistema junto con la API key. No es el mismo número que 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

Respuesta 201 Created:


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

La clave debe almacenarse: es el identificador único para consultas futuras.

Paso 5 — Espera del resultado de Hacienda

Opción A — Polling (no recomendado en producción):


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

La consulta debe repetirse cada 30 s hasta que el estado sea "aceptado" o "rechazado".

Opción B — Webhook (recomendado): el administrador configuró un webhookUrl al crear la key. Hacienda suele responder entre 30 y 180 segundos. El endpoint del integrador recibirá una llamada POST automática en cuanto llegue el resultado.

Paso 6 — Descarga del PDF y del 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"

Proceso completado. Con esto se ha emitido el primer comprobante electrónico legalmente válido en Costa Rica.