API pública Comges DTE — guía de integración

Público objetivo: desarrollador de un sistema externo (ERP, e-commerce, POS) que necesita emitir Documentos Tributarios Electrónicos al SII de Chile desde su propio software, sin usar nuestro portal.

Este documento es la fuente de verdad de la API pública. Las guías y la referencia interactiva del portal son tutoriales que apuntan acá; si alguna difiere de este documento, vale este documento.

Regla de este documento: acá solo se describe lo que existe y está desplegado. Cada ruta, cada campo y cada código de error fue verificado contra el código que corre en producción. Lo que todavía no existe está en Qué no existe todavía, explícito, para que nadie escriba código contra una promesa.

Referencia interactiva (OpenAPI, generada del mismo contrato): /docs/reference en el portal.

ÍndiceCopiar

1. Antes de empezar: dar de alta la empresa
2. Lo mínimo para entender el modelo
3. Autenticación con API Key
4. Ambientes: certificación y producción
5. Scopes (permisos de la key)
6. Health check
7. Prerequisitos: qué tiene que estar listo antes de emitir
8. Emitir un DTE
9. Consultar el estado (modelo asíncrono)
10. Descargar XML y PDF - Enlaces firmados para el comprador
11. Anular un documento
12. Devolución parcial: notas de crédito por línea o por monto
13. Exportación (110 / 111 / 112)
14. Paso a producción (go-live)
15. Errores: formato y códigos
16. Idempotencia y reintentos
17. Rate limiting y límites duros
18. Webhooks - Catálogo de eventos - Vector de prueba fijo
19. Ejemplo end-to-end con curl
20. Qué no existe todavía
21. Soporte

1. Antes de empezar: dar de alta la empresaCopiar

El alta de una empresa emisora no es self-service. No existe un endpoint público de registro: la ejecuta el equipo de Comges, y hasta que ese paso no está hecho no hay portal, no hay usuario, no hay API Key y no hay nada que integrar.

Esto es lo primero que hay que resolver, antes de escribir una línea de código.

Los cinco datos que hay que entregar

Para dar de alta a la empresa emisora hay que entregarnos, de esa empresa:

⚠️ Estos datos son credenciales reales del contribuyente. Entregarlos es una decisión del cliente final, no del integrador. Coordinalo con él antes de prometer una fecha de puesta en marcha: en la práctica es el paso que más tarda de todo el proyecto.

Qué pasa en el alta

Con esos cinco datos, el alta:

1. Valida el certificado y su clave, y valida la clave tributaria contra el sitio del SII.
2. Trae del SII los datos de la empresa: razón social, correo, teléfono, oficina del SII, sucursales y actividades económicas (actecos).
3. Crea la empresa con esos datos y guarda el certificado.

Si el certificado, su clave o la clave tributaria están mal, el alta falla completa: no queda una empresa a medio crear.

Lo que NO hace el alta (y hay que pedir aparte)

• El usuario administrador de la empresa se crea en un paso posterior. Sin usuario no hay quien entre al portal ni quien cree API Keys.
• La habilitación de cada tipo de documento (33, 34, 39, …) es un paso aparte. Ver §7 Prerequisitos.
• La certificación ante el SII para emitir en Producción es otro proceso, con su propia duración. Ver §14 Paso a producción.

El reloj del plan empieza acá

Toda empresa nueva se crea con plan Trial de 30 días, contados desde el alta, no desde que empieza la integración. Si el alta se hace mucho antes de que el ERP esté listo, el plan puede vencer en pleno desarrollo y toda emisión pasa a responder 403 plan.vencido.

Recomendación: pedí el alta cuando tengas el proyecto encaminado, y coordiná la vigencia del plan con soporte antes de arrancar.

A quién pedirlo

El alta, la creación del usuario administrador, la habilitación de tipos de documento y la extensión del plan las gestiona soporte de Comges: escribí a [email protected] con el RUT de la empresa y qué tipos de documento vas a emitir.

Quién puede crear la API Key

Una vez que la empresa existe y tiene usuario, las API Keys se administran desde el portal (/portal/configuracion/api-keys):

Si el usuario entra al portal y no ve la sección de API Keys, no es un bug: le falta el permiso. Se lo tiene que dar el administrador de la empresa.

2. Lo mínimo para entender el modeloCopiar

Rutas públicas

17 rutas de negocio, más el health check. Base: https://api-publica.dtecomges.cl

DTE nacional

Exportación

Descargas firmadas — las únicas rutas sin API Key. Ver §10.

Estas cuatro no las construís vos: llegan armadas y firmadas en xmlUrl y pdfUrl dentro del cuerpo de la emisión. Son para reenviárselas al comprador, que no tiene tu API Key.

Operación

Una integración de facturación típica usa cinco: emitir, consultar, XML, PDF y anular.

3. Autenticación con API KeyCopiar

Formato de la key

pk_{live|test}_{prefijo}_{secreto}
   └─ ambiente   └─ 8 chars  └─ secreto base64url (32 bytes)

Ejemplo (ilustrativo, no funcional): pk_test_a1b2c3d4_R0hKTlBRU1RVVldYWVpiY2RlZmdoaWprbG0

• El prefijo de 8 caracteres identifica la key y es el que aparece en el portal, en los logs y en la partición del rate limiter. No es secreto.
• El secreto se muestra una sola vez, al crear o rotar la key. No se puede recuperar: la base solo guarda su hash SHA-256.
• El segmento live / test tiene que coincidir con el ambiente registrado de la key. Una clave pk_live_* presentada contra una key marcada como de certificación se rechaza con 401 (el prefijo no puede mentir sobre el ambiente).

Cómo se manda

Header canónico:

X-Api-Key: pk_test_a1b2c3d4_...

Alternativa aceptada (útil si tu cliente HTTP solo maneja Authorization):

Authorization: Bearer pk_test_a1b2c3d4_...

El servidor acepta Authorization: Bearer solo si el token empieza con pk_.

Qué pasa si falla

El 401 es deliberadamente genérico: no distingue "no mandaste key" de "tu key no existe" ni de "tu key fue revocada". Es anti-enumeración — no queremos que alguien descubra prefijos válidos probando. Para programar, usá el status 401, no el sub-código: hoy todos los caminos de fallo de autenticación devuelven el mismo code.

El 403 por scope faltante devuelve permiso.requerido, con el código del permiso que falta dentro del title. Si tu código busca otro valor, esa rama nunca se va a ejecutar.

Obtener y rotar una key

Se crean desde el portal (/portal/configuracion/api-keys). Al crear se elige nombre, scopes y una expiración opcional. Quién puede hacerlo: ver §1.

⚠️ La rotación no tiene ventana de gracia. Al rotar una key, el secreto anterior deja de servir de inmediato: no hay período en que las dos versiones funcionen. Planificá la rotación como un despliegue coordinado (guardá el secreto nuevo, desplegá, recién ahí rotá), no como un cambio en caliente.

⚠️ La revocación tarda hasta 30 segundos en propagarse. El resultado positivo de validación se cachea 30 s. Una key revocada puede seguir emitiendo dentro de esa ventana. Si necesitás corte inmediato, revocá y verificá; para un incidente de seguridad real, escalá a soporte.

4. Ambientes: certificación y producciónCopiar

El ambiente lo determina la key y nada más.

• No lo cambia el host: la misma URL sirve a los dos ambientes.
• No lo cambia el body. El campo ambiente del cuerpo de emisión existe por compatibilidad, pero con una API Key se ignora si coincide y se rechaza si contradice:

// key pk_test_ (Certificación) + body {"ambiente":"Produccion"}
{
  "code": "emisor.ambiente-no-coincide-con-key",
  "title": "La API key opera en 'Certificacion' y el cuerpo pide 'Produccion'. El ambiente lo determina la key, no el request: usá una key del ambiente que necesitás.",
  "status": 400,
  "field": "ambiente"
}

La forma correcta de trabajar con los dos ambientes es tener dos keys y elegir cuál usar en tu configuración. La recomendación operativa es no mandar ambiente en el body en absoluto.

⚠️ Una sola URL base. https://api-publica.dtecomges.cl es la única que se integra, para los dos ambientes. Si en alguna herramienta o colección importada aparece un servidor alternativo con un hostname de despliegue (algo terminado en .run.app), no lo uses: es un entorno interno de desarrollo, corre contra otra base de datos, tus keys devuelven 401 ahí y su URL cambia sin aviso.

El ambiente de la key se hereda del usuario que la creó y queda congelado en ella. Un usuario que opera en certificación nunca obtiene una key de producción; al crear la key se puede además restringirla explícitamente a certificación, pero nunca ampliarla. Para pasar a producción, ver §14.

5. Scopes (permisos de la key)Copiar

Cada key lleva una lista de scopes. El servidor valida el scope antes de reservar folio.

Reglas que sorprenden si no se leen:

• Anular exige dte:emit:61, no un scope propio. No existe dte:anular.
• dte:read cubre todos los caminos de lectura (detalle, XML, PDF, ticket, acreditable). Sin él, todos responden 403, incluido el PDF.
• Tener dte:emit:33 no habilita a leer. Son scopes independientes.
• Existen otros scopes asignables en el portal (plantillas, sobres, procesos) que no tienen ninguna ruta en esta API pública. Asignarlos no habilita nada acá.
• El scope webhook:configurar se puede asignar, pero no habilita nada en esta API. Las suscripciones de webhooks se administran desde el portal, no por código: ninguna ruta bajo /api/public/v1/ las crea, edita ni consulta. Ver §18.

Una key típica de integración de facturación lleva: dte:emit:33, dte:emit:61, dte:read.

⚠️ La misma falta de dte:emit:61 puede devolver tres códigos distintos, según qué capa corte primero: permiso.requerido (403), emisor.permiso-tipo-no-autorizado (403, al anular) o dte.permiso-faltante (403, al emitir una nota de crédito parcial). Los tres significan lo mismo: falta el scope. Ramificá por el code, no por el status: dentro del mismo 403 conviven causas que se resuelven de forma distinta —a la key le falta un scope (§15.1) vs. ese tipo todavía no está certificado en Producción (cert.tipo-no-aprobado-prod, §15.3) vs. el plan venció (plan.vencido, §15.2)—. Si programás una rama de "falta permiso", cubrí los tres códigos de scope.

6. Health checkCopiar

GET https://api-publica.dtecomges.cl/health      → 200 "Healthy"

• Cuelga de la raíz del host, no de /api/public/v1.
• Público: no lleva X-Api-Key.
• Exento del rate limit: podés consultarlo tan seguido como quieras sin gastar tu cuota.

⚠️ Solo dice que el servicio responde. No verifica el SII, ni la base de datos, ni la disponibilidad de folios. Un 200 acá no garantiza que una emisión vaya a funcionar.

Usalo para tus monitores de disponibilidad. Lo que no hay que hacer es usar GET /api/public/v1/dte/{id} como ping: consume cuota de rate limit por cada llamada.

7. Prerequisitos: qué tiene que estar listo antes de emitirCopiar

Cada fila es una condición que, si falta, hace fallar la emisión. La columna del código está para que puedas buscar acá el error que te devolvió la API.

8. Emitir un DTECopiar

POST /api/public/v1/dte
Content-Type: application/json
X-Api-Key: pk_test_...

Un solo endpoint cubre todos los tipos nacionales. El tipo se elige con tipoDte: 33 factura, 34 factura exenta, 39 boleta, 41 boleta exenta, 52 guía de despacho, 56 nota de débito, 61 nota de crédito.

Tipos que esta API no emite

Los tipos de exportación (110/111/112) no van por acá: POST /api/public/v1/dte los rechaza con 501 emisor.tipo-dte-no-implementado. Usá POST /api/public/v1/exportacion.

Los tipos 43 (liquidación-factura) y 46 (factura de compra) no se emiten por esta API: POST /api/public/v1/dte responde 501 emisor.tipo-dte-no-emisible sin consumir folio. La 43 admite montos negativos y exige un bloque de comisiones propio; la 46 invierte la semántica del receptor (el RUT es el del vendedor) y lleva retención. Ninguna de las dos aritméticas está implementada, y emitirlas a medias produciría documentos mal formados que el SII rechazaría con el folio ya quemado. Sin fecha comprometida. Los scopes dte:emit:43 y dte:emit:46 existen y se pueden asignar, pero no habilitan nada.

El certificado digital tiene que estar activo

Firmar es obligatorio: no existe ningún camino que persista un DTE sin firma. Por eso la emisión nacional verifica el certificado antes de reservar el folio, y falla explícito:

Los dos errores traen field: "certificado". Ninguno se arregla reintentando: hay que cargar un PFX vigente o corregir su clave desde el portal. El certificado vence cada 1–3 años, así que este error puede aparecer de un día para otro en una integración que venía funcionando: tratalo como un error operativo que hay que avisar, no como un 4xx de validación de tu request.

⚠️ En exportación el orden es distinto y peor. POST /api/public/v1/exportacion carga el PFX después de tomar el folio, así que responde 409 exp.sin-certificado (sin PFX activo) o 500 exp.error-pfx (PFX ilegible) con el folio ya consumido. Ver §15.17.

Cuerpo mínimo

{
  "tipoDte": 33,
  "receptor": {
    "rut": "96790240-3",
    "razonSocial": "Cliente Ejemplo S.A.",
    "giro": "Comercio al por mayor",
    "direccion": "Av. Providencia 1234",
    "comuna": "Providencia"
  },
  "detalles": [
    {
      "nroLinea": 1,
      "nombreItem": "Consultoría técnica",
      "cantidad": 1,
      "precioUnitario": 1000000
    }
  ]
}

Campos del cuerpo

Raíz:

receptor:

detalles[]:

⚠️ unidadMedida tiene un máximo de 4 caracteres. Es un límite del formato del SII, no nuestro. Unidades corrientes como UNIDAD, KILOS o LITROS no caben: usá UN, KG, LT, MT, CJA. Si tu ERP exporta la unidad como texto largo, mapeala antes de llamar. Una línea con la unidad demasiado larga devuelve 400 emisor.detalle-largo-excedido y ninguna línea del documento se emite.

referencias[] (obligatorio en notas de crédito y débito emitidas a mano):

Para anular un documento no armes la referencia a mano: usá POST /{id}/anular, que la resuelve el servidor. Para una devolución parcial, usá POST /{id}/nota-credito.

Ningún largo de esta sección se trunca. Exceder cualquiera de los de arriba —razonRef incluido— devuelve 400 antes de reservar folio, con el campo culpable en field. El único campo del sistema que sí se recorta en silencio es el motivo de POST /{id}/anular, que no es parte de este cuerpo.

Aritmética: cómo se calcula el documento

Los totales del documento — y los montoNeto / montoIva / montoTotal que devuelve la respuesta — los calcula el servidor, no vos. Si tu ERP usa otra aritmética, el total que te devolvemos no va a coincidir con el tuyo, y esa diferencia después impide anular el documento (emisor.montos-no-reproducibles, ver §11).

El precio unitario se redondea a peso entero (AwayFromZero) antes de calcular la línea:

montoLinea = round( cantidad × round(precioUnitario) − descuentoMonto + recargoMonto )

Si trabajás con precios de más de dos decimales, mandá el precio ya redondeado a peso. cantidad sí admite decimales (hasta 6, formato del SII); los montos del documento son pesos enteros.

Cero y negativos se rechazan: cantidad > 0, precioUnitario >= 0, y descuentoMonto y recargoMonto no negativos. Si no, 400 emisor.detalle-monto-invalido, con todas las líneas problemáticas listadas de una vez en el formato L[n] que usa el SII.

Única excepción: en nota de crédito (61) y nota de débito (56) se admite cantidad: 0 — es la línea "dummy" con la que el SII anula un documento o corrige un texto.

Ejemplos por tipo de documento

Todos los cuerpos de abajo van al mismo POST /api/public/v1/dte.

Factura afecta (33)

El caso base. giro, direccion y comuna del receptor son obligatorios (el SII rechaza la factura sin ellos, y para entonces el folio ya se consumió: por eso se validan antes).

{
  "tipoDte": 33,
  "receptor": {
    "rut": "96790240-3",
    "razonSocial": "Cliente Ejemplo S.A.",
    "giro": "Comercio al por mayor",
    "direccion": "Av. Providencia 1234, of. 501",
    "comuna": "Providencia",
    "ciudad": "Santiago",
    "contacto": "Marcela Ruiz - [email protected]",
    "correos": ["[email protected]"]
  },
  "formaPago": 2,
  "fechaVencimiento": "30-08-2026",
  "detalles": [
    {
      "nroLinea": 1,
      "codigoItem": "SRV-CONS-01",
      "tipoCodigo": "INT1",
      "nombreItem": "Consultoría técnica",
      "descripcionItem": "Horas de consultoría del mes de julio 2026",
      "cantidad": 1,
      "unidadMedida": "UN",
      "precioUnitario": 1000000
    },
    {
      "nroLinea": 2,
      "nombreItem": "Licencia de software",
      "cantidad": 3,
      "unidadMedida": "UN",
      "precioUnitario": 25000
    }
  ]
}

Totales que devuelve la respuesta:

formaPago: 2 (crédito) sin fechaVencimiento toma por defecto emisión + 30 días. Con formaPago: 1 (contado) o 3 (sin costo) no se genera vencimiento.

Factura exenta (34)

Mismos requisitos de receptor que la 33 (giro, direccion, comuna obligatorios).

⚠️ Marcá cada línea con indExe: 1. El servicio no lo deduce del tipo de documento: en una 34 el IVA siempre sale 0, así que una línea sin indExe suma a montoNeto y el documento queda con neto positivo e IVA cero — descuadrado, y el SII lo rechaza con el folio ya consumido. Es la trampa propia de este tipo.

{
  "tipoDte": 34,
  "receptor": {
    "rut": "77123456-9",
    "razonSocial": "Instituto de Formación Andes SpA",
    "giro": "Enseñanza",
    "direccion": "Manuel Montt 980",
    "comuna": "Ñuñoa"
  },
  "formaPago": 1,
  "detalles": [
    {
      "nroLinea": 1,
      "nombreItem": "Curso de capacitación exento",
      "cantidad": 1,
      "unidadMedida": "UN",
      "precioUnitario": 350000,
      "indExe": 1
    },
    {
      "nroLinea": 2,
      "nombreItem": "Material de estudio",
      "cantidad": 12,
      "unidadMedida": "UN",
      "precioUnitario": 15000,
      "indExe": 1
    }
  ]
}

Boleta electrónica (39) y boleta exenta (41)

Tres diferencias con la factura, todas propias del formato de boleta del SII:

1. precioUnitario va NETO. El sistema le suma el IVA. En la boleta afecta, el precio que viaja al SII es el precio al público (con IVA); vos mandás el neto y el servicio multiplica por 1,19 al construir el documento. Si mandás el precio con IVA ya incluido, la boleta sale por un 19 % de más.
2. giro, contacto, ciudad y rutSolicita del receptor se descartan. El receptor de boleta del SII es estricto y rechaza el envío completo si aparecen. direccion y comuna sí se emiten si vienen.
3. indServicio es propio de la boleta: 1 periódico con domicilio, 2 periódico sin domicilio, 3 boletas de venta y servicios (default si se omite), 4 espectáculos.

{
  "tipoDte": 39,
  "indServicio": 3,
  "receptor": {
    "rut": "66666666-6",
    "razonSocial": "Consumidor final"
  },
  "detalles": [
    {
      "nroLinea": 1,
      "nombreItem": "Café de grano 250 g",
      "cantidad": 2,
      "unidadMedida": "UN",
      "precioUnitario": 1500
    },
    {
      "nroLinea": 2,
      "nombreItem": "Sándwich del día",
      "cantidad": 1,
      "unidadMedida": "UN",
      "precioUnitario": 4200
    }
  ]
}

Propinas y otros no facturables: una línea con indExe: 2 no genera neto ni IVA, y en la boleta sí suma al montoTotal (viaja además en montoNF). Es la diferencia con la factura, donde el no facturable queda fuera del montoTotal.

Boleta exenta (41): mismo cuerpo, con "tipoDte": 41 y indExe: 1 en todas las líneas (misma regla que la 34: el tipo no lo deduce solo). En la 41 el montoTotal incluye el componente no facturable, igual que en la 39.

indServicio no se valida: se escribe tal cual en el documento. Un valor fuera de rango no devuelve 400 acá — lo rechaza el SII después, con el folio ya consumido.

Guía de despacho (52)

Es el tipo con más campos propios, y los tres son exclusivos de él.

indTraslado — obligatorio, sin valor por defecto. Sin él: 400 emisor.ind-traslado-requerido. No se asume un default a propósito: emitir "traslado interno" por omisión falsearía el motivo del traslado ante el SII.

8 y 9 exigen el bloque de aduana (puerto de embarque y desembarque, peso bruto, total de bultos) que esta operación no arma. Se rechazan antes de reservar folio, en vez de emitir un documento que el SII rechazaría con el folio ya quemado. Un valor fuera de 1..9 devuelve 400 emisor.ind-traslado-invalido.

tipoDespacho — opcional. 1 por cuenta del receptor, 2 por cuenta del emisor a instalaciones del cliente, 3 por cuenta del emisor a otras instalaciones. Fuera de 1..3: 400 emisor.tipo-despacho-invalido.

indTraslado y tipoDespacho solo existen en el 52. Mandarlos en otro tipo devuelve 400 (emisor.ind-traslado-no-aplica / emisor.tipo-despacho-no-aplica) — no se ignoran en silencio.

transporte — opcional, todos sus campos opcionales:

rutChofer y nombreChofer van juntos o no van. Informar solo uno devuelve 400 emisor.transporte-chofer-incompleto: el formato del SII exige los dos hijos dentro del bloque del chofer. Exceder cualquiera de los largos devuelve 400 emisor.transporte-largo-excedido (no se trunca). El bloque de transporte se acepta en cualquier tipo salvo boletas, donde se descarta; en la práctica solo tiene sentido en la 52.

{
  "tipoDte": 52,
  "indTraslado": 1,
  "tipoDespacho": 2,
  "receptor": {
    "rut": "96790240-3",
    "razonSocial": "Cliente Ejemplo S.A.",
    "giro": "Comercio al por mayor",
    "direccion": "Av. Providencia 1234",
    "comuna": "Providencia"
  },
  "transporte": {
    "patente": "KXPR23",
    "rutTransportista": "76543210-3",
    "rutChofer": "13579246-2",
    "nombreChofer": "Pedro Salinas",
    "direccionDestino": "Camino a Melipilla 5600, bodega 3",
    "comunaDestino": "Maipú",
    "ciudadDestino": "Santiago"
  },
  "detalles": [
    {
      "nroLinea": 1,
      "codigoItem": "PROD-114",
      "nombreItem": "Caja de repuestos modelo A",
      "cantidad": 10,
      "unidadMedida": "CJ",
      "precioUnitario": 12000
    }
  ]
}

Guía de venta vs. traslado interno. Con indTraslado 1 o 2 la mercadería ya está vendida y el SII exige neto, tasa e IVA cuadrados: se calcula IVA sobre las líneas afectas, como en una factura. En un traslado interno (indTraslado: 5) lo habitual es marcar las líneas con indExe: 1, con lo que neto e IVA quedan en 0 y el documento solo mueve mercadería.

Nota de débito (56)

Exige al menos una referencia, y cada referencia exige codRef. Son dos validaciones distintas, con dos códigos distintos:

• Sin referencias → 400 emisor.referencia-requerida.
• Con referencia pero sin codRef (o con un codRef distinto de 1/2/3) → 400 emisor.referencia-codref-invalido, con todas las líneas problemáticas listadas.

A diferencia de la factura, en la nota de débito y en la de crédito giro, direccion y comuna del receptor son opcionales.

fechaRef debe ser la fecha de emisión del documento referenciado, y tiene que caer entre 2002-08-01 y 2050-12-31; fuera de rango es 400 emisor.referencia-fecha-fuera-de-rango.

{
  "tipoDte": 56,
  "receptor": {
    "rut": "96790240-3",
    "razonSocial": "Cliente Ejemplo S.A."
  },
  "referencias": [
    {
      "nroLinea": 1,
      "tipoDocRef": "33",
      "folioRef": "1048",
      "fechaRef": "2026-07-27",
      "codRef": 3,
      "razonRef": "Cobro de intereses por mora"
    }
  ],
  "detalles": [
    {
      "nroLinea": 1,
      "nombreItem": "Intereses por mora factura 1048",
      "cantidad": 1,
      "unidadMedida": "UN",
      "precioUnitario": 25000
    }
  ]
}

Nota de crédito (61)

Mismas reglas de referencia que la 56 (referencias obligatoria, codRef obligatorio en cada línea, receptor sin giro/direccion/comuna obligatorios).

Antes de armar una 61 a mano, mirá si te sirve un endpoint dedicado. Para anular un documento completo está POST /{id}/anular, y para una devolución parcial POST /{id}/nota-credito. En los dos casos la referencia la arma el servidor leyendo el documento original. Armarla a mano ya rechazó una anulación real: el cliente mandó fechaRef con la fecha de hoy en lugar de la fecha de emisión del original, el SII rechazó la nota y el folio se quemó igual.

La 61 a mano queda para lo que esos endpoints no cubren: por ejemplo corregir el texto de un documento (codRef: 2) o acreditar un documento que no emitiste por esta API.

{
  "tipoDte": 61,
  "receptor": {
    "rut": "96790240-3",
    "razonSocial": "Cliente Ejemplo S.A."
  },
  "referencias": [
    {
      "nroLinea": 1,
      "tipoDocRef": "33",
      "folioRef": "1048",
      "fechaRef": "2026-07-27",
      "codRef": 3,
      "razonRef": "Descuento comercial acordado post facturación"
    }
  ],
  "detalles": [
    {
      "nroLinea": 1,
      "nombreItem": "Descuento comercial factura 1048",
      "cantidad": 1,
      "unidadMedida": "UN",
      "precioUnitario": 50000
    }
  ]
}

Corregir solo el texto (codRef: 2) es el único caso donde se admite cantidad: 0: la nota no mueve montos, solo declara la corrección.

{
  "tipoDte": 61,
  "receptor": { "rut": "96790240-3", "razonSocial": "Cliente Ejemplo S.A." },
  "referencias": [
    {
      "nroLinea": 1,
      "tipoDocRef": "33",
      "folioRef": "1048",
      "fechaRef": "2026-07-27",
      "codRef": 2,
      "razonRef": "Corrige giro del receptor"
    }
  ],
  "detalles": [
    {
      "nroLinea": 1,
      "nombreItem": "Corrige giro del receptor",
      "cantidad": 0,
      "precioUnitario": 0
    }
  ]
}

Casos de borde

Ítems exentos mezclados con afectos

Usá indExe por línea: 0 afecto (default), 1 exento, 2 no facturable (propina, cobro por cuenta de terceros), 6 no facturable negativo. Cualquier otro valor devuelve 400 emisor.detalle-indexe-invalido (los códigos 3, 4 y 5 del formato del SII no están soportados).

indExento: true sigue funcionando por compatibilidad, pero equivale a indExe: 1 y manda indExe cuando vienen los dos. En integraciones nuevas usá solo indExe.

{
  "tipoDte": 33,
  "receptor": {
    "rut": "96790240-3",
    "razonSocial": "Cliente Ejemplo S.A.",
    "giro": "Comercio al por mayor",
    "direccion": "Av. Providencia 1234",
    "comuna": "Providencia"
  },
  "detalles": [
    {
      "nroLinea": 1,
      "nombreItem": "Servicio afecto a IVA",
      "cantidad": 1,
      "unidadMedida": "UN",
      "precioUnitario": 100000,
      "indExe": 0
    },
    {
      "nroLinea": 2,
      "nombreItem": "Servicio exento de IVA",
      "cantidad": 1,
      "unidadMedida": "UN",
      "precioUnitario": 40000,
      "indExe": 1
    }
  ]
}

Descuentos y recargos

Hay dos niveles, y no se comportan igual.

Por línea — descuentoMonto / recargoMonto. Son montos, nunca porcentajes, y el valor es el de la línea completa, no el de cada unidad. No pueden ser negativos. Se aplican dentro de la línea, con la fórmula de Aritmética.

{
  "tipoDte": 33,
  "receptor": {
    "rut": "96790240-3",
    "razonSocial": "Cliente Ejemplo S.A.",
    "giro": "Comercio al por mayor",
    "direccion": "Av. Providencia 1234",
    "comuna": "Providencia"
  },
  "detalles": [
    {
      "nroLinea": 1,
      "nombreItem": "Producto con descuento por volumen",
      "cantidad": 10,
      "unidadMedida": "UN",
      "precioUnitario": 5000,
      "descuentoMonto": 5000
    },
    {
      "nroLinea": 2,
      "nombreItem": "Servicio con recargo por urgencia",
      "cantidad": 1,
      "unidadMedida": "UN",
      "precioUnitario": 20000,
      "recargoMonto": 1500
    }
  ]
}

Línea 1: 10 × 5000 − 5000 = 45 000. Línea 2: 20 000 + 1 500 = 21 500.

Globales — descuentosGlobales[]. Máximo 20 entradas. Se aplican en cascada sobre las bases del documento, en el orden en que vienen: un segundo descuento del 10 % descuenta el 10 % de lo que quedó, no del total inicial.

⚠️ Un documento con líneas afectas y exentas necesita una línea de descuento global por cada base. Con una sola entrada sin indExeDR solo se descuenta la parte afecta, y la exenta queda entera — el documento se emite igual, y el SII lo cuestiona porque los montos no le cuadran.

{
  "tipoDte": 33,
  "receptor": {
    "rut": "96790240-3",
    "razonSocial": "Cliente Ejemplo S.A.",
    "giro": "Comercio al por mayor",
    "direccion": "Av. Providencia 1234",
    "comuna": "Providencia"
  },
  "detalles": [
    {
      "nroLinea": 1,
      "nombreItem": "Servicio afecto",
      "cantidad": 1,
      "unidadMedida": "UN",
      "precioUnitario": 100000,
      "indExe": 0
    },
    {
      "nroLinea": 2,
      "nombreItem": "Servicio exento",
      "cantidad": 1,
      "unidadMedida": "UN",
      "precioUnitario": 40000,
      "indExe": 1
    }
  ],
  "descuentosGlobales": [
    {
      "nroLinea": 1,
      "tipoMovimiento": "D",
      "tipoValor": "%",
      "valor": 10,
      "glosa": "Descuento comercial 10% - afectos"
    },
    {
      "nroLinea": 2,
      "tipoMovimiento": "D",
      "tipoValor": "%",
      "valor": 10,
      "glosa": "Descuento comercial 10% - exentos",
      "indExeDR": 1
    }
  ]
}

En boleta (39/41) los descuentos globales se aplican sobre bases brutas, porque el detalle de la boleta va con IVA incluido. Un descuento global con tipoValor: "$" en una boleta tiene que expresarse con IVA; en porcentaje da lo mismo.

Receptor sin RUT y boleta a consumidor final

receptor.rut y receptor.razonSocial son siempre obligatorios, en todos los tipos. No hay forma de emitir sin receptor: tanto omitir el RUT como mandarlo con el dígito verificador equivocado devuelven 400 emisor.rut-receptor-invalido, con field: "receptor.rut" y sin tocar el folio (se valida por módulo 11 antes de reservarlo).

Ojo con el orden de las palabras: el código que vas a recibir es emisor.rut-receptor-invalido. Los códigos emisor.receptor-rut-requerido y emisor.receptor-rut-invalido existen en el código fuente, pero son inalcanzables desde POST /dte: el chequeo que devuelve emisor.rut-receptor-invalido corre antes y se los come. No programes contra ellos.

Cuando no hay cliente identificado —el caso normal de una boleta en punto de venta— se usa el RUT genérico del SII para consumidor final:

{
  "receptor": {
    "rut": "66666666-6",
    "razonSocial": "Consumidor final"
  }
}

razonSocial es texto libre: cualquier etiqueta legible sirve.

El formato del RUT es indiferente: 96790240-3, 96.790.240-3 y 967902403 se normalizan solos a la forma canónica. La k del dígito verificador se acepta en minúscula o mayúscula.

Otros RUT que conviene conocer: 55555555-5 es el receptor extranjero genérico y pertenece al flujo de exportación (§13), no a este endpoint.

Respuesta 201 — el camino normal

{
  "id": "b5f8c2e1-7d93-4e8f-a12b-9c4d5e6f7a8b",
  "tipoDte": 33,
  "folio": 1048,
  "ambiente": "Certificacion",
  "fechaEmision": "2026-07-27",
  "montoNeto": 1000000,
  "montoExento": 0,
  "montoIva": 190000,
  "montoTotal": 1190000,
  "montoNF": 0,
  "estadoSii": "Pendiente",
  "glosaSii": null,
  "trackId": null,
  "transactionId": "a3bb189e-8bf9-3888-9912-ace4e6543002",
  "creadoEn": "2026-07-27T14:30:12Z",
  "offsetUtcHoras": -4,
  "glosa": "Consultoría técnica",
  "receptorRut": "96790240-3",
  "receptorRznSoc": "Cliente Ejemplo S.A.",
  "montoAcreditado": 0,
  "estadoAcreditacion": "SinAcreditar",
  "anuladoEn": null,
  "notaCreditoId": null,
  "plantillaId": null,
  "cotizacionIds": null,
  "customFields": null,
  "customFieldLabels": null,
  "xmlBlobPath": "...",

  "ted": "<TED version=\"1.0\"><DD>…</DD><FRMT algoritmo=\"SHA1withRSA\">…</FRMT></TED>",
  "xmlUrl": "https://api-publica.dtecomges.cl/api/public/v1/descargas/dte/b5f8c2e1-.../xml?t=Vg9m…&exp=1769472000&e=7c1e…&a=Certificacion",
  "pdfUrl": "https://api-publica.dtecomges.cl/api/public/v1/descargas/dte/b5f8c2e1-.../pdf?t=Kq2p…&exp=1769472000&e=7c1e…&a=Certificacion"
}

Campos que conviene conocer:

ted solo viaja en la respuesta de la emisión. Al emitir, el timbre ya está en memoria y devolverlo no cuesta nada. En GET /dte/{id} llega siempre null a propósito: el TED vive en almacenamiento y leerlo penalizaría una consulta que hoy no toca disco. Si lo necesitás, guardalo cuando emitís — no se puede recuperar después por esta API. Para tener el timbre más tarde, descargá el XML completo, que lo contiene.

En exportación (POST /exportacion) el campo existe en el cuerpo pero llega siempre null: ese camino todavía no expone el TED. El XML de la exportación sí lo trae.

Lo que todavía no ocurrió en un 201 es el envío al SII.

Respuesta 202 — la emisión quedó esperando folio

Este no es un caso raro: es el caso normal de un contribuyente nuevo. El SII entrega folios de a poco a quien recién empieza (a veces de a uno), así que al emitir varios documentos seguidos es esperable quedarse sin folio disponible en medio.

Cuando eso pasa, el documento ya fue validado y en vez de descartarlo lo encolamos: pedimos folios al SII y emitimos apenas llegan. La respuesta es 202 con un ticket:

{
  "ticketId": "6f1c2b90-33a1-4a5e-8b7d-0c2e5f9a1d44",
  "estado": "Pendiente",
  "tipoDte": 33,
  "ambiente": "Certificacion",
  "posicionEnCola": 1,
  "intentos": 0,
  "documentoId": null,
  "codigoError": null,
  "mensaje": "No hay folios disponibles; se solicitaron al SII.",
  "esErrorTerminal": false,
  "resumen": "Factura 33 — Cliente Ejemplo S.A.",
  "solicitadoEn": "2026-07-27T14:30:12Z",
  "terminadoEn": null,
  "offsetUtcHoras": -4
}

Fijate en lo que no trae: no hay id, no hay folio.

⚠️ Tres formas clásicas de romperse acá:

1. Leer .id de la respuesta sin mirar el status. Con un 202 te queda undefined o null, y como es un 2xx tu manejo de errores no se entera: guardás un documento fantasma. Ramificá siempre por el status code (201 vs 202), no por la presencia de campos. Para los errores, en cambio, el campo estable es el code (§15).
2. Tratar todo lo que no sea 201 como un fallo y reemitir. El documento ya está encolado: reemitir consume otro folio, salvo que mandes el mismo transactionId.
3. Seguir el header Location. No llega: la respuesta pública no reenvía ese header. Leé el ticketId del cuerpo.

Resolver el ticket

GET /api/public/v1/dte/pendientes/{ticketId}        (scope dte:read)

Devuelve el mismo cuerpo, actualizado. Los estados posibles de estado son:

Ritmo de consulta sugerido: igual que el polling de estado — 5 s, 10 s, 20 s, 40 s, 60 s. Consume la misma cuota de rate limit (§17).

Listar los tickets abiertos

GET /api/public/v1/dte/pendientes?estado={n}&pagina=1&tamano=50      (scope dte:read)

Devuelve un array plano, sin envoltorio de paginación: paginá hasta recibir menos elementos que tamano. Si la cola está deshabilitada en el despliegue, responde 200 con un array vacío (no un error).

Cuando el SII no autoriza timbraje

Si el SII directamente no autoriza folios para ese tipo de documento, la emisión no se encola: falla de inmediato con 422 caf.sin-autorizacion. Es terminal — reintentar no cambia nada, hay que gestionarlo ante el SII.

9. Consultar el estado (modelo asíncrono)Copiar

GET /api/public/v1/dte/{id}          (scope dte:read)

Devuelve el mismo cuerpo que la emisión, con estadoSii, glosaSii y trackId actualizados.

Pendiente  → firmado y persistido, todavía no salió al SII (trackId null)
Enviado    → el SII lo recibió, ya hay trackId, falta el veredicto
Aceptado   | AceptadoConReparos | Rechazado   → estado final
ErrorEnvio → error técnico de envío; reintenta solo desde nuestra cola
Anulado    → anulado por nota de crédito

Si llegás a Rechazado o AceptadoConReparos, el motivo está en glosaSii. Es el campo que explica qué objetó el SII.

Ritmo de polling sugerido: primer intento a los 5 s, después backoff (10 s, 20 s, 40 s, 60 s). Cortá en cuanto llegues a un estado final. No hagas polling en loop cerrado: el rate limit es por key y lo vas a topar (§17).

Se puede evitar buena parte de este polling recibiendo un aviso firmado en tu servidor. El contrato está en §18, y la suscripción la das de alta vos, desde el portal.

Aislamiento entre empresas: un id que pertenece a otra empresa responde 404, no 403. La API no confirma la existencia de documentos ajenos.

⚠️ El 404 de esta ruta y el de GET /{id}/xml llegan con el cuerpo vacío, sin code ni title. No intentes leer code de un 404: ramificá por el status.

⚠️ No agregues parámetros de query que no estén documentados. La query se reenvía tal cual al servicio de emisión, y los dos parámetros que existen ahí se comportan distinto:

• ?empresaId=... falla fuerte: 403 dte.cross-tenant-no-autorizado. Una API key nunca puede consultar otra empresa.
• ?ambiente=Produccion falla en silencio, y eso es peor. El override de ambiente solo lo honra un godadmin; para una API key se ignora sin avisar y la consulta se resuelve en el ambiente de la key. Con una key de certificación vas a recibir 200 con el documento de certificación (o 404 si ese id no existe ahí), nunca un error que te diga que el parámetro no se aplicó. Si tu código lo manda "por las dudas", vas a leer datos del ambiente equivocado creyendo que leíste producción.

Ninguno de los dos hace falta: la key ya define empresa y ambiente, y no hay forma de cambiarlos desde el request.

10. Descargar XML y PDFCopiar

XML firmado

GET /api/public/v1/dte/{id}/xml        → 200 application/xml

Devuelve el XML del DTE firmado, con su TED. La firma está garantizada: sin certificado digital activo el documento no se llega a emitir (§8). Es el archivo que corresponde archivar y el que se le entrega al receptor para intercambio.

El XML se sirve en ISO-8859-1 y así lo declara su cabecera. Si lo vas a procesar, respetá esa codificación: reinterpretarlo como UTF-8 rompe las tildes y la eñe, y con eso invalida su propia firma.

PDF

GET /api/public/v1/dte/{id}/pdf?formato=carta   → 200 application/pdf

Si necesitás el ticket térmico de una boleta, pedilo explícitamente con ?formato=80mm. Omitir el parámetro no lo elige por vos.

⚠️ Estos dos endpoints requieren API Key. No los pegues en un correo al receptor: quien tenga la key puede emitir a nombre de tu cliente. Para hacerle llegar el documento al comprador existen los enlaces firmados, acá abajo.

Ambos exigen el scope dte:read.

Enlaces firmados para el comprador

El problema que resuelven. Al comprador hay que entregarle su factura, y tu API Key no puede salir de tu backend. Hasta acá la única salida era descargar el archivo y redistribuirlo vos.

Por eso la respuesta de emisión trae xmlUrl y pdfUrl: enlaces que se abren sin API Key, listos para reenviar por correo o incrustar en tu portal de clientes. Lo que autoriza no es una credencial sino la firma del propio enlace, que lleva vencimiento.

GET /api/public/v1/descargas/dte/{id}/xml?t=…&exp=…&e=…&a=…
GET /api/public/v1/descargas/dte/{id}/pdf?t=…&exp=…&e=…&a=…&formato=carta
GET /api/public/v1/descargas/exportacion/{id}/xml?t=…&exp=…&e=…&a=…
GET /api/public/v1/descargas/exportacion/{id}/pdf?t=…&exp=…&e=…&a=…

Usá la URL tal como viene. No la armes vos, no le cambies parámetros, no la re-firmes: el token cubre el documento y el recurso, así que cualquier retoque la invalida. Los parámetros:

Dónde aparecen los tres campos

ted, xmlUrl y pdfUrl viajan en el cuerpo de cuatro respuestas:

Dónde no aparecen:

• POST /dte → 202. El ticket todavía no tiene documento: no hay nada que firmar ni que descargar. Cuando el ticket se resuelve, consultá GET /dte/{documentoId} y ahí sí vienen.
• POST /dte/{id}/anular y POST /dte/{id}/nota-credito. El cuerpo trae la nota de crédito emitida, pero sin enlaces. Si necesitás mandarle la NC al comprador, consultala aparte con GET /dte/{notaCreditoId} y usá los enlaces de esa respuesta.
• En cualquier respuesta de error.

Cuánto duran y qué pasa al vencer

30 días, por defecto, contados desde que el enlace se firma — no desde que se emitió el documento. En la respuesta de emisión son lo mismo; en la de una consulta posterior, el reloj arranca en esa consulta. El valor exacto viaja en exp, así que no hace falta suponerlo.

Es configuración del despliegue, no del cliente: si necesitás otra ventana, hablalo con soporte.

Pasado el vencimiento el enlace devuelve 403 descarga.token-vencido y deja de servir para siempre — no hay período de gracia.

Renovar un enlace vencido es gratis: volvé a consultar el documento. GET /api/public/v1/dte/{id} (con tu API Key) devuelve xmlUrl y pdfUrl recién firmadas, con un vencimiento nuevo contado desde ese momento. Lo mismo vale para GET /api/public/v1/exportacion/{id}. No hace falta reemitir nada ni pedir nada a soporte.

Por eso conviene generar el enlace cuando el comprador lo pide, y no guardar el de la emisión para reenviarlo meses después.

Errores

Ambos usan el mismo cuerpo de error que el resto de la API (§15), con field: "t". Con un token inválido la respuesta es idéntica exista o no el documento: el token se valida antes de consultar nada, así que probar ids al azar no revela cuáles son reales.

Un 404 acá significa lo de siempre: el documento no existe o no pertenece a esa empresa.

Seguridad: lo que hay que asumir

⚠️ La URL da acceso al documento a cualquiera que la tenga, hasta que vence. No hay login ni segundo factor detrás: el enlace es la llave. Eso es exactamente lo que lo hace útil para mandárselo al comprador, y también lo que obliga a tratarlo con cuidado.

• No la publiques en una página indexable, ni en un repositorio, ni en un ticket público. Un buscador que la encuentre expone la factura de tu cliente.
• Asumí que un reenvío de correo, un log de proxy o una captura de pantalla la propagan. El vencimiento existe justamente porque eso pasa.
• Del lado nuestro, el token no queda archivado: se enmascara antes de guardar la traza de la petición.
• No se puede revocar un enlace suelto. No hay ruta para eso, ni por API ni en el portal: el único corte disponible es rotar el secreto de firma del ambiente, lo que invalida de golpe todos los enlaces vigentes de todas tus emisiones. Si un enlace se filtró y el impacto lo justifica, escribí a soporte para evaluarlo; si no, el enlace deja de servir al vencer.

Cuota

Estas rutas sí consumen rate limit (§17) — son públicas, y sin límite serían un vector de abuso. Como no llevan API Key, la cuota se cuenta por IP del visitante, no contra la de tu integración: los compradores que abren sus facturas no te gastan el presupuesto de emisión.

Si los campos llegan en null

xmlUrl y pdfUrl vienen null cuando la funcionalidad no está configurada en ese ambiente (le falta el secreto de firma al despliegue). En ese caso los cuatro endpoints de descarga rechazan todo enlace con 403 descarga.token-invalido.

No es un error de tu request y no se arregla reintentando. Programá para el caso — if (respuesta.xmlUrl) — y si esperabas tener la funcionalidad, pedila a soporte. El resto de la emisión funciona igual: el documento se emitió, y GET /dte/{id}/xml con tu API Key sigue siendo el camino de siempre.

11. Anular un documentoCopiar

POST /api/public/v1/dte/{id}/anular
X-Api-Key: pk_test_...
Content-Type: application/json     (cuerpo opcional)

Anular es emitir una Nota de Crédito tipo 61 que referencia al documento original con CodRef=1 ("anula documento completo") y marcarlo como anulado. Es una sola llamada.

¿Anular o acreditar parcial? /anular deja el documento sin efecto por su total. Si lo que querés es devolver parte del documento (unas líneas, o un monto) y que el resto siga vigente, no es esto: es POST /{id}/nota-credito.

Lo importante: la referencia la arma el servidor

El cliente no manda tipoDocRef, folioRef ni fechaRef. El servidor lee el documento original y arma la referencia con su tipo, su folio y su fecha de emisión real.

Esto no es una comodidad, es la razón de existir del endpoint. Armar la NC a mano ya provocó una anulación rechazada por el SII: el cliente mandó FchRef con la fecha de hoy en vez de la fecha de emisión del original. El SII rechazó la nota de crédito y el folio se quemó igual.

La NC además espeja el cuerpo del original (detalles, impuestos adicionales, descuentos y recargos globales) para que los montos cuadren peso a peso.

Cuerpo (opcional)

{
  "motivo": "Error en el RUT del receptor"
}

El cuerpo entero es opcional: POST sin body es válido.

Idempotencia: reintentar es seguro

La anulación es idempotente por documento. La clave es el {id} de la URL, no un campo que mandes vos. Consecuencia práctica:

• Reintentar el mismo POST (timeout de red, retry automático de tu cliente HTTP, doble click de un usuario) devuelve la misma nota de crédito.
• No se emite una segunda NC. No se quema otro folio.
• No necesitás mandar transactionId para que esto funcione — de hecho, mandarlo no cambia nada.

Respuesta 201

{
  "documentoAnulado": {
    "id": "b5f8c2e1-7d93-4e8f-a12b-9c4d5e6f7a8b",
    "tipoDte": 33,
    "folio": 1048,
    "fechaEmision": "2026-07-27",
    "estadoSii": "Aceptado"
  },
  "notaCredito": {
    "id": "7c1e9a44-2f60-4a1d-8e33-5b0c9d2f1a77",
    "tipoDte": 61,
    "folio": 312,
    "montoTotal": 1190000,
    "estadoSii": "Pendiente",
    "trackId": null
  }
}

Dos cosas que suelen confundir:

1. documentoAnulado.estadoSii sigue diciendo Aceptado. No es un bug. Para el SII el documento original sigue aceptado: la anulación es comercial (una NC 61 con CodRef=1), no un cambio de estado en el SII. Lo que marca la anulación es el campo anuladoEn del documento (visible en GET /dte/{id}), junto con notaCreditoId.
2. La nota de crédito nace Pendiente, como cualquier emisión: viaja al SII en segundo plano. Si querés confirmar que el SII la aceptó, hacé polling sobre GET /api/public/v1/dte/{notaCredito.id}.

Qué se puede anular

Errores propios de la anulación

Ver la tabla completa en §15; los específicos son emisor.documento-ya-anulado, emisor.tipo-no-anulable, emisor.estado-no-anulable, emisor.sin-folios-nc, emisor.montos-no-reproducibles, emisor.anulacion-nc-descartada y emisor.anulacion-marca-fallida.

12. Devolución parcial: notas de crédito por línea o por montoCopiar

Cuando el cliente devuelve parte de lo facturado —dos de cinco unidades, un descuento posterior, o hay que corregir un dato sin tocar montos— no corresponde anular. Corresponde una nota de crédito parcial, con CodRef=3 (o CodRef=2 si solo se corrige texto), que rebaja el documento sin dejarlo sin efecto.

El flujo recomendado es siempre el mismo: consultar el saldo, después emitir.

12.1 Consultar el saldo acreditable

GET /api/public/v1/dte/{id}/acreditable        (scope dte:read)

Te dice qué queda disponible del documento y cómo se puede acreditar. Sirve especialmente si tu ERP no lleva su propio registro de devoluciones: el servidor ya lo lleva, y así no se desincronizan.

{
  "documento": {
    "id": "b5f8c2e1-7d93-4e8f-a12b-9c4d5e6f7a8b",
    "tipoDte": 33,
    "folio": 1048,
    "fechaEmision": "2026-07-27",
    "montoNeto": 1000000,
    "montoExento": 0,
    "montoTotal": 1190000,
    "montoAcreditado": 200000,
    "saldoAcreditable": 800000,
    "estadoAcreditacion": "Parcial",
    "porcentajeAcreditado": 20
  },
  "puedeAcreditar": true,
  "motivoNoAcreditar": null,
  "modosDisponibles": ["lineas", "monto", "texto"],
  "advertenciaPlazo": null,
  "lineas": [
    {
      "nroLinea": 1,
      "nombreItem": "Consultoría técnica",
      "descripcionItem": null,
      "codigoItem": null,
      "unidadMedida": null,
      "indExe": 0,
      "cantidadOriginal": 5,
      "precioUnitario": 200000,
      "montoItem": 1000000,
      "montoEfectivo": 1000000,
      "cantidadAcreditada": 1,
      "montoAcreditado": 200000,
      "cantidadDisponible": 4,
      "montoDisponible": 800000,
      "acreditable": true,
      "motivoNoAcreditable": null
    }
  ],
  "notasCreditoPrevias": [
    {
      "id": "…", "folio": 310, "fechaEmision": "2026-07-28",
      "montoTotal": 238000, "montoNetoImputado": 200000,
      "codRef": 3, "razonRef": "Devolución de 1 unidad", "estadoSii": "Aceptado",
      "lineasImputadas": [{ "nroLineaOrigen": 1, "cantidad": 1, "monto": 200000 }]
    }
  ]
}

Lo que hay que entender de esta respuesta:

Si modosDisponibles no incluye "lineas", es porque los montos de las líneas de ese documento no son reproducibles a partir de cantidad × precio (típico de documentos importados de otro sistema). Podés acreditar igual, por monto.

⚠️ Un 404 emisor.acreditacion-no-habilitada en esta ruta NO significa que la ruta no exista: significa que el módulo de notas de crédito parciales está apagado para este despliegue. Si lo necesitás, pedilo a soporte.

12.2 Emitir la nota de crédito parcial

POST /api/public/v1/dte/{id}/nota-credito        (scope dte:emit:61)
Content-Type: application/json

{
  "modo": "lineas",
  "motivo": "Devolución de 2 unidades",
  "lineas": [
    { "nroLinea": 1, "cantidad": 2 }
  ],
  "transactionId": "1f0a7d2c-5c3e-4c1f-9b6a-2d8e4f0b7c31"
}

Los tres modos:

La referencia al documento original la arma el servidor, igual que en /anular. Vos nunca mandás tipoDocRef, folioRef ni fechaRef.

12.3 Idempotencia: acá transactionId SÍ importa

A diferencia de /anular —donde un documento se anula a lo sumo una vez, así que la clave se deriva del documento— acá pueden existir N notas parciales legítimas sobre el mismo folio, incluso idénticas (dos devoluciones de 1 unidad el mismo día). El servidor no puede distinguir un reintento de una devolución nueva.

• Mandá un transactionId propio, generado antes de la primera llamada. Con él, reintentar devuelve la misma nota; sin él, un reintento tras un timeout puede emitir una segunda nota y acreditar de más.
• Si se omite, el servidor genera uno interno: la operación funciona, pero perdés la protección contra reintentos.
• El guard de saldo sigue impidiendo acreditar más de lo disponible en cualquier caso.

12.4 Respuesta 201

{
  "notaCredito": { "id": "…", "tipoDte": 61, "folio": 313, "montoTotal": 476000, "estadoSii": "Pendiente", "…": "…" },
  "documentoOrigen": {
    "id": "b5f8c2e1-…", "tipoDte": 33, "folio": 1048,
    "montoAcreditado": 600000, "saldoAcreditable": 400000,
    "estadoAcreditacion": "Parcial", "porcentajeAcreditado": 60
  },
  "imputaciones": [
    { "nroLineaOrigen": 1, "cantidad": 2, "monto": 400000 }
  ]
}

notaCredito tiene el mismo formato que cualquier documento emitido (§8), incluido su id para hacerle polling. documentoOrigen viene con el saldo ya actualizado. En modo monto, imputaciones trae una sola entrada con nroLineaOrigen: null.

12.5 Errores

13. Exportación (110 / 111 / 112)Copiar

POST /api/public/v1/exportacion
GET  /api/public/v1/exportacion/{id}
GET  /api/public/v1/exportacion/{id}/xml
GET  /api/public/v1/exportacion/{id}/pdf

Mismo modelo de autenticación y de errores, pero es un contrato distinto: el receptor es extranjero, los montos van en moneda extranjera y hay un bloque de aduana obligatorio.

Diferencias que importan de entrada:

• El receptor extranjero usa el RUT genérico 55555555-5.
• Si la moneda no es peso chileno, el servidor genera automáticamente el bloque de totales en CLP equivalente a partir de la tasa de cambio.
• Los datos de aduana (país de destino, puerto de embarque y desembarque, modalidad y cláusula de venta, vía de transporte, bultos) salen de catálogos oficiales de aduana. Los códigos no son de invención libre.
• Los códigos de error usan el prefijo exp. en vez de emisor..
• estadoSii es un string, igual que en el DTE nacional ("Pendiente", "Enviado", "Aceptado", "AceptadoConReparos", "Rechazado", "Anulado", "ErrorEnvio"). No compares contra números.
• El PDF de exportación es solo Carta y no admite ?formato=: el bloque de aduana, arancel, moneda extranjera y receptor extranjero no caben en un ticket de 80 mm.
• Anulación: una exportación no se anula con POST /dte/{id}/anular ni con POST /exportacion/{id}/anular (esa ruta no existe). Se emite una NC de exportación (112) referenciando el original.
• Enlaces firmados: POST /exportacion y GET /exportacion/{id} traen xmlUrl y pdfUrl igual que el DTE nacional, apuntando a /descargas/exportacion/.... Mismas reglas de vencimiento y de seguridad (§10). El PDF firmado tampoco admite ?formato=.
• ted llega siempre null en exportación: ese camino todavía no expone el timbre por separado. Está dentro del XML.

Los catálogos de aduana todavía no tienen endpoint público. Hoy se consultan desde el portal. Si necesitás integrarte a exportación, pedí el volcado de los catálogos a soporte — ver Qué no existe todavía.

El contrato campo por campo del cuerpo de exportación está en la referencia OpenAPI (/docs/reference, sección Exportación), generada del mismo contrato que valida el servidor.

14. Paso a producción (go-live)Copiar

Emitir con una key pk_live_* no es solo cambiar la key. Son tres pasos, y dos dependen de nosotros.

Paso 1 — Certificación ante el SII, por cada tipo de documento

El SII exige un proceso de certificación por contribuyente y por tipo de DTE. Lo ejecuta el equipo de Comges; el integrador no lo dispara por API, y no hay endpoint público para consultarlo ni iniciarlo.

Mientras un tipo no esté aprobado, emitirlo en Producción devuelve 403 cert.tipo-no-aprobado-prod, tipo por tipo. Es decir: podés tener la 33 aprobada y la 61 no, y descubrirlo recién al intentar tu primera anulación real.

Pedí la certificación de todos los tipos que vas a emitir, incluida la 61 si vas a anular o acreditar. Es el olvido más común.

Si la verificación de certificación no responde, la emisión falla con 503 cert.servicio-no-disponible: eso sí es reintentable con backoff.

Paso 2 — Cambiar el ambiente del usuario

El ambiente de la key se hereda del usuario que la crea. Para que un usuario pueda crear keys de producción, un administrador de la empresa (con el permiso empresa:usuarios:ambiente) tiene que cambiarle el ambiente operativo desde el portal.

Ese cambio cierra las sesiones abiertas de ese usuario: tiene que volver a entrar.

Paso 3 — Crear una API Key nueva

⚠️ Rotar una key pk_test_ NUNCA la convierte en pk_live_. La rotación conserva el ambiente de la key: solo cambia el secreto. Si rotás tu key de certificación esperando pasar a producción, vas a seguir emitiendo contra Maullín — documentos de prueba, sin validez tributaria — sin ningún error que te avise.

Hay que crear una key nueva después del paso 2, con los mismos scopes.

Checklist de go-live

• Pendiente: Certificación SII aprobada para cada tipo que vas a emitir (depende de Comges).
• Pendiente: Plan de la empresa vigente y con fecha suficiente (depende de Comges).
• Pendiente: Certificado digital de la empresa activo y no vencido (depende de Comges). Si vence, toda emisión corta con 422 emisor.sin-certificado / emisor.certificado-invalido (§8).
• Pendiente: Todos los tipos habilitados para la empresa en Producción (depende de Comges).
• Pendiente: Ambiente del usuario cambiado a Producción (lo hace el administrador de la empresa).
• Pendiente: Key nueva pk_live_* creada (no rotada) y desplegada en tu configuración.
• Pendiente: Tu código manda transactionId en toda emisión.
• Pendiente: Tu código ramifica por el code del error (§15) y maneja el 202 (§8).
• Pendiente: Tu timeout HTTP es mayor al nuestro (§17).
• Pendiente: Verificado que las primeras emisiones reales llegan a Aceptado, y que si no, leés glosaSii.

15. Errores: formato y códigosCopiar

El cuerpo estándar

La mayoría de los errores llega con este cuerpo:

{
  "code": "emisor.sin-folios",
  "title": "No hay folios disponibles para tipo 33 ambiente Certificacion. Suba un CAF nuevo.",
  "detail": null,
  "status": 409,
  "field": "tipoDte",
  "traceId": null
}

Los campos que no aplican viajan como null, no se omiten.

Respuestas que NO usan ese cuerpo

Estas son las excepciones. Si tu manejo de errores asume que siempre hay code, estas lo rompen:

Además, dos respuestas traen el cuerpo recortado: el 401 y el 429 vienen con code y title (el 429 también con status) pero sin traceId; y el 403 plan.vencido trae campos extra (type, detail, fechaVencimiento).

Cómo leer las tablas

• ¿Reintentar? — no significa que el mismo request va a fallar igual: hay que corregir algo. sí (backoff) significa que la causa es transitoria.
• ¿Folio? — lo más importante cuando algo falla en una emisión. no = el documento se rechazó antes de tomar un folio del CAF, así que no perdiste nada y podés corregir y reenviar. sí = el folio ya se consumió (o quedó comprometido) y ese número no vuelve.

Regla general de la emisión nacional: todas las validaciones del cuerpo, del receptor, del detalle, de la guía de despacho, de las fechas, de los largos y de los prerequisitos de la empresa —el certificado digital incluido— corren antes de reservar folio. Si recibiste un 400, un 403, un 422 o un 501 de POST /dte, no se consumió folio.

⚠️ POST /exportacion no cumple esa regla del todo. Sus validaciones de formato también corren antes del folio, pero el certificado digital se carga después de reservarlo: por eso 409 exp.sin-certificado y 500 exp.error-pfx llegan con el folio ya consumido. La columna «¿Folio?» de §15.17 lo marca caso por caso.

15.1 Autenticación, cuota y permisos

Los tres 403 de scope (permiso.requerido, emisor.permiso-tipo-no-autorizado, dte.permiso-faltante) describen la misma causa: la key no tiene el permiso. Cuál de los tres llega depende de qué capa corte primero, así que si programás una rama de "falta permiso", cubrí los tres.

15.2 Estado de la cuenta

15.3 Prerequisitos de la empresa

Nada de esto se puede resolver desde el ERP: son datos o habilitaciones de la empresa emisora. Ninguno consume folio — los dos controles del certificado también corren antes de tomar el folio, a propósito: la firma ocurre después de reservarlo.

15.4 Tipo de documento y ambiente

Ninguno consume folio.

15.5 Validación del cuerpo — receptor

Ninguno consume folio. Todos son 400.

Los códigos emisor.receptor-rut-requerido y emisor.receptor-rut-invalido aparecen en el código fuente pero no son alcanzables desde POST /dte: el guard que devuelve emisor.rut-receptor-invalido corre primero. Programá contra ese código, o contra field == "receptor.rut". Ver §15.19.

15.6 Validación del cuerpo — detalle

Ninguno consume folio. Todos son 400.

15.7 Validación del cuerpo — referencias, impuestos, descuentos y recargos

Ninguno consume folio. Todos son 400.

15.8 Validación del cuerpo — fechas y forma de pago

Ninguno consume folio. Todos son 400.

15.9 Validación del cuerpo — sucursal, actecos y campos propios

Ninguno consume folio.

Los cuatro códigos de campos propios no llevan prefijo de familia. Solo aparecen si la empresa tiene campos propios configurados.

15.10 Validación del cuerpo — guía de despacho (52)

Estos nueve solo aplican al tipo 52. Ninguno consume folio. Todos son 400.

15.11 Cotizaciones de origen

Solo aparecen si el cuerpo trae cotizacionIds. Ninguno consume folio.

15.12 Folios

Es el grupo donde más importa saber si perdiste un folio. En ninguno de estos se consumió folio: el folio se toma después de todas las validaciones y, si algo falla más adelante, el servidor lo libera.

emisor.sin-folios es hoy un camino residual. Cuando no hay folio disponible, el sistema se los pide al SII y espera. Si el folio llega, recibís tu 201 normal. Si no llega a tiempo, la emisión se encola y recibís un 202 con ticketId (ver Respuesta 202): el documento ya está validado y se va a emitir solo. Solo si el SII dice que no autoriza ese tipo vas a ver el 422 caf.sin-autorizacion.

15.13 Consulta de documentos y de tickets

15.14 Códigos que llegan dentro del ticket del 202

Estos no son errores HTTP: viajan en el campo codigoError del cuerpo que devuelve GET /dte/pendientes/{ticketId}, junto con mensaje y esErrorTerminal. La respuesta del endpoint es 200.

esErrorTerminal: true significa: no reintentes ese ticket. Con false, el sistema lo vuelve a tomar solo.

15.15 Anulación — POST /dte/{id}/anular

Y además: emisor.sin-folios-nc (§15.12) y dte.cross-tenant-no-autorizado (§15.13).

15.16 Nota de crédito parcial — GET /dte/{id}/acreditable y POST /dte/{id}/nota-credito

Ninguno consume folio: el saldo se valida antes de reservar.

Y además: dte.permiso-faltante (§15.1) y emisor.sin-folios-nc (§15.12).

El saldo de GET /{id}/acreditable viene en neto, no en total con IVA.

15.17 Exportación (exp.*)

Mismo criterio que la emisión nacional: todo lo que sea 400, 403 o 422 ocurre antes de tomar folio. Las excepciones están marcadas.

Y además: emisor.permiso-tipo-no-autorizado (§15.1) cuando falta dte:emit:{110|111|112}.

La familia exportacion.*

Son las reglas del formato oficial del SII para documentos de exportación: hoy son 109. Todas responden 400 sin consumir folio, y el code nombra exactamente la regla que falló, con el campo en field. Se agrupan por bloque del documento:

No hace falta programar contra cada uno: todos son 400 de validación, ninguno consume folio, y ninguno se arregla reintentando. Lo accionable está en field y en title.

15.18 Resumen: qué reintentar y qué no

15.19 Códigos que no existen

Ninguno de los códigos de esta tabla lo devuelve la API. Aparecen en documentación vieja o en ejemplos de terceros; si tu código tiene una rama para alguno, esa rama no se ejecuta nunca.

15.20 Qué reportar cuando algo no calza

Como traceId hoy solo viaja en las respuestas 500, para cualquier otro error hay que mandar otros datos. La lista completa está en Soporte.

16. Idempotencia y reintentosCopiar

Un timeout de red no te dice si el documento se emitió o no. Sin idempotencia, reintentar duplica documentos y quema folios. Hay tres mecanismos, uno por operación:

Emisión: transactionId

Generá un UUID antes de la primera llamada, guardalo junto a tu orden/factura interna, y mandalo en el cuerpo:

{ "transactionId": "a3bb189e-8bf9-3888-9912-ace4e6543002", "tipoDte": 33, "...": "..." }

Si reintentás con el mismo valor, el servidor devuelve el documento ya emitido en vez de emitir uno nuevo. No consume otro folio. Y si la primera llamada devolvió un 202, reintentar con el mismo transactionId devuelve el mismo ticketId: no encola un segundo documento.

La deduplicación corre después de las validaciones: un cuerpo inválido devuelve 400 aunque repita un transactionId ya usado.

transactionId es opcional pero prácticamente obligatorio en producción. Sin él, un timeout te deja sin forma de saber si reintentar es seguro. Y es lo único que te protege si tratás por error un 202 como un fallo y reemitís.

Anulación: automática, por documento

No necesita transactionId. La clave es el {id} del documento: un documento se anula a lo sumo una vez, así que reintentar el mismo POST /{id}/anular devuelve siempre la misma NC. Ver §11.

Nota de crédito parcial: transactionId, y acá sí hace falta

Un mismo documento puede recibir varias notas parciales legítimas, incluso idénticas. El servidor no puede distinguir un reintento de una devolución nueva. Mandá tu propio transactionId. Ver §12.3.

17. Rate limiting y límites durosCopiar

Rate limit

Dos capas, ambas con ventana deslizante de 60 segundos, y se aplican las dos a la vez:

Al exceder cualquiera de las dos:

HTTP/1.1 429 Too Many Requests
Retry-After: 15
Content-Type: application/json

{"code":"api-publica.rate-limit","title":"Demasiadas solicitudes para esta API key. Reintenta en unos segundos.","status":429}

El header Retry-After siempre viene (en segundos). Respetalo: reintentar antes solo gasta cuota.

Consecuencias prácticas:

• El límite por IP no es un simple respaldo del otro: está siempre activo. Si tu ERP multiempresa usa 5 keys desde el mismo servidor, no tenés 5 × 120 = 600 requests/min: topás a 300 por la IP.
• El polling de estado y el de tickets entran en la misma cuota que la emisión. Con backoff (5/10/20/40/60 s) un documento consume ~5 requests; en loop cerrado consume el presupuesto de una key entera.
• Las descargas firmadas de §10 también consumen cuota, pero como no llevan API Key se cuentan por IP del visitante: los compradores que abren sus documentos no gastan el presupuesto de tu integración.
• GET /health no consume cuota. Usalo para monitores.
• Si necesitás más throughput, hablalo con soporte antes de subir a producción — el límite es configurable por despliegue, no por cliente.

Límites duros del documento (los pone el SII, no nosotros)

Cantidades:

Largos de texto — exceder cualquiera devuelve 400 antes de reservar folio. La única excepción es el motivo de anulación y de nota de crédito, que se trunca en silencio: