Facturas 33 y 34

Esta guía emite una factura afecta 33 con tres líneas y dos referencias. La exenta 34 usa la misma forma. Antes de empezar, revisa qué necesitas y ten a mano el connectionId de la empresa, que sale de conexiones.estado.consultar.

Los datos de los ejemplos son ficticios. No los envíes: toda emisión es real.

La guía de campos, validación y límites reúne la obligatoriedad, los largos, los decimales y la forma de leer errores por REST o MCP.

1. Previsualiza la factura

sii.dte.previsualizar recibe los datos de la factura en candidato y devuelve una vista previa con el receptor y los totales, sin firmar ni emitir:

curl -X POST https://connect.emisso.ai/api/v1/tools/sii.dte.previsualizar/execute \
  -H "Authorization: Bearer connect_sk_…" \
  -H "X-Connect-Connection: conn_9tKfR2mQx4Vb" \
  -H "Content-Type: application/json" \
  -d '{
    "input": {
      "candidato": {
        "tipoDte": "33",
        "receptor": {
          "rut": "77123456-9",
          "razonSocial": "Comercial Los Aromos SpA",
          "giro": "Venta de artículos de oficina",
          "direccion": "Av. Providencia 1234, oficina 501",
          "comuna": "Providencia",
          "ciudad": "Santiago"
        },
        "tipoVenta": "del_giro",
        "tipoCompra": "del_giro",
        "condicionPago": { "formaPago": "credito" },
        "detalles": [
          { "nombre": "Asesoría contable", "cantidad": 1, "precioUnitario": 450000 },
          { "nombre": "Horas extra", "cantidad": 2.5, "precioUnitario": 32000 },
          { "nombre": "Traslado", "cantidad": 1, "precioUnitario": 18000 }
        ],
        "referencias": [
          { "tipoDocumento": "801", "folio": "OC-4512", "fecha": "2026-09-10", "razon": "Orden de compra" },
          { "tipoDocumento": "HES", "folio": "7781", "fecha": "2026-09-12" }
        ]
      }
    }
  }'

Salida esperada (200, campo data):

{
  "estado": "previsualizado",
  "tipoDte": "33",
  "variante": "33:del_giro:del_giro:credito",
  "fechaEmision": "2026-09-15",
  "receptorRut": "77123456-9",
  "totales": { "tributacion": "afecta", "neto": 548000, "iva": 104120, "total": 652120 },
  "advertencias": [],
  "previewRef": "<referencia opaca>",
  "expiraEn": "2026-09-15T14:15:00.000Z",
  "contractVersion": 3
}

Revisa los totales antes de seguir. La fecha de emisión la fija el portal del SII: no se envía. El previewRef es de un solo uso, vence en 15 minutos y solo sirve para la misma conexión y el mismo actor.

2. Emite la factura

Genera una clave de idempotencia (UUID v4), guárdala junto a la factura en tu sistema y llama a sii.dte.emitir con el previewRef:

curl -X POST https://connect.emisso.ai/api/v1/tools/sii.dte.emitir/execute \
  -H "Authorization: Bearer connect_sk_…" \
  -H "X-Connect-Connection: conn_9tKfR2mQx4Vb" \
  -H "Idempotency-Key: 3f6c1b2e-8d4a-4c7f-9e21-5a0b7d9c4e18" \
  -H "Content-Type: application/json" \
  -d '{"input": {"previewRef": "<referencia opaca>"}}'

Salida esperada (200, campo data):

{
  "resultado": {
    "estado": "emitido",
    "operacionId": "req_k7w2m9q4x1c8v5b3n6z0p",
    "tipoDte": "33",
    "variante": "33:del_giro:del_giro:credito",
    "folio": "1042",
    "fechaEmision": "2026-09-15",
    "confirmadoEn": "2026-09-15T14:03:12.000Z",
    "xmlFirmado": "<DTE version=\"1.0\"><Documento ID=\"…\">…<TED version=\"1.0\">…</TED>…</Documento>…</DTE>"
  }
}

Guarda folio y operacionId. Si el estado es rechazado o resultado_desconocido, sigue Resultados y errores: nunca reenvíes con una clave nueva para salir de la duda.

xmlFirmado es el documento tributario: el XML que Connect firmó y el SII aceptó, con su timbre electrónico (TED). Con él generas la representación impresa y el código PDF417 sin otra llamada. Repetir la emisión con la misma clave lo devuelve de nuevo. Guárdalo como guardas cualquier factura. Si prefieres el PDF oficial que muestra el Facturador Gratuito, pídelo con sii.dte.descargar.

3. Pide el XML después

sii.dte_xml.consultar entrega el XML firmado de una factura, nota o nota de crédito de anulación que Connect emitió en la conexión, a partir del operacionId que devolvió la emisión. Lo lee de lo que Connect guardó al emitir: no consulta al SII, responde de inmediato aunque el documento todavía no aparezca en sii.cl y sirve también para documentos emitidos antes de que la respuesta incluyera xmlFirmado.

curl -X POST https://connect.emisso.ai/api/v1/tools/sii.dte_xml.consultar/execute \
  -H "Authorization: Bearer connect_sk_…" \
  -H "X-Connect-Connection: conn_9tKfR2mQx4Vb" \
  -H "Content-Type: application/json" \
  -d '{"input": {"operacionId": "req_k7w2m9q4x1c8v5b3n6z0p"}}'

Salida esperada (200, campo data, recortada):

{
  "operacionId": "req_k7w2m9q4x1c8v5b3n6z0p",
  "tipoDte": "33",
  "folio": "1042",
  "fechaEmision": "2026-09-15",
  "xmlFirmado": "<DTE version=\"1.0\">…</DTE>"
}

Solo responde por documentos que quedaron emitidos en esa conexión. Si no hay uno con ese operacionId, o la emisión quedó en resultado_desconocido, responde 404 con sii_emission_not_found. Requiere el permiso sii:read.

Por MCP

Un agente conectado al servidor MCP hace las mismas dos llamadas. La vista previa no escribe, así que va por execute, y params lleva lo mismo que el input de REST (aquí, una factura de una línea):

{
  "tool": "sii.dte.previsualizar",
  "connectionId": "conn_9tKfR2mQx4Vb",
  "params": {
    "candidato": {
      "tipoDte": "33",
      "receptor": {
        "rut": "77123456-9",
        "razonSocial": "Comercial Los Aromos SpA",
        "giro": "Venta de artículos de oficina",
        "direccion": "Av. Providencia 1234, oficina 501",
        "comuna": "Providencia",
        "ciudad": "Santiago"
      },
      "tipoVenta": "del_giro",
      "tipoCompra": "del_giro",
      "condicionPago": { "formaPago": "credito" },
      "detalles": [
        { "nombre": "Asesoría contable", "cantidad": 1, "precioUnitario": 450000 }
      ]
    }
  }
}

La emisión escribe, así que va por execute_write, con la clave de idempotencia como argumento, fuera de params:

{
  "tool": "sii.dte.emitir",
  "connectionId": "conn_9tKfR2mQx4Vb",
  "idempotencyKey": "3f6c1b2e-8d4a-4c7f-9e21-5a0b7d9c4e18",
  "params": { "previewRef": "<referencia opaca>" }
}

La UUID del ejemplo solo ilustra el formato: genera una propia por documento.

Pedir el XML después no escribe, así que va por execute:

{
  "tool": "sii.dte_xml.consultar",
  "connectionId": "conn_9tKfR2mQx4Vb",
  "params": { "operacionId": "req_k7w2m9q4x1c8v5b3n6z0p" }
}

El candidato, campo por campo

Usa los datos del receptor tal como están registrados en el SII, sin espacios al inicio ni al final. Los textos deben poder escribirse en Latin-1: tildes y ñ sí, emojis no. El emisor no se envía: sale del perfil de la conexión (su actividad económica y su dirección).

Receptor completado desde el SII

Como el Facturador Gratuito al escribir el RUT, Connect completa el receptor con lo que el SII tiene registrado. Basta con enviar receptor.rut:

• Una sola opción: si el SII tiene un giro y una dirección para ese RUT, Connect los usa con su comuna y su ciudad, y la previsualización sigue.
• Varias opciones: el SII no indica cuál es la principal, así que Connect no elige. La previsualización responde validation_error. Consulta las opciones con sii.receptor.opciones y envía en receptor.giro y receptor.direccion las que correspondan, escritas como en la lista. Para no recibir todas las direcciones, envía solo receptor.comuna: si en esa comuna queda una sola dirección, se usa.
• Comuna y ciudad: salen de la dirección elegida. Si el SII no tiene la ciudad de esa dirección, envía receptor.ciudad: Connect la necesita para preparar esta variante. El formato DTE la considera opcional; eso no significa que pueda faltar al terminar de preparar la factura en Connect.
• Sin datos en el SII: envía razón social, giro, dirección, comuna y ciudad.

Con datos en el SII, el giro y la dirección tienen que ser de su lista. Connect los reconoce aunque los escribas con otras mayúsculas, tildes o espacios, y los envía como los tiene el SII. Lo que envíes nunca se reemplaza por otra opción.

La previsualización devuelve el receptor tal como quedó en receptor. Revísalo antes de emitir. Cada campo que Connect completó aparece en advertencias con el código receptor_completado_desde_sii, y cada uno que reescribió con la ortografía del SII, con receptor_escrito_como_en_el_sii. Si el receptor llega completo, Connect no consulta nada y la previsualización tarda lo mismo que antes. Si falta algo, la consulta suma alrededor de medio segundo.

Varias líneas

detalles lleva entre una y diez líneas, en el orden en que van en la factura. Cada línea tiene:

• nombre: hasta 80 caracteres.
• cantidad: desde 0,01, con hasta dos decimales.
• precioUnitario: en pesos, positivo y antes de impuestos, con hasta dos decimales (8402.49).

Ninguna línea admite código, unidad, descripción ni descuento.

Connect calcula el subtotal de cada línea como round(cantidad × precioUnitario), igual que el portal, y el neto (o el monto exento de la 34) como la suma de esos subtotales. El IVA de la 33 se calcula una sola vez sobre ese neto. En el ejemplo: 450.000 + 80.000 + 18.000 = 548.000 de neto, 104.120 de IVA y 652.120 de total.

El precio puede llevar decimales, pero el subtotal de cada línea siempre queda en pesos enteros: 1,09 × 8.402,49 da 9.158,7141 y la línea queda en 9.159. Si una combinación produce una diferencia de redondeo entre la cuenta exacta y la vista previa, Connect la rechaza con validation_error en precioUnitario. Verifica cantidad y precio; si son correctos, conserva los importes reales y usa otra vía de emisión. No cambies importes para hacer pasar la validación.

Que el precio admita decimales no permite llegar a cualquier total con IVA incluido. El neto es un entero y el IVA se calcula sobre él, así que hay totales a los que no llega ningún neto: $9.999 queda entre 8.402 + 1.596 = 9.998 y 8.403 + 1.597 = 10.000. El portal del SII se comporta igual.

Connect compara cada línea de la vista previa y del documento que se firma con las que enviaste. Si el SII devuelve una línea distinta, de más o de menos, la operación se detiene antes de firmar.

Referencias

Una factura 33 o 34 puede llevar entre una y tres referencias a los documentos que la originan. Cada referencia tiene:

• tipoDocumento: el código del documento referido, tal como lo ofrece el selector del Facturador Gratuito.
• folio: el folio o número de ese documento, en texto y hasta 18 caracteres.
• fecha: la fecha de ese documento, en AAAA-MM-DD.
• razon: opcional, hasta 90 caracteres.
• indicadorGlobal: opcional. Con 1, la referencia cubre un conjunto de documentos y el folio debe ser "0".

También puedes referir un documento tributario por su código: 30, 32, 33, 34, 35, 38, 39, 40, 41, 43, 45, 46, 48, 50, 52 (guía de despacho), 55, 56, 60, 61 o 103. Los tipos que requieren folio numérico positivo, sin ceros iniciales, están en las reglas de referencias.

Una factura no lleva código de referencia: anular una factura se hace con su nota de anulación, y corregir montos de una 34, con una nota de corrección.

Connect compara las referencias de la vista previa y del documento que se firma con las que enviaste. Si el SII devuelve otras, la operación se detiene antes de firmar.

Factura exenta 34

La 34 lleva el mismo candidato con "tipoDte": "34". Sus líneas son exentas y la vista previa devuelve totales sin IVA:

{ "tributacion": "exenta", "exento": 548000, "total": 548000 }

Qué no admite todavía

• Contacto del receptor ni solicitante.
• Código, unidad, descripción o descuento por línea, ni descuento global.
• Más de diez líneas o más de tres referencias.
• Formas de pago distintas de crédito, pagos parciales ni datos de transporte.
• En la 33: líneas exentas, impuestos adicionales y regímenes especiales (constructoras, madera, bienes raíces, factura turística).
• Cantidades menores que 0,01 o con más de dos decimales, y precios unitarios con más de dos decimales.

La previsualización confirma si la conexión puede preparar la factura con los datos enviados. Revisa su resultado antes de emitir. La referencia completa del contrato está en sii.dte.previsualizar y sii.dte.emitir.