Guía

Autenticación

Toda request a la API pública de Comges DTE se autentica con una API Key. No hay OAuth, no hay JWT, no hay sesiones: una key, un header, un request.

Formato de las keys

Las API Keys tienen dos prefijos posibles, según el ambiente al que apuntan:

pk_test_... → Certificación (SII Maullín). Ideal para pruebas, no genera DTE con valor tributario.
pk_live_... → Producción (SII Palena). Emite DTE reales, con valor tributario ante el SII.

El ambiente se hereda y no se puede elegir

El ambiente de una key lo determina el usuario que la crea: sale de su ambiente operativo y queda congelado en la key al momento de emitirla. Un usuario de certificación no puede crear una key de producción — el servidor responde 403, no es sólo una restricción de la interfaz.

En consecuencia, el ambiente no viaja en el request: no hay campo en el cuerpo ni parámetro de query para cambiarlo. Si después un administrador cambia el ambiente del usuario, las keys ya emitidas siguen apuntando al ambiente con el que nacieron. Para operar en el otro ambiente, creá una key nueva.

El host tampoco define el ambiente: el mismo despliegue atiende ambos prefijos.

Trata a tus keys como contraseñas

Nunca commitees keys al repositorio. Usa variables de entorno, Secret Manager o Key Vault. Si una key se expone, revócala de inmediato desde el portal.

Cómo enviarla

La forma recomendada es el header X-Api-Key:

Header X-Api-Key

curl https://api-publica.dtecomges.cl/api/public/v1/dte/b5f8c2e1-7d93-4e8f-a12b-9c4d5e6f7a8b \
  -H "X-Api-Key: $API_KEY"

También aceptamos el esquema Authorization: Bearer estándar, útil cuando tu cliente HTTP sólo permite ese formato. El token debe empezar con pk_:

Authorization: Bearer

curl https://api-publica.dtecomges.cl/api/public/v1/dte/b5f8c2e1-7d93-4e8f-a12b-9c4d5e6f7a8b \
  -H "Authorization: Bearer $API_KEY"

Scopes y permisos

Cada key lleva asociado un conjunto de scopes que determinan qué puede hacer. Los scopes de emisión son granulares por tipo de documento: no existe un dte:emit genérico ni comodines.

Scope	Permite	Estado
dte:emit:33	Emitir Factura Electrónica	Operativo
dte:emit:34	Emitir Factura Exenta	Operativo
dte:emit:39	Emitir Boleta Electrónica	Operativo
dte:emit:41	Emitir Boleta Exenta	Operativo
dte:emit:43	Emitir Liquidación-Factura	No operativo
dte:emit:46	Emitir Factura de Compra	No operativo
dte:emit:52	Emitir Guía de Despacho	Operativo
dte:emit:56	Emitir Nota de Débito	Operativo
dte:emit:61	Emitir Nota de Crédito	Operativo
dte:emit:110	Emitir Factura de Exportación	Operativo
dte:emit:111	Emitir Nota de Débito de Exportación	Operativo
dte:emit:112	Emitir Nota de Crédito de Exportación	Operativo
dte:read	Consultar documentos emitidos y descargar su XML y su PDF. Es el scope que necesita casi cualquier integración.	Operativo
plantillas:emitir	Emitir a partir de una plantilla con variables.	Sin endpoint público
dte:sobre:read	Consultar el estado de un sobre enviado al SII.	Sin endpoint público
dte:sobre:enviar	Forzar el envío al SII de un sobre creado previamente.	Sin endpoint público
dte:proceso:read	Consultar procesos de emisión async y batches.	Sin endpoint público

Tener el scope no garantiza que la operación exista

No operativo — dte:emit:43 y dte:emit:46 — significa que el scope se puede asignar, pero la emisión responde 501 con emisor.tipo-dte-no-emisible sin consumir folio. La aritmética de esos dos tipos no está implementada. Si tu ERP factura compras o liquida por consignación, no diseñes el módulo asumiendo que están: consultanos antes.

Sin endpoint público significa que el scope existe en el registro y el portal te deja tildarlo, pero ninguna ruta de /api/public/v1 lo consume hoy. No pierdas tiempo buscándole el endpoint.

Si llamás a un endpoint sin el scope que exige, recibís un 403. El código depende de qué capa corte primero — ver Errores de autenticación más abajo.

Los scopes se administran desde el portal, y quien lo haga necesita el permiso empresa:api-keys:write (para crear, rotar, revocar o editar scopes) o empresa:api-keys:read (para listarlas). Si sos un integrador externo y no ves la opción, pedísela al administrador de la empresa: no es algo que se resuelva desde la API.

Aislamiento entre empresas

La empresa emisora sale de los claims de la key, nunca del request. Un id de documento que pertenece a otra empresa responde 404, no 403: la API no confirma la existencia de documentos ajenos.

Rotación y revocación

Las keys no expiran automáticamente. Recomendamos rotar en estos casos:

Cada vez que un miembro del equipo con acceso deja de estar autorizado.
Al menos una vez al año como buena práctica de seguridad.
Inmediatamente si sospechas que la key fue expuesta.

Puedes crear una nueva key, migrar tus servicios al nuevo valor y revocar la vieja sin downtime.

Rotar no cambia el ambiente

La rotación genera un secreto nuevo pero conserva el ambiente: una key pk_test_ rotada sigue siendo pk_test_ y sigue emitiendo contra certificación. Para pasar a producción hay que crear una key nueva desde un usuario cuyo ambiente operativo ya sea Producción. Es el error más caro del go-live: se rota, se despliega, y todo sigue yendo a Maullín sin ningún síntoma.

Errores de autenticación

Todos los 401 llegan con el mismo código, api-key.ausente: header ausente, key inexistente, revocada o expirada. Es deliberado, para no confirmarle a nadie qué keys existen. No escribas ramas contra un api-key.invalida — no llega nunca.

401 — cualquier problema con la key

HTTP/1.1 401 Unauthorized
Content-Type: application/json

{
  "code": "api-key.ausente",
  "title": "Se requiere API key en el header X-Api-Key."
}

El cuerpo del 401 no trae status ni traceId

Los rechazos de autenticación se escriben antes de que se arme el cuerpo de error completo: llegan sólo con code y title. Parseá defensivo.

El 403, en cambio, tiene dos códigos posibles según qué capa corte primero:

permiso.requerido — a la key le falta el scope que exige la ruta. Es el que devuelven las consultas (dte:read) y la anulación (dte:emit:61).
emisor.permiso-tipo-no-autorizado — a la key le falta dte:emit:{tipoDte} en la emisión. Trae field: "tipoDte".

Los dos significan lo mismo para vos: pedile a un administrador de la empresa que agregue ese scope a la key, o creá una key nueva con él.

403 — falta el scope del tipo de documento

HTTP/1.1 403 Forbidden
Content-Type: application/json

{
  "code": "emisor.permiso-tipo-no-autorizado",
  "title": "No tiene el permiso 'dte:emit:33' requerido para emitir este tipo de documento.",
  "status": 403,
  "field": "tipoDte"
}

El listado de scopes de esta guía refleja el registro real, pero la referencia de la API es la fuente de verdad: si alguna vez difieren, gana la referencia.

¿Por qué sólo API Keys?

Las integraciones DTE son server-to-server, sin browsers ni usuarios finales. OAuth agregaría complejidad sin beneficio claro. API Keys con scopes granulares ofrecen el mismo nivel de seguridad con menos ceremonias.