Skip to Content
v1.0Documentación oficial de la API LX CloudPos · estable en producción
V1FundamentosQuickstart

Quickstart

⏱ Tiempo estimado: 15 minutos.

Paso 1 — Confirma conectividad

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

Respuesta esperada:

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

⚠ Si esto falla, revisa tu firewall, DNS o conectividad. No avances hasta tener 200 OK aquí.

Paso 2 — Configura la variable de entorno

export LXS_API_KEY="lxs_live_a1b2c3d4_0011223344556677889900aabbccddeeff00112233445566"

🔒 Nunca commitees la key. Usa .env, Secret Manager, Vault o el gestor de tu cloud.

Paso 3 — Verifica tu key

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

Respuesta esperada:

{ "tipo": "01", "proximo": 1234 }
RespuestaSignificadoAcción
200 con proximoTodo OKAvanza
401 UnauthorizedKey inválida o malformadaRevisa que esté completa y sin espacios
403 ForbiddenFalta scope facturas:readSolicita al admin agregar el scope

Paso 4 — Emite una factura

curl -s -X POST https://api.lxsyscr.com/api/v1/facturas \
  -H "X-Api-Key: $LXS_API_KEY" \
  -H "Content-Type: application/json" \
  -H "Idempotency-Key: $(uuidgen)" \
  -d '{
    "tipo": "FacturaElectronica",
    "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"
}

💡 Guarda la clave — es tu identificador único para consultas futuras.

Paso 5 — Espera el resultado de Hacienda

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

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

Repite cada 30 s hasta que el estado sea "aceptado" o "rechazado".

Opción B — Webhook (recomendado): el admin configuró un webhookUrl cuando creó tu key. Hacienda suele responder entre 30 y 180 segundos. Tu endpoint recibirá una llamada POST automática en cuanto llegue el resultado.

Paso 6 — Descarga el PDF y XML

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

🎉 Listo. Ya emitiste tu primer comprobante electrónico legalmente válido en Costa Rica.

PrerrequisitosEnum TipoComprobanteApi