API LUMINOUS — Referencia v1

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

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

Consultar boletas, facturación y compras

El detalle incorpora detalle_estado y ultima_consulta_sii (ISO con zona horaria, o null si no se registró). Compras diferencia ultimo_evento_sii de una consulta de estado. Puedes descargar el XML auténtico con GET /api/public/v1/consultas/{familia}/{id}/xml, usando el permiso de lectura de la familia. Se entrega solo el DTE seleccionado.

El portal de API ofrece pestañas de solo consulta, detalle y PDF. Tu programa puede acceder a los mismos datos mediante estas rutas de lectura. No emiten ni contabilizan documentos.

familia: boletas, facturacion o compras. Usa el id devuelto por el listado, no el folio. La empresa y el ambiente los determina la clave. Las claves existentes no reciben automáticamente el nuevo permiso de compras; se selecciona al crear la credencial en Staff.

Formato y logo de las boletas

El administrador puede guardar el formato predeterminado en API → Configuración de salida. La preferencia es de la empresa y se comparte entre pruebas y producción. Se usa su logo y colores cargados en Mi cuenta. Si no hay preferencia, se conserva voucher. Revisa la vista previa con tu logo y pulsa Guardar formato para aplicar tu elección.

En boletas (39 y 41), ambos endpoints de PDF aceptan ?formato=carta (hoja carta de 216 × 279 mm) o ?formato=voucher (80 mm). Por ejemplo: /api/public/v1/dte/39/123/pdf?formato=carta y /api/public/v1/consultas/boletas/456/pdf?formato=voucher. Sin el parámetro se usa la preferencia guardada. Un valor distinto devuelve 400.

La selección cambia solo la presentación del PDF, conservando el documento, XML, folio y timbre. No cambia el formato de facturas ni de documentos de proveedores. Si tu integración guarda una copia del PDF, debe volver a descargarlo para ver la nueva presentación.

Filtros: q (folio, RUT o nombre), tipo_dte, estado, desde y hasta (fecha de emisión en formato ISO AAAA-MM-DD). Paginación: page desde 1 y per_page entre 1 y 200, por defecto 50.

La respuesta contiene datos.documentos, total, resumen por estado, page, per_page y ambiente. El detalle añade lineas. Cada documento incluye tipo, folio, fecha de emisión, estado, RUT, razón social y montos neto, exento, IVA y total.

Las consultas respetan el límite de solicitudes y no suman emisiones facturables. El estado es el último registrado; consultar no envía solicitudes nuevas al SII. Un PDF de compra requiere el XML auténtico del proveedor: si falta, se devuelve 404 con una explicación, sin inventar detalle a partir del Registro de Compras.

Consultar tu consumo

GET /api/public/v1/uso te dice, en cualquier momento, cuánto llevas consumido de tu plan este mes y cuántos folios CAF de cada tipo de documento te quedan disponibles. Es de solo lectura: no cobra, no factura, no descuenta nada — solo informa.

Request

GET /api/public/v1/uso
X-API-Key: lum_test_XXXX

También acepta Authorization: Bearer lum_test_XXXX, igual que el resto de los endpoints.

Respuesta

{
  "exito": true,
  "datos": {
    "periodo": "2026-07",
    "plan": {
      "tiene_api": true,
      "periodo": "2026-07",
      "ambiente": "CERT",
      "plan_codigo": "starter",
      "plan_nombre": "Starter",
      "plan_vigente": true,
      "documentos_consumidos": 42,
      "documentos_incluidos": 100,
      "restante_plan": 58,
      "excedente": 0,
      "precio_base": 15000,
      "precio_excedente": 90,
      "tope_duro": null,
      "cargo_excedente": 0
    },
    "folios_caf": [
      {"tipo_dte": 33, "nombre": "Factura", "restantes": 120},
      {"tipo_dte": 39, "nombre": "Boleta", "restantes": 8}
    ]
  }
}

Para emitir necesitas tu certificado digital y tus folios CAF cargados en el sistema. Si folios_caf no trae el tipo de documento que quieres emitir (o su restantes es 0), la emisión fallará con 422 aunque tu plan tenga cupo.

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

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

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, en el ambiente de Producción de Configuración SII: certificado digital vigente, folios CAF cargados, y las resoluciones del SII de Boletas y de Facturas (ambas, porque el SII las autoriza por separado). Eso supone estar certificado ante el SII — nuestro módulo de certificación asistida te acompaña en el trámite.

Con el checklist completo, tu key lum_live_ se genera sola y te llega por correo: no tienes que pedírsela a nadie. El paso a paso completo está en Primeros pasos.