Primeros pasos con la API de LUMINOUS

Esta guía te lleva desde cero hasta emitir tu primer documento tributario de prueba. Al terminar vas a tener tu API key, el sandbox funcionando y una factura emitida contra el ambiente de certificación del SII.

⬇ Descargar este manual en PDF

1. Contratar la API y recibir tu key

Todo el proceso es autoservicio: no necesitas hablar con nadie para empezar.

Cómo se ve tu key

Son keys distintas: la de sandbox no sirve en producción ni al revés. Si te equivocas de base URL, la API te responde 400 diciéndote cuál es la correcta.

2. Qué es el sandbox y qué necesitas para usarlo

Nuestro sandbox no es un simulador: opera contra el ambiente de certificación real del SII. Lo que te funciona ahí es lo que va a funcionar en producción, con las mismas validaciones tributarias.

Los dos requisitos, paso a paso

1. Certificado digital — el mismo que usas para operar ante el SII. Súbelo en Configuración SII → Certificado Digital, con el ambiente Certificación seleccionado.
2. Folios CAF — descárgalos del sitio de certificación del SII (maullín) para cada tipo de documento que vayas a emitir, y súbelos en Configuración SII → Folios CAF.

Comprueba que estás listo

Este endpoint te dice qué folios tienes disponibles antes de intentar emitir:

curl https://pruebas.luminous.cl/api/public/v1/uso \
  -H "Authorization: Bearer lum_test_TU_KEY"

Si en folios_caf no aparece el tipo de documento que quieres emitir, o su restantes es 0, primero carga folios de ese tipo.

3. Tu primera llamada

Antes de emitir nada, confirma que tu key funciona:

curl https://pruebas.luminous.cl/api/public/v1/ping \
  -H "Authorization: Bearer lum_test_TU_KEY"

Respuesta esperada:

{
  "exito": true,
  "datos": {
    "app": "API Starter API",
    "ambiente": "CERT",
    "scopes": ["dte:emitir", "dte:leer", "pdf:leer"],
    "plan": "Starter API"
  },
  "mensaje": "Credenciales válidas."
}

Si ambiente dice CERT, estás en el sandbox y ningún documento que emitas tendrá efecto tributario. También puedes mandar la key como X-API-Key: lum_test_TU_KEY si te acomoda más.

4. Emitir tu primer documento

curl -X POST https://pruebas.luminous.cl/api/public/v1/dte/emitir \
  -H "Authorization: Bearer lum_test_TU_KEY" \
  -H "Idempotency-Key: pedido-8841" \
  -H "Content-Type: application/json" \
  -d '{
    "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}
    ]
  }'

Si sale bien recibes el folio y el track_id con el que el SII sigue tu documento:

{
  "exito": true,
  "datos": {
    "documento_id": 12345,
    "tipo_dte": 33,
    "folio": 41,
    "ambiente": "CERT",
    "totales": {"neto": 350000, "iva": 66500, "total": 416500},
    "enviado": true,
    "track_id": "9876543"
  },
  "mensaje": "Documento emitido."
}

Después de emitir: consulta el estado

El SII procesa de forma asincrónica, así que la respuesta anterior no significa todavía «aceptado». Consulta el estado hasta que cambie:

curl https://pruebas.luminous.cl/api/public/v1/dte/33/41 \
  -H "Authorization: Bearer lum_test_TU_KEY"

Los estados van EMITIDO_LOCAL → RECIBIDO_SII → ACEPTADO_SII o RECHAZADO_SII. También puedes descargar el PDF (/pdf?copia=original|cedible|ambas) y el XML firmado (/xml).

La lista completa de tipos de documento, campos y códigos de error está en la Referencia v1.

5. Pasar a producción

Para emitir documentos con validez tributaria real necesitas estar certificado ante el SII. Es un trámite del SII, no nuestro, pero te acompañamos con nuestro módulo de certificación asistida.

Cuando lo completes, carga en Configuración SII, con el ambiente Producción seleccionado:

• Tu certificado digital
• Tu resolución del SII para Boletas (número y fecha)
• Tu resolución del SII para Facturas (número y fecha)
• Tus folios CAF de producción

Con el checklist completo, tu key lum_live_ se genera sola y te llega por correo. Desde ahí solo cambias la base URL a https://luminous.cl y la key: el resto de tu integración no cambia.

6. Problemas frecuentes

Dos reglas que te van a ahorrar dolores

• Nunca pongas la key en código que corra en el navegador o en una app móvil. Llama a la API desde tu backend: quien tenga tu key puede emitir documentos con tu RUT.
• Integra primero en sandbox. Un documento emitido en producción no se borra — se corrige con una nota de crédito, y eso es un hecho tributario.

¿Algo no calza? Escríbenos desde contacto y te ayudamos con tu integración.