Campos, validación y límites

Usa esta guía para preparar los datos de una factura 33 o 34, una guía 52 o una nota 56 o 61 que corrige montos de una factura exenta 34. Indica qué campos debes enviar, sus límites y cómo corregir una petición rechazada por sii.dte.previsualizar. Previsualizar te permite revisar el documento antes de firmarlo y emitirlo.

Si necesitas el flujo completo, consulta Facturas 33 y 34, Guías de despacho o Anular o corregir. Las boletas tienen sus propias reglas.

Reglas de la API

Los límites de esta página son los que acepta Connect para estos documentos. El formato DTE del SII y el schema XML oficial contemplan otros campos y combinaciones que esta API no admite. Para la estructura exacta de tu petición, consulta la referencia de previsualización.

Las facturas afecta 33 y exenta 34 comparten las reglas de campos de esta API. En ambas, tipoCompra y tipoVenta deben ser "del_giro", y condicionPago.formaPago debe ser "credito".

Si los datos reales de tu documento requieren un campo o un valor que esta API no admite, utiliza una vía de emisión que permita informarlos completos. Conserva los datos de la operación: Connect no recorta textos ni ajusta importes para que una petición pase la validación.

Reglas comunes

• Envía cantidades y precios como números JSON: por ejemplo, 0.01. Usa punto decimal, sin comillas, separadores de miles ni símbolos monetarios. Los folios y los tipos de documento del candidato son texto, salvo referencia.tipoDteReferido, que es el número 34.
• Los textos tienen al menos un carácter visible. Los espacios cuentan para el máximo; Connect no recorta un texto para hacerlo caber. Usa caracteres representables en Latin-1: letras con tildes y ñ sí; emojis, comillas tipográficas y el símbolo de euro no.
• Envía los RUT sin puntos, con guion y dígito verificador válido; por ejemplo, 77123456-9.
• Omite los campos opcionales que no vayas a usar. No los envíes con null, texto vacío, un objeto vacío o un arreglo vacío. Si envías un bloque, debe incluir todos sus campos obligatorios.
• Usa solo los campos admitidos para el tipoDte elegido. Los campos de otro tipo de documento producen un error de validación.
• La fecha de emisión, el emisor, el folio asignado y los totales se resuelven al preparar y emitir; no se envían dentro del candidato. Las fechas que sí envías son las de los documentos referenciados.

Las tablas siguientes usan rutas relativas a candidato. En REST este objeto va dentro de input; en MCP, dentro de params, con la tool sii.dte.previsualizar mediante execute.

Documento y receptor

Completar los datos del receptor

En facturas 33 y 34 puedes empezar con receptor.rut. Connect completa la razón social, el giro, la dirección, la comuna y la ciudad con los datos registrados en el SII. Debes enviar cualquier dato que no esté disponible allí; los seis datos del receptor son necesarios para preparar el documento.

Si hay un único giro y una única dirección, Connect los usa. Si hay varias opciones, responde validation_error: consulta sii.receptor.opciones y elige el giro o la dirección que corresponda. Si envías giro o dirección y el SII tiene opciones registradas, usa uno de esos valores. Enviar una comuna sin dirección puede acotar las opciones.

Si la dirección elegida no trae ciudad, envía receptor.ciudad con hasta 20 caracteres. Si el SII no tiene datos del receptor, envía los seis campos completos.

La respuesta de previsualización de la factura incluye receptor y advertencias. Revisa los datos completados y los cambios de ortografía antes de emitir. En guías y notas, envía siempre los seis datos del receptor desde la petición.

La obligatoriedad de la tabla corresponde a Connect. También se aplica a los campos que el formato DTE considera opcionales: ciudad y, en notas 56/61, giro, dirección y comuna.

Líneas de detalle

Las cantidades y los precios deben ser de al menos 0,01 y tener hasta dos decimales. Aunque el formato XML admite hasta seis decimales, esta API se limita a los dos que conserva el Facturador Gratuito al preparar el documento. Una entrada con mayor precisión produce un error; Connect no la redondea para aceptarla. No se admiten descuentos, recargos ni impuestos por línea.

Cálculo de los montos

Connect calcula el subtotal de cada línea como round(cantidad × precioUnitario), en pesos enteros. Cada subtotal debe ser positivo y tener hasta 10 dígitos. Un precio que cumple su límite puede producir un subtotal demasiado grande o redondeado a cero; revisa también la cantidad.

Los subtotales se suman para obtener el neto o el monto exento del documento:

• Factura 33 y guía 52: IVA del 19 % sobre el neto, redondeado a pesos enteros. Esta API exige IVA positivo, por lo que el neto debe ser de al menos $3. Neto, IVA y total admiten hasta 12 dígitos.
• Factura 34 y notas sobre ella: sin IVA; el total es igual al monto exento y admite hasta 12 dígitos.

Los totales no se envían ni se pueden elegir por separado. Si el cálculo de Connect y el del SII pueden dar resultados distintos por redondeo, la previsualización responde validation_error. Revisa la cantidad y el precio; si reflejan la operación real, utiliza otra vía de emisión que los admita.

El SII también puede rechazar montos altos que cumplan los límites de dígitos de Connect. Ante ese rechazo, conserva los importes reales y sigue Resultados y errores.

Impresión de la guía

La guía debe caber en 17 renglones impresos. El presupuesto suma una fila por detalle, una extra por cada cuatro detalles, las descripciones y, cuando hay referencias, una fila por referencia más su título. Las descripciones ocupan renglones de 45 caracteres; los saltos de línea también consumen espacio. No admiten palabras de más de 30 caracteres ni 170 espacios consecutivos de relleno.

El máximo de 999 caracteres de una descripción no garantiza que quepa la guía. Con una sola línea sin referencias caben hasta 720 caracteres de descripción continua; con diez líneas y tres referencias queda un renglón para descripciones. Estos ejemplos suponen palabras dentro del límite y texto sin saltos. Si falta espacio, conserva la información necesaria y usa otra vía de emisión que la admita.

Referencias

En facturas y guías, usa referencias para asociar documentos como una orden de compra o una guía de despacho. En notas, usa referencia, en singular, para identificar la factura exenta 34 que corriges.

En facturas y guías, los tipos 30, 32, 33, 34, 38, 39, 40, 45, 46, 50, 52, 55, 56, 60, 61 y 103 requieren folio numérico positivo sin ceros iniciales. Los otros tipos admitidos pueden llevar un identificador alfanumérico. En ambos casos, el texto "0" se reserva para una referencia global con indicadorGlobal: 1; no uses esa combinación para representar un documento individual.

La exigencia de no enviar ceros iniciales es una regla de representación de Connect.

En las notas, envía una única referencia a la factura 34. No se admiten referencias globales, referencias adicionales ni un código de referencia enviado por ti. operacion: "corregir_montos" determina la corrección. Para anular utiliza el flujo de anulación, con sus propios tipos de documento admitidos.

Solicitante y transporte de la guía

Estos campos solo se aceptan para tipoDte: "52". Si envías transporte, incluye sus cuatro campos: transportista, patente, RUT del chofer y nombre del chofer.

La Resolución SII N.º 144 de 2026 rige desde el 1 de noviembre de 2026 y reemplaza la N.º 154 de 2025. Distingue modalidades de traslado y regula sus datos de origen, destino, conductor, transportista y vehículo. Los plazos específicos de adecuación hasta mayo de 2027 no son una exención general. Que transporte sea opcional en la API no te exime de informar los datos exigibles en tu operación, incluso en traslados que no son venta. Si necesitas datos o un flujo que Connect no ofrece, usa una vía que permita informarlos.

Esta API no permite informar:

• Los motivos de traslado 10, 11 y 12 incorporados por esa resolución; solo admite los nueve motivos de la guía.
• Campos separados de origen y destino efectivos, remolque o fechas de traslado.
• El flujo de declaración de datos desconocidos y su complemento posterior.
• Datos de manejo de madera.

Operaciones y campos no admitidos

Esta API no acepta descuentos globales, pagos parciales, moneda extranjera, totales editables, regímenes especiales ni impuestos adicionales. La factura 33 no admite líneas exentas mezcladas. Las notas 56/61 de esta guía solo corrigen montos de una factura 34; no corrigen texto ni otros tipos de documento.

Emitir después de previsualizar

Cuando hayas revisado la vista previa, usa su previewRef para emitir. sii.dte.emitir recibe únicamente esa referencia. Usa la misma conexión y la misma identidad que preparó el documento, y una clave de idempotencia propia de esa emisión. El previewRef vence en 15 minutos y es de un solo uso. En REST, la conexión y la idempotencia van en X-Connect-Connection e Idempotency-Key; en MCP, en connectionId e idempotencyKey de execute_write, fuera de params.

Errores por campo en REST y MCP

Si recibes validation_error, sigue estos pasos:

1. Lee message y suggested_fix para saber qué dato falta o qué regla incumple la petición.
2. Si hay un arreglo details, revisa path para localizar el campo y code para identificar la regla.
3. Corrige los datos que correspondan y vuelve a llamar a sii.dte.previsualizar antes de emitir.

Cada elemento de details contiene code, path y message. Puede incluir también maximum, minimum, inclusive, expected, values o keys, según la regla. Para procesar errores en tu integración, usa esos códigos y rutas; el texto de message puede cambiar.

Este ejemplo es un elemento de details por una ciudad de más de 20 caracteres:

{
  "code": "too_big",
  "path": ["candidato", "receptor", "ciudad"],
  "message": "candidato.receptor.ciudad admite hasta 20 caracteres, contando los espacios. Envía el dato correcto dentro de ese límite; si necesita más caracteres, esta variante no lo admite.",
  "origin": "string",
  "maximum": 20,
  "inclusive": true
}

Las rutas empiezan en el input de la tool: no incluyen los contenedores REST input ni MCP params. Un índice numérico identifica una posición de un arreglo desde cero: detalles, 0, precioUnitario se refiere al precio de la primera línea. Un error sobre una combinación puede apuntar al objeto, al arreglo o al candidato completo en lugar de a un único campo.

Un validation_error también puede indicar que falta ciudad o que debes elegir entre varias direcciones del receptor. En esos casos puede no haber details: sigue message y suggested_fix, y consulta sii.receptor.opciones cuando te pida elegir un giro o una dirección.

Para documentos no admitidos, rechazos del SII, vistas previas vencidas o resultados desconocidos, sigue Resultados y errores. Conserva el request_id para soporte y no cambies la clave de idempotencia para resolver una emisión cuyo resultado todavía no conoces.