Para desarrolladores e integradores
Emite boletas y facturas electrónicas ante el SII desde tu propio software.
Sigue construyendo tu producto: la parte legal y tributaria la ponemos nosotros. Tu backend manda un JSON con el receptor y las líneas; recibe de vuelta el folio, el XML firmado, el PDF y el timbre electrónico.
- El certificado digital se carga una vez, en el alta, y cada emisión se firma del lado del servidor. Tu código nunca toca el .pfx.
- Los folios del CAF se piden al SII y se reservan solos. Cuando no hay, la emisión nacional se encola y se resuelve con un ticket; la de exportación no se encola: responde 409 y hay que cargar el CAF.
- El envío al SII y el ciclo de estados corren en segundo plano. El motivo de un rechazo llega en el mismo documento.
La documentación es pública y no pide registro. El alta de la empresa emisora sí la hacemos nosotros: necesita el certificado digital y la clave tributaria del contribuyente.
Para quién es
Para el equipo que escribe el software, no para el que emite desde una pantalla.
Si estás construyendo un punto de venta, una tienda en línea, un ERP, un sistema de gestión a medida o un vertical —arriendos, consultas médicas, talleres, colegios, gimnasios— y llegaste al punto en que el producto funciona pero tiene que entregar un documento tributario válido en Chile, esta es la parte que te falta.
El muro no es tu código: es el SII. Certificado digital, folios del CAF, firma del XML en el orden exacto, timbre, envío, set de certificación, rechazos que no dicen qué falló. Nada de eso agrega una función a tu producto, y todo eso hay que mantenerlo cada vez que el SII cambia el formato.
Si lo que necesitas es emitir desde una pantalla, con plantillas, punto de venta y contabilidad, no hace falta nada de esto.
Una precisión de alcance, porque el vocabulario tributario chileno es amplio: esta API emite documentos. Los libros contables, el F29 y la contabilidad de la empresa siguen siendo trabajo de un contador, dentro de la plataforma o fuera de ella.
Qué resuelve
Seis sistemas que no vas a tener que construir ni volver a certificar.
Emitir un DTE válido en Chile no es un POST a un webservice. Esta es la lista de lo que hay detrás, y al lado lo que ocupa su lugar.
El certificado digital y la firma del XML
Pedir una semilla al SII, firmarla, canjearla por un token, firmar el documento y el sobre con XMLDSig en el orden correcto, canonicalizar antes de cada digest y custodiar un .pfx con su clave. Cuando algo de eso falla, el SII responde «rechazado por error en firma» y no dice qué parte.
El certificado se carga una vez, en el alta de la empresa, y cada emisión se firma del lado del servidor. Tu código nunca toca el .pfx. Si vence, la emisión nacional corta con un 422 antes de reservar el folio, así que no se pierde ninguno. En exportación el orden es al revés —primero el folio, después el certificado—, y ahí el mismo problema responde 409 o 500 con el folio ya consumido. En los dos casos es un aviso operativo que hay que escalar, no un bug de tu integración.
Los folios del CAF
Pedir timbraje al SII, guardar los archivos CAF, llevar el correlativo, no repetir un folio, no quemarlo cuando se cae la red y decidir qué hacer cuando se acaban a mitad de jornada.
El folio llega definitivo en la respuesta. En emisión nacional, si no hay, el sistema los pide al SII automáticamente y encola la emisión con un ticket; también se puede cargar un CAF a mano desde el portal. Exportación no tiene esa cola: sin folios responde 409 y hay que cargar el CAF antes de reintentar. Si el SII no autoriza timbraje de ese tipo, el error es terminal y hay que gestionarlo ante el SII.
La aritmética del documento y el timbre impreso
El árbol del DTE, el IVA por línea, el neto, el exento, el no facturable, los descuentos y recargos globales, los impuestos adicionales, y después generar el timbre, firmarlo con la clave del CAF y dibujarlo como código PDF417 en dos formatos de impresión.
Envías cantidad y precio unitario, y el servidor devuelve los montos calculados. En emisión nacional el timbre viene en la respuesta, como XML ya firmado —no como imagen del código de barras—, y solo ahí: la consulta posterior lo devuelve en null, y en exportación llega en null incluso al emitir. Si lo necesitas para armar tu propia impresión, guárdalo al emitir o sácalo del XML, que lo contiene. El PDF nacional se descarga en carta o, pidiéndolo con formato 80mm, en ticket térmico; el de exportación es solo carta.
El envío al SII y el ciclo de estados
Armar el sobre, mandarlo, guardar el identificador de envío, consultar el estado, interpretar la glosa y decidir qué se reintenta y qué no.
El envío es automático y en segundo plano. El estado se lee consultando el documento por su id, y cuando el SII rechaza u observa, el motivo llega en el mismo campo. Hay webhooks firmados que avisan cada cambio, pero son una optimización y no un reemplazo de esa consulta: si tu endpoint estuvo caído toda la escalera de reintentos —unas 31 horas— o la suscripción se apagó sola por fallos consecutivos, el estado real sigue estando en el documento.
La certificación ante el SII
El set de pruebas asignado por el SII, el set de simulación, el intercambio de información, las muestras de impresión, la declaración de cumplimiento y el registro como emisor electrónico. Por cada tipo de documento.
En certificación desarrollas y pruebas la integración completa sin haber pasado el set de pruebas. La certificación es por contribuyente y por tipo de documento, la ejecuta nuestro equipo y solo se exige en producción. Lo decimos completo: el trámite no desaparece, cambia de manos.
La entrega del documento al comprador
Alojar el XML y el PDF, controlar quién los abre, ponerles vencimiento y no exponer nunca la credencial que los genera.
La respuesta de emisión y la de consulta traen enlaces firmados al XML y al PDF, que se abren sin API Key y se le reenvían al comprador. Por defecto duran 30 días desde que se firman —el vencimiento exacto viaja dentro del enlace, y el plazo es configuración del despliegue, no tuya— y volver a pedirlos es gratis: se consulta el documento y llegan recién firmados. Programa el caso en que lleguen en null: pasa si el ambiente no tiene la firma configurada, y además no vienen en el 202 ni en las respuestas de anular y de nota de crédito.
Nada de esta lista es imposible: hay equipos en Chile que la construyeron entera y les funciona. La pregunta no es si puedes, sino si quieres que el roadmap de tu producto dependa del próximo cambio de formato del SII.
El primer request
Un POST, y la única bifurcación que no se puede omitir.
El cuerpo mínimo de una emisión son un tipo de documento, un receptor y una línea de detalle. El resto lo pone el servidor: los totales, el folio, el XML, la firma y el timbre. Abajo están los dos cuerpos que hace falta tener resueltos desde el primer día —la boleta, que es el más corto, y la factura, que exige tres campos más del receptor—, las dos respuestas posibles y el código que las cierra.
curl -sS https://api-publica.dtecomges.cl/api/public/v1/dte \
-H "X-Api-Key: pk_test_a1b2c3d4_TU_SECRETO" \
-H "Content-Type: application/json" \
--max-time 60 \
-d '{
"transactionId": "a3bb189e-8bf9-3888-9912-ace4e6543002",
"tipoDte": 39,
"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 }
]
}'{
"transactionId": "5c4f0b7e-2a19-4d6c-8f31-7b0e2c9a4d55",
"tipoDte": 33,
"receptor": {
"rut": "96790240-3",
"razonSocial": "Cliente Ejemplo S.A.",
"giro": "Comercio al por mayor",
"direccion": "Av. Providencia 1234, of. 501",
"comuna": "Providencia"
},
"formaPago": 2,
"fechaVencimiento": "30-11-2026",
"detalles": [
{
"nroLinea": 1,
"nombreItem": "Consultoría técnica",
"cantidad": 1,
"unidadMedida": "UN",
"precioUnitario": 1000000
},
{
"nroLinea": 2,
"nombreItem": "Licencia de software",
"cantidad": 3,
"unidadMedida": "UN",
"precioUnitario": 25000
}
]
}// 201 Created — había folio. Abreviado: el cuerpo real trae bastante más.
{
"id": "b5f8c2e1-7d93-4e8f-a12b-9c4d5e6f7a8b",
"tipoDte": 39,
"folio": 1048,
"ambiente": "Certificacion",
"montoNeto": 7200,
"montoIva": 1368,
"montoTotal": 8568,
"estadoSii": "Pendiente",
"trackId": null,
// Solo viaja en la emisión nacional. La consulta posterior lo devuelve en
// null, y en /exportacion llega en null incluso al emitir. Guárdalo ahora.
"ted": "<TED version=\"1.0\">…</TED>",
// Pueden llegar en null: no los des por hechos. No vienen en el 202 ni en
// las respuestas de anular y de nota de crédito.
"xmlUrl": "‹enlace firmado, se abre sin API Key; su vencimiento viaja en exp›",
"pdfUrl": "‹enlace firmado, se abre sin API Key; su vencimiento viaja en exp›"
}
// 202 Accepted — no había folio. El documento ya está validado y encolado.
// No trae id, ni folio, ni ted, ni enlaces: todavía no hay documento.
{
"ticketId": "6f1c2b90-33a1-4a5e-8b7d-0c2e5f9a1d44",
"estado": "Pendiente",
"posicionEnCola": 1,
"documentoId": null,
"esErrorTerminal": false,
"mensaje": "No hay folios disponibles; se solicitaron al SII."
}const API = "https://api-publica.dtecomges.cl/api/public/v1";
const cab = {
"X-Api-Key": process.env.COMGES_API_KEY,
"Content-Type": "application/json",
};
// transactionId: un UUID que generas TÚ antes de la primera llamada.
// Reintentar con el mismo valor no emite dos veces ni quema otro folio.
// El timeout del cliente va POR ENCIMA del del servidor: 45 s para emitir,
// consultar, XML y anular; 60 s para el PDF.
const r = await fetch(API + "/dte", {
method: "POST",
headers: cab,
signal: AbortSignal.timeout(60_000),
body: JSON.stringify({ transactionId, tipoDte: 39, receptor, detalles }),
});
// Ramifica por el status code, nunca por la presencia de campos.
if (r.status === 201) {
await guardarDocumento(await r.json());
} else if (r.status === 202) {
const ticket = await r.json(); // sin id, sin folio, sin enlaces
await encolarSeguimiento(ticket.ticketId);
} else {
const err = await r.json().catch(() => null);
throw new Error((err && err.code) || "HTTP " + r.status);
}
function guardarDocumento(dte) {
// El timbre solo viaja en la emisión nacional: la consulta lo devuelve en
// null y en /exportacion llega en null incluso al emitir.
// xmlUrl y pdfUrl pueden venir en null. No los des por hechos.
return guardar({
documentoId: dte.id,
folio: dte.folio,
ted: dte.ted ?? null,
xmlUrl: dte.xmlUrl ?? null,
pdfUrl: dte.pdfUrl ?? null,
});
}
// Así se cierra el 202. Con backoff: 5, 10, 20, 40 y 60 segundos.
async function resolverTicket(ticketId) {
const t = await (
await fetch(API + "/dte/pendientes/" + ticketId, { headers: cab })
).json();
if (t.estado === "Completado") {
// Solo ahora hay documento, y su consulta trae los enlaces al día.
const d = await fetch(API + "/dte/" + t.documentoId, { headers: cab });
return guardarDocumento(await d.json());
}
if (t.estado === "Error" && t.esErrorTerminal) throw new Error(t.codigoError);
if (t.estado === "Cancelado") throw new Error("ticket.cancelado");
return "reintentar"; // Pendiente o Procesando
}El 202 no es un caso de borde
Es el caso normal de un contribuyente nuevo: el SII entrega folios de a poco, a veces de a uno. Una integración que asume 201 siempre produce documentos fantasma el primer día, porque leer el id de un 202 devuelve vacío y, como es un 2xx, tu manejo de errores no se entera. El ticket se cierra consultando la ruta de pendientes. Es propio de /dte: exportación no encola.
En factura, el receptor lleva tres campos más
Copiar el ejemplo de boleta y cambiarle el tipo a 33 devuelve un 400. En factura afecta y en factura exenta, el giro, la dirección y la comuna del receptor son obligatorios: los exige el SII. No se consume folio, pero tampoco se emite nada hasta completarlos.
En la factura exenta 34, marca cada línea
Hay que mandar el indicador de exención en línea por línea: el servicio no lo deduce del tipo de documento. Si falta, la línea suma al neto y el documento sale con neto positivo e IVA cero, descuadrado, y el SII lo rechaza con el folio ya consumido. Es la trampa propia de este tipo.
En boleta, el precio unitario va neto
El servicio le suma el IVA al construir el documento. Si mandas el precio con IVA ya incluido, la boleta sale por un 19 % de más. En el ejemplo: 7.200 de neto, 1.368 de IVA, 8.568 que paga el cliente en caja.
Los largos del SII no se truncan solos
Tres rompen con datos comerciales chilenos perfectamente normales: la unidad de medida acepta cuatro caracteres —UN, KG y LT sirven; UNIDAD, KILOS y LITROS no—, el giro del receptor cuarenta y su comuna veinte. Exceder cualquiera devuelve un 400 antes de reservar folio, y no se emite ninguna línea. Mapéalos en tu sistema antes de llamar.
Tu timeout va por encima del nuestro
El servidor corta a los 45 segundos al emitir, consultar, descargar el XML y anular, y a los 60 en el PDF. Configura el tuyo más arriba, por ejemplo 60 y 75. Un timeout más corto que el nuestro es la forma clásica de creer que algo falló cuando en realidad se emitió, y es la otra razón por la que el transactionId no es opcional.
Las rutas que toca una integración de facturación
Son 17 rutas de negocio más el health check. Estas son las que se usan todos los días; el contrato campo por campo está en la referencia.
POST/dte
dte:emit:{tipo}
Emite un documento nacional. Devuelve 201 con el folio definitivo, o 202 con un ticket si no había folio.
GET/dte/{id}
dte:read
El documento y su estado ante el SII. El motivo de un rechazo está en glosaSii, y los enlaces de descarga vuelven recién firmados. El ted llega siempre en null.
GET/dte/pendientes/{ticketId}
dte:read
Resuelve el ticket que devolvió un 202. Cuando el estado es Completado, trae el documentoId con el que sigue todo lo demás.
GET/dte/{id}/xml
dte:read
El XML firmado, con su timbre adentro. Se sirve en ISO-8859-1 y así lo declara: reinterpretarlo como UTF-8 rompe las tildes e invalida la firma.
GET/dte/{id}/pdf
dte:read
El PDF. Carta si no pides nada, también en boleta; el ticket térmico se pide con formato=80mm.
POST/dte/{id}/anular
dte:emit:61
Anula el documento completo con una nota de crédito que arma el servidor. Es idempotente por documento: repetirla devuelve siempre la misma nota.
POST/exportacion
dte:emit:{110|111|112}
Emite exportación, con su propio contrato: receptor extranjero, moneda con conversión y bloque de aduana. Sus consultas y descargas cuelgan de /exportacion/{id}, y su PDF es solo carta. No tiene cola de folios: sin folios responde 409, nunca un 202.
El scope de lectura cubre todas las consultas, así que una key que solo emite no puede leer lo que emitió.
Tipos de documento
Los diez tipos que emite la API.
Los nacionales —33, 34, 39, 41, 52, 56 y 61— salen todos por el mismo endpoint de emisión y el tipo se elige con un campo del cuerpo. Los de exportación —110, 111 y 112— tienen su propio endpoint, porque el contrato es distinto: receptor extranjero, moneda con conversión y bloque de aduana.
- 33Factura electrónica
dte:emit:33/dte
- 34Factura exenta
dte:emit:34/dte
- 39Boleta electrónica
dte:emit:39/dte
- 41Boleta exenta
dte:emit:41/dte
- 52Guía de despacho
dte:emit:52/dte
- 56Nota de débito
dte:emit:56/dte
- 61Nota de crédito
dte:emit:61/dte
- 110Factura de exportación
dte:emit:110/exportacion
- 111Nota de débito de exportación
dte:emit:111/exportacion
- 112Nota de crédito de exportación
dte:emit:112/exportacion
- Cada tipo pide su propio scope en la API Key. Anular exige el scope de la nota de crédito 61, porque una anulación es una nota de crédito: no existe un scope de anulación.
- El scope de lectura cubre todas las consultas —detalle, XML, PDF y tickets—, así que tener permiso para emitir no habilita a leer. Una key típica de facturación lleva tres scopes.
Lo que esta API no emite
El tipo 43, liquidación-factura, y el 46, factura de compra, responden 501 y no consumen folio. No hay fecha comprometida para ninguno de los dos. La boleta de honorarios electrónica tampoco forma parte de esta API.
Documentación
La documentación ya está escrita, publicada y abierta.
No hay que pedir acceso ni registrarse para leerla. Esta página explica qué resuelve la API y cómo se pide el alta; el contrato exacto de cada endpoint vive allá, generado del mismo esquema que valida el servidor.
- Guías por temaAutenticación, ambientes, emisión por tipo de documento, estados, descargas, errores, webhooks y paso a producción.
- Empezar de ceroEl recorrido corto: de la API Key al primer documento emitido en certificación.
- Referencia OpenAPIExplorador interactivo, campo por campo, generado del mismo contrato que valida el servidor.
- llms.txtEl índice de la documentación en texto plano, para asistentes y agentes de programación.
- llms-full.txtLa documentación completa en un solo archivo de texto, para cargarla entera en el contexto de un modelo.
Si estás leyendo esto desde un asistente y necesitas el contenido completo para responder una integración, el volcado en texto plano está en llms-full.txt, en el mismo dominio de la documentación.
Lo que no desaparece
Lo que la API no te quita, dicho antes de que empieces.
Media internet dice que integrar facturación electrónica es cambiar una línea. No lo es. Estas son las partes que igual te van a tocar, y ninguna es código.
El certificado digital y la clave tributaria son del contribuyente
El alta de la empresa emisora necesita el RUT, la clave tributaria del SII, el archivo .pfx del certificado, su clave y el RUT del titular. Son credenciales reales, y entregarlas es una decisión del cliente final, no del integrador. En la práctica es el paso que más tarda de todo el proyecto: coordínalo antes de comprometer una fecha.
El alta no es autoservicio, y no hay ambiente de juguete
No existe endpoint público de registro: el alta la ejecuta nuestro equipo, y hasta que ese paso no está hecho no hay portal, no hay usuario y no hay API Key. Firmar es obligatorio y no hay ningún camino que guarde un DTE sin firma, así que incluso el ambiente de certificación necesita el certificado real de la empresa.
Los folios los entrega el SII, no nosotros
A un contribuyente nuevo se los entrega de a poco, a veces de a uno. Por eso existe la respuesta 202 en la emisión nacional, y por eso hay que manejarla desde el primer día. Exportación no la tiene: sin folios responde 409 y el CAF se carga antes de reintentar. Si el SII no autoriza timbraje de un tipo, la emisión falla en firme y se resuelve ante el SII, no reintentando.
La API se llama desde tu backend
No habilita CORS. La empresa emisora sale del claim de la API Key, así que quien tenga esa key puede emitir documentos tributarios a nombre de tu cliente: una key en un navegador o dentro de una app móvil es una key comprometida. Para el comprador existen los enlaces firmados.
Los webhooks son una optimización, no un reemplazo del polling
Ahorran consultas, pero la entrega no está garantizada: son siete intentos repartidos en unas 31 horas, y a los veinte fallos consecutivos la suscripción se apaga sola y hay que reactivarla desde el portal. Si eso pasa, el estado real sigue estando en la consulta del documento, así que consérvala como respaldo. Las suscripciones se administran desde el portal, no por API.
Los certificados vencen, y muerden después
Un certificado digital dura entre uno y tres años, así que una integración que venía funcionando hace meses corta de un día para otro. En emisión nacional el corte es limpio: 422 antes de reservar el folio. En exportación no: el folio se toma primero, y el mismo problema responde 409 o 500 con el folio ya consumido. Es un aviso operativo que hay que escalar, no un error de validación de tu request.
El reloj del plan arranca en el alta, no cuando empiezas a integrar
Toda empresa nueva se crea con un plan Trial de 30 días contados desde el alta. Si el alta se pide mucho antes de que el software esté listo, el plan puede vencer en pleno desarrollo y toda emisión pasa a responder 403 con el código de plan vencido: bloquea emitir, anular, las notas de crédito y las consultas de documentos. Pide el alta con el proyecto encaminado y coordina la vigencia con nosotros.
Rotar una API Key no tiene ventana de gracia
Al rotar, el secreto anterior deja de servir en el mismo instante: no hay período en que las dos versiones funcionen. Planifícalo como un despliegue coordinado —guardas el secreto nuevo, despliegas y solo entonces rotas—, no como un cambio en caliente. Y al revés: revocar tarda hasta 30 segundos en propagarse, porque la validación positiva se cachea.
Y lo que la API pública no hace hoy
- No hay alta de empresa por API: la ejecuta nuestro equipo.
- No hay administración de webhooks por API. Se crean, se prueban y se rotan desde el portal.
- No se emiten los tipos 43 ni 46: responden 501, sin fecha comprometida.
- No hay listado de documentos con filtros. Se consultan por id, así que guarda el id que devuelve la emisión.
- No hay emisión en lote: un documento por request.
- No existen enlaces de descarga públicos y permanentes, y no van a existir: están descartados por diseño.
- No hay PDF de exportación en 80 mm: exportación se renderiza solo en carta.
- No hay catálogos de aduana por API: los códigos de país, puerto, moneda, modalidad y cláusula de venta se consultan en el portal o se piden por escrito.
- No se recupera el timbre de un documento ya emitido: viaja una sola vez, en la respuesta de la emisión nacional, o dentro del XML.
- No hay ventana de gracia al rotar una API Key: el secreto anterior muere de inmediato.
- No se consulta ni se dispara la certificación ante el SII por API.
- No se convierte una key de certificación en una de producción: se crea una nueva.
De la prueba a producción
Siete pasos. Dos son tuyos y toman minutos.
Los otros cinco no dependen de tu código. Conviene saber cuáles son antes de comprometer una fecha con tu cliente.
- 1La empresa emisora
Reunir los datos del contribuyente
RUT, clave tributaria del SII, certificado digital .pfx, su clave y el RUT del titular. Si la empresa todavía no tiene certificado digital, ese es un trámite propio del mercado de firma electrónica, previo y ajeno a esta integración.
- 2Comges
Alta de la empresa
Con esos datos se valida el certificado y la clave tributaria, y se traen del SII la razón social, las sucursales y las actividades económicas. Si algo está mal, el alta falla completa: no queda una empresa a medias.
- 3Comges
Crear el usuario administrador
Sin usuario no hay portal ni API Keys.
- 4Comges
Habilitar los tipos de documento
Por empresa y por ambiente. Si falta, emitir ese tipo devuelve un 403 aunque la key tenga el scope.
- 5Tú, en el portal
Crear la API Key
Nombre, scopes y expiración opcional. El secreto se muestra una sola vez: la base guarda solo su hash, y no hay forma de recuperarlo. Toma minutos.
- 6Tú
Emitir el primer documento de prueba
Un POST con la key de certificación. La integración completa se desarrolla acá, contra el ambiente de pruebas del SII, sin haber pasado el set de certificación. Toma minutos.
- 7Comges y tú
Paso a producción
Tres cosas, y dos no son tuyas: la certificación ante el SII por cada tipo de documento, que ejecutamos nosotros; el cambio de ambiente del usuario en el portal, que hace un administrador de tu empresa; y crear una API Key nueva. Del lado del código es cambiar el valor de una variable de entorno: la URL base no cambia.
Rotar una key de certificación nunca la convierte en una de producción
La rotación conserva el ambiente y solo cambia el secreto. Si rotas esperando pasar a producción, sigues emitiendo documentos de prueba sin validez tributaria, y no hay ningún error que te avise.
Pide la certificación de todos los tipos que vas a emitir
Incluida la nota de crédito 61, si vas a anular o acreditar. Es el olvido más común: se puede tener la factura aprobada y la nota de crédito no, y descubrirlo recién en la primera anulación real.
No publicamos plazos para el alta, la habilitación de tipos, la certificación ni la entrega de folios. Dependen del SII y de qué tan rápido el contribuyente entrega sus credenciales, y no vamos a inventar una cifra. Si necesitas una fecha para planificar, pídela por escrito con el RUT y los tipos de documento, y te respondemos con el estado real de ese contribuyente.
Precio y alta
El acceso a la API va incluido en el plan.
$66.000 al año, por RUT certificado. Valor neto, más IVA.
El acceso a la API pública con API Keys está en la lista de lo que incluye el Plan Pyme DTE Comges, junto con el punto de venta, el módulo contable y remuneraciones. Es el único plan que publicamos, y no cobra por documento emitido.
Si vas a integrar varios RUT de clientes distintos, o si tu volumen justifica revisar el límite de peticiones por minuto, eso se conversa: el límite es configurable por despliegue, no por cliente.
Antes de pedir el alta, mira el reloj: toda empresa nueva se crea con un plan Trial de 30 días contados desde el alta, no desde que empiezas a integrar. Si vence en pleno desarrollo, toda emisión responde 403 con el código de plan vencido, y se resuelve renovando el plan, no reintentando. Por eso conviene pedir el alta con el proyecto ya encaminado.
El alta la hacemos nosotros. Escríbenos con cuatro cosas:
- 1El RUT de la empresa que va a emitir.
- 2Qué tipos de documento necesitas, incluida la nota de crédito 61 si vas a anular.
- 3Si la empresa ya tiene certificado digital vigente, o todavía no.
- 4Cuándo esperas estar integrando, para coordinar la vigencia del plan y que no se te venza en pleno desarrollo.
Te respondemos con el estado real de ese contribuyente. Mientras tanto no hace falta pedir permiso para leer nada: la documentación y la referencia OpenAPI son públicas.
Preguntas frecuentes
¿Cómo emito boletas electrónicas en Chile desde mi propio sistema?
Con un POST a nuestra API pública y una API Key en el header X-Api-Key. El cuerpo lleva el tipo de documento, el receptor y las líneas de detalle; en boleta el precio unitario va neto y el servicio suma el IVA. La respuesta 201 trae el folio definitivo, el timbre firmado y enlaces al XML y al PDF, que pueden llegar en null. Si todavía no hay folio, llega un 202 con un ticket.
¿Puedo registrarme y probar la API por mi cuenta?
No. No existe endpoint público de registro ni formulario de autoservicio: el alta de la empresa emisora la ejecuta el equipo de Comges y exige el certificado digital .pfx real del contribuyente, su clave y la clave tributaria del SII. Hasta que ese paso no está hecho no hay portal, no hay usuario y no hay API Key. Ni siquiera el ambiente de certificación se abre sin eso.
¿Dónde está la documentación para desarrolladores?
Publicada y abierta, sin pedir acceso: las guías por tema están en https://new.dtecomges.cl/docs/guides, el explorador interactivo de la referencia OpenAPI en https://new.dtecomges.cl/docs/reference, y para modelos de lenguaje hay un llms.txt y un llms-full.txt en el mismo dominio. Esta página resume qué resuelve la API y cómo se pide el alta; el contrato exacto de cada endpoint vive allá y se genera del mismo esquema que valida el servidor.
¿Hay SDK o librería cliente?
La integración es HTTP y JSON: un POST con la API Key en un header y un cuerpo con el receptor y las líneas. Cualquier cliente HTTP sirve, en cualquier lenguaje. La referencia se publica como OpenAPI, generada del mismo esquema que valida el servidor, así que puedes generar tu propio cliente desde ese contrato si tu lenguaje lo permite.
¿Me tengo que certificar yo ante el SII?
La certificación ante el SII la ejecuta el equipo de Comges: no se dispara ni se consulta por API. El trámite no desaparece, porque el SII certifica por contribuyente y por tipo de documento, y solo se exige en producción. En certificación desarrollas la integración completa sin haber pasado el set de pruebas. Si un tipo no quedó aprobado, emitirlo en producción responde 403.
¿Necesito comprar un certificado digital y quién lo guarda?
Sí: el contribuyente que emite necesita su propio certificado digital .pfx vigente. Se entrega una sola vez en el alta, junto con su clave y el RUT del titular, que se informa aparte porque no se lee del archivo. Queda guardado del lado de Comges y tu código nunca lo maneja. Cuando vence, la emisión nacional corta con un 422 antes de tomar folio; la de exportación lo toma antes y lo pierde.
¿Cómo consigo folios (CAF) y qué pasa cuando se acaban?
No los pides tú. En emisión nacional, cuando no hay folio disponible, el sistema los solicita al SII automáticamente y encola la emisión: recibes un 202 con un ticket y el documento sale apenas llega el folio. Exportación no tiene esa cola: responde 409 y el CAF se carga desde el portal antes de reintentar. Si el SII no autoriza timbraje de ese tipo, la respuesta es terminal y requiere gestión ante el SII.
¿Hay un ambiente de pruebas para no emitir documentos reales?
Sí. Una API Key de certificación apunta al servidor Maullín del SII y los documentos que emitas ahí no tienen validez tributaria. La URL base es la misma para los dos ambientes: el ambiente lo determina la key, no el host ni el cuerpo del request. Lo que sí hace falta antes es que la empresa esté dada de alta con su certificado digital real: no hay sandbox al que entres solo con un correo.
¿Por qué recibí un 202 y no un 201 al emitir?
Porque no había folio disponible. El documento ya fue validado y quedó encolado: el sistema pide folios al SII y emite apenas llegan. Es el caso normal de un contribuyente nuevo, porque el SII los entrega de a poco. La respuesta trae un ticketId y no trae id ni folio. Ramifica siempre por el status code, nunca por la presencia de campos.
¿Cómo resuelvo el ticket que devuelve un 202?
Consultando la ruta de pendientes con ese ticketId, con el scope de lectura. Devuelve el mismo cuerpo actualizado: mientras el estado sea Pendiente o Procesando se sigue consultando, con backoff de 5, 10, 20, 40 y 60 segundos. Cuando llega a Completado trae el documentoId, y ese es el id definitivo del documento. Si el estado es Error y el error es terminal, no reintentes: hay que gestionarlo.
¿Qué campos exige una factura que no exige una boleta?
Tres del receptor: giro, dirección y comuna. Los pide el SII en factura afecta y en factura exenta, así que copiar el ejemplo de una boleta y cambiarle el tipo devuelve un 400 de receptor incompleto, sin consumir folio. En la factura exenta hay además que marcar cada línea de detalle como exenta: el servicio no lo deduce del tipo de documento.
¿Cómo evito emitir dos veces el mismo documento?
Manda un transactionId, un UUID que generas tú antes de la primera llamada, en cada emisión. Reintentar con el mismo valor devuelve el documento ya emitido sin consumir otro folio, y si la primera respuesta fue un 202 devuelve el mismo ticket. La anulación ya es idempotente por documento sin que mandes nada: repetirla devuelve siempre la misma nota de crédito.
¿Qué hago cuando el SII rechaza un documento?
Consulta el documento por su id. Si el estado ante el SII es Rechazado o AceptadoConReparos, el motivo está en glosaSii, que es el único lugar donde el SII explica por qué; el trackId identifica el envío. Si el estado es ErrorEnvio, es un problema técnico y se reintenta solo. Un rechazo no se arregla reenviando el mismo documento: se corrige el dato y se emite de nuevo.
¿Puedo llamar la API desde el navegador o desde una app móvil?
No. La API no habilita CORS y está pensada para tu backend. La empresa emisora sale del claim de la API Key, así que quien tenga esa key puede emitir documentos tributarios a nombre de tu cliente: no debe salir de tu servidor. Para que el comprador acceda a su documento existen los enlaces firmados de XML y PDF, que se abren sin credencial.
¿Cómo le entrego el XML y el PDF al comprador sin exponer mi API Key?
La respuesta de emisión y la de consulta traen xmlUrl y pdfUrl: enlaces firmados que se abren sin credencial, hechos para reenviárselos al comprador. Duran 30 días por defecto, plazo que fija el despliegue, y renovarlos es gratis volviendo a consultar el documento. Pueden llegar en null, y no vienen en el 202 ni al anular, así que programa ese caso. No los publiques en páginas indexables: el enlace es la llave.
¿Cómo verifico la firma de un webhook de DTE Comges?
Cada entrega trae el header X-Comges-Signature con un timestamp y una firma v1, que es un HMAC SHA-256 del secreto sobre el timestamp, un punto y el cuerpo crudo. Es el mismo esquema que usa Stripe. Firma sobre los bytes crudos, rechaza timestamps de más de cinco minutos y compara en tiempo constante. La documentación publica un vector de prueba fijo para verificar tu implementación sin recibir nada.
¿Cuál es el rate limit de la API?
Dos capas simultáneas, ambas con ventana deslizante de 60 segundos: 120 peticiones por minuto por credencial y 300 por minuto por IP de origen. Se aplican las dos, así que cinco keys desde el mismo servidor topan en 300, no en 600. Al exceder llega un 429 con el header Retry-After, en segundos, que siempre viene. El límite es configurable por despliegue, no por cliente.
¿Qué timeout tengo que configurar en mi cliente HTTP?
Uno más alto que el nuestro. El servidor corta a los 45 segundos al emitir, consultar, descargar el XML y anular, y a los 60 en el PDF, así que configura 60 y 75. Un timeout más corto es la forma clásica de creer que algo falló cuando en realidad se emitió. En el PDF, además, un 504 puede llegar como HTML: no lo parsees como JSON.
¿Qué pasa cuando roto o revoco una API Key?
Al rotar, el secreto anterior deja de servir de inmediato: no hay ventana de gracia ni período en que las dos versiones convivan, así que planifícalo como un despliegue coordinado y no como un cambio en caliente. Al revocar pasa lo contrario: la validación positiva se cachea, así que la revocación tarda hasta 30 segundos en propagarse. Rotar tampoco cambia el ambiente de la key.
¿Cómo paso mi integración de certificación a producción?
Del lado del código es cambiar el valor de una variable de entorno: la URL base no cambia. Además hacen falta tres cosas: la certificación ante el SII de cada tipo de documento, que ejecuta Comges; el cambio de ambiente del usuario en el portal, que hace un administrador de tu empresa; y crear una API Key nueva. Rotar una key de certificación nunca la convierte en una de producción.
¿Cuánto tarda desde que pido el alta hasta emitir mi primer documento?
La parte que te toca —crear la API Key y emitir en certificación— son minutos. Lo que tarda está antes y no depende del código: que el contribuyente entregue su certificado digital y su clave tributaria, que en la práctica es el paso más largo, y el alta, la habilitación de tipos y la certificación ante el SII. No publicamos plazos para esos pasos porque no dependen solo de nosotros.
¿Cuánto cuesta emitir DTE por API?
El acceso a la API va incluido en el Plan Pyme DTE Comges: $66.000 al año, por RUT certificado, valor neto más IVA, con documentos y usuarios ilimitados. Es el único plan que publicamos, y no cobra por documento emitido. Si vas a integrar varios RUT de clientes distintos o necesitas más peticiones por minuto que el límite por defecto, escríbenos y lo revisamos antes de que subas a producción.
¿El plan puede vencerse mientras todavía estoy integrando?
Sí, y es un tropiezo común. Toda empresa nueva se crea con un plan Trial de 30 días contados desde el alta, no desde que empiezas a escribir código. Si vence, toda emisión responde 403 con el código de plan vencido, y también quedan bloqueadas la anulación, las notas de crédito y las consultas. Se resuelve renovando: pide el alta con el proyecto ya encaminado.
¿Por qué no usar una librería open source y hablar directo con el SII?
Es una alternativa real y hay equipos en Chile que la usan en producción. La diferencia no es el código: una librería te resuelve el armado y la firma del XML, pero el certificado digital, el timbraje, la certificación por tipo de documento, el ciclo de estados ante el SII y los reintentos sobre un folio irrepetible siguen siendo tuyos, y hay que mantenerlos cada vez que el SII cambia el formato.
¿Qué tipos de DTE emite la API y cuáles no?
Diez tipos: 33, 34, 39, 41, 52, 56 y 61 por el endpoint de emisión nacional, y 110, 111 y 112 de exportación por su propio endpoint. No se emiten el 43, liquidación-factura, ni el 46, factura de compra: la API responde 501, sin consumir folio y sin fecha comprometida. Cada tipo pide su propio scope en la API Key, y anular exige el scope de la nota de crédito 61.
¿En qué se diferencia emitir una exportación de emitir un DTE nacional?
Tiene endpoint y contrato propios: receptor extranjero, moneda con conversión y un bloque de aduana con códigos de catálogos oficiales que aún no se consultan por API. Además, el certificado se verifica después de tomar el folio, así que uno vencido lo pierde; sin folios responde 409, sin cola ni 202; el timbre llega en null incluso al emitir; el PDF es solo carta; y no se anula con /anular, sino con una nota de crédito de exportación.
¿El SII de esta página es el mismo SII español?
No. Acá SII es el Servicio de Impuestos Internos de Chile, el organismo que autoriza el timbraje de folios y certifica a los emisores electrónicos. No es el Suministro Inmediato de Información de la Agencia Tributaria española, que es otro régimen, otro formato y otro país. Esta API emite documentos tributarios electrónicos chilenos y no sirve para el SII español.
¿Te mostramos cómo queda tu empresa adentro?
Escríbenos por WhatsApp o déjanos tus datos. Te hacemos una demostración con tu propia realidad, sin compromiso.
O escríbenos a dtecomges@comges.cl