API LUMINOUS — Referencia v1

Formato: JSON (UTF-8) · Solo HTTPS, server-to-server. La base URL depende del ambiente de tu key:

Key	Ambiente	Base URL
`lum_test_…`	Sandbox (certificación del SII)	`https://pruebas.luminous.cl`
`lum_live_…`	Producción (validez tributaria real)	`https://luminous.cl`

Si usas una key en la base URL equivocada, la API responde 400 indicándote la correcta.

Autenticación

Todas las solicitudes llevan tu API key en el header:

Authorization: Bearer lum_test_XXXXXXXX   (sandbox → ambiente de certificación del SII)
Authorization: Bearer lum_live_XXXXXXXX   (producción)

La key se muestra una sola vez al crearla — guárdala en un gestor de secretos. Nunca la incluyas en código cliente (apps móviles, JS de navegador).
Cada key tiene scopes (dte:emitir, dte:leer, pdf:leer), límite de solicitudes por minuto y cuota mensual de emisión según tu plan.
Verifica tus credenciales con GET /api/public/v1/ping.

Endpoints

Endpoint	Scope	Descripción
GET`/api/public/v1/ping`	—	Verifica la key: app, ambiente, scopes, plan
POST`/api/public/v1/dte/emitir`	dte:emitir	Crea, firma y envía un DTE al SII
GET`/api/public/v1/dte/{tipo}/{folio}`	dte:leer	Estado, track ID y montos del documento
GET`/api/public/v1/dte/{tipo}/{folio}/pdf?copia=`	pdf:leer	PDF (`original` \| `cedible` \| `ambas`)
GET`/api/public/v1/dte/{tipo}/{folio}/xml`	dte:leer	XML firmado (ISO-8859-1)

Emitir un DTE

Header obligatorio: Idempotency-Key (8–120 caracteres, único por emisión — por ejemplo el ID de tu pedido). Si reintentas con la misma key de idempotencia, recibes la misma respuesta y no se emite un segundo documento.

Tipos soportados

tipo_dte	Documento	Notas
33	Factura electrónica	Afecta (IVA 19%). Receptor con dirección/comuna.
34	Factura exenta	Ítems exentos automáticamente.
39 / 41	Boleta electrónica (afecta / exenta)	Precio de la boleta afecta es BRUTO (IVA incluido).
46	Factura de compra	Retención total de IVA (cambio de sujeto) automática.
52	Guía de despacho	Enviar `ind_traslado` (1=venta, 5=traslado interno…) y opcional `tipo_despacho`.
56 / 61	Nota de débito / crédito	Requieren `referencias` al documento que modifican.

Request

POST /api/public/v1/dte/emitir
Authorization: Bearer lum_test_XXXX
Idempotency-Key: pedido-8841-factura
Content-Type: application/json

{
  "tipo_dte": 33,
  "receptor": {
    "rut": "77043599-4",
    "razon_social": "Techmell SpA",
    "giro": "Venta de bicicletas",
    "direccion": "Rio Claro 8300",
    "comuna": "Pudahuel",
    "ciudad": "Santiago"
  },
  "items": [
    {"nombre": "Bicicleta MTB 29", "cantidad": 1, "precio_unitario": 350000},
    {"nombre": "Casco", "cantidad": 2, "precio_unitario": 25000, "descuento_pct": 10}
  ],
  "forma_pago": 1,
  "enviar": true
}

Campos opcionales: fecha_emision (AAAA-MM-DD), referencias (lista de {tipo_doc_ref, folio_ref, fecha_ref, cod_ref, razon_ref}; cod_ref 1=anula, 2=corrige texto, 3=modifica monto), enviar (default true; con false el documento queda firmado sin enviar).

Respuesta

{
  "exito": true,
  "datos": {
    "documento_id": 812,
    "tipo_dte": 33,
    "folio": 128,
    "ambiente": "CERT",
    "totales": {"monto_neto": 395000, "monto_iva": 75050, "monto_total": 470050},
    "enviado": true,
    "track_id": "0252583311"
  },
  "mensaje": "Documento emitido."
}

Códigos de error

HTTP	Significado
400	Solicitud inválida (falta Idempotency-Key, tipo no soportado, ítems mal formados)
401	API key ausente, inválida o revocada
402	Cuota mensual de documentos agotada — sube de plan
403	La key no tiene el scope requerido
404	Documento no encontrado (de tu empresa y ambiente)
422	El documento no pudo crearse (validación tributaria: folios agotados, receptor incompleto…) — el mensaje indica la causa
429	Rate limit por minuto excedido, o demasiados intentos de autenticación fallidos
5xx	Error interno — reintenta con la MISMA Idempotency-Key (no duplica el documento)

Buenas prácticas

Idempotencia siempre: usa el ID de tu operación (pedido, venta) como Idempotency-Key y reintenta con backoff ante 5xx/timeouts.
Integra primero en sandbox (lum_test_): opera contra el ambiente de certificación real del SII, con folios y certificado de prueba.
Consulta el estado después de emitir: el SII procesa asincrónicamente (estados: EMITIDO_LOCAL → RECIBIDO_SII → ACEPTADO_SII / RECHAZADO_SII).
No expongas la key en clientes: llama a la API desde tu backend.

Pasar a producción

Para emitir con validez tributaria tu empresa necesita: certificado digital vigente, folios CAF cargados, configuración SII (resolución) y la certificación ante el SII — nuestro equipo la hace contigo usando el módulo de certificación asistida de LUMINOUS. Al completarla, te entregamos tu key lum_live_. Solicita tu acceso aquí.