Documentos Tributarios Electrónicos (DTE)

Un DTE es un documento tributario que se emite ante el SII de Chile. La API cubre nueve tipos, desde la factura afecta hasta la liquidación factura, con un mismo endpoint de emisión.

Esta guía es conceptual: explica el flujo, los modos y las restricciones que se descubren en runtime. El detalle exhaustivo de campos, tipos y esquemas de respuesta vive en la especificación OpenAPI — acá no se duplica.

Antes de emitir

Tres cosas tienen que existir en tu tenant antes del primer POST:

Requisito	Qué es	¿Por API?
Emisor DTE	La empresa que emite, con su certificado digital vigente delegado a la plataforma. Su identificador es el emisorDteId que pide el endpoint de emisión	Sí, por tokenización SII
Folios CAF	Los rangos de folios que el SII autoriza por tipo de documento. Sin folios disponibles, la emisión falla	No
dirOrigen	La dirección de origen configurada en el emisor. El SII la exige en el encabezado	No

El alta de un emisor DTE sí se hace íntegramente por API: el camino es la tokenización SII, donde el titular entrega su certificado en un wizard de Redcumbre y tú recibes el emisor de vuelta. Está documentado en Emisores Tributarios y Emisores DTE. Los folios CAF y la dirOrigen no se resuelven por API: si te faltan, escribe a tu contacto en REDCUMBRE.

De dónde sacas el emisorDteId

Es configuración: se fija una vez por emisor y después no se toca. Hay dos caminos según cómo se dio de alta, y los dos entregan el mismo valor.

• Panel web — Configuración → Emisores: abre el emisor y copia el campo ID. Es el camino normal cuando el emisor ya estaba provisionado en tu tenant.
• Tokenización SII — si das de alta el emisor desde tu backend, el id viene en la respuesta de POST /{tenantSlug}/tokenizacion/exchange (data.emisorId) y en el webhook tokenizacion.completada, con tipoEmisor: "dte".

Guárdalo en tu sistema junto al RUT. No hay endpoint de listado de emisores con API key: si lo pierdes, tienes que volver al panel o re-tokenizar el mismo RUT. Ver De dónde sale el emisorDteId.

Tipos soportados

Código	tipoDte	Documento
33	FACTURA_AFECTA	Factura Electrónica Afecta
34	FACTURA_EXENTA	Factura Electrónica Exenta
39	BOLETA_AFECTA	Boleta Electrónica Afecta
41	BOLETA_EXENTA	Boleta Electrónica Exenta
43	LIQUIDACION_FACTURA	Liquidación Factura
46	FACTURA_COMPRA	Factura de Compra (cambio de sujeto)
52	GUIA_DESPACHO	Guía de Despacho
56	NOTA_DEBITO	Nota de Débito
61	NOTA_CREDITO	Nota de Crédito

El canal de emisión es del emisor, no del tipo de documento

Es lo primero que conviene entender, porque de ahí cuelgan el límite de líneas, el modo de emisión y la forma exacta de la respuesta.

El canal es una propiedad del emisor DTE configurado en tu tenant. Una misma factura afecta se emite por un canal o por otro según cómo esté habilitado tu emisor: no lo decide el tipo de documento ni lo eliges en la petición. Te lo indica tu contacto en REDCUMBRE, junto con el resto de los prerequisitos.

Canal	Cómo emite	Qué cambia para ti
Portal MiPyme	La plataforma opera el portal del SII con el certificado delegado	Máximo de 10 líneas de detalle. Los tres modos de emisión aplican
Firma local (FULL_DTE)	La plataforma arma el XML, lo firma y lo envía al SII en lote	Hasta 60 líneas de detalle. El modo que pidas no aplica: la respuesta siempre viene con modo: "ASINCRONO", con el documento y su folio ya asignados, y con estadoSii: "PENDIENTE_ENVIO"
API Oficial SII	Sólo las boletas 39 y 41, con CAF y certificado digital propios	Hasta 500 líneas de detalle
Integración a medida (API_EXTERNA)	La plataforma delega la emisión en el sistema que ya usas	El máximo de líneas lo fija ese sistema. El modo que pidas no aplica: la respuesta viene con modo: "ASYNC_EXTERNO", estado: "PENDIENTE_EXTERNO" y folio: 0 — el folio lo asigna el sistema externo y llega después

Un RUT puede tener dos emisores: facturación y boletas

Las boletas electrónicas (39 y 41) salen de un emisor propio, el de boletas, distinto del de facturación. Un mismo RUT puede tener los dos, y cada uno tiene su emisorDteId: el que mandas en la petición decide por cuál sale el documento.

La nota de crédito que anula una boleta la emite el emisor de facturación

La nota de crédito (61) es un documento de facturación. El emisor de boletas no la emite: para anular una boleta necesitas el emisor de facturación del mismo RUT y su emisorDteId.

Si el RUT sólo tiene el emisor de boletas, esa anulación no se puede hacer por API: se hace directamente en el Portal MiPyme del SII.

Cómo se dan de alta los dos, y cómo llegan sus ids, está en Emisores.

Emitir

POST /{tenantSlug}/dte

Cuatro campos son obligatorios: emisorDteId, tipoDte, receptor y lineas. El emisorDteId sale del panel web o de la tokenización — ver Antes de emitir. Dentro de receptor, el giro es obligatorio en todos los tipos salvo las boletas 39 y 41: si falta, la petición responde 400 con receptor.El giro del receptor es obligatorio para este tipo de DTE.

El giro del receptor

El camino natural para obtenerlo es POST /{tenantSlug}/herramientas/lookup-rut, pero giroGlosa normalmente llega null: el SII solo entrega el giro cuando el RUT consultado es el mismo del certificado que consulta, y al facturarle a un cliente nunca lo es. Hay que resolverlo en cascada:

const { data } = await lookupRut(rutReceptor);

const giro = data.giroGlosa                              // null salvo lookup auto-referencial
          ?? data.actividadesEconomicas?.[0]?.descripcion // la actividad principal del SII
          ?? await pedirGiroAlUsuario();                  // último recurso

Los nombres de campo son literales: el array es data.actividadesEconomicas —no data.actividades— y cada elemento trae { codigo, descripcion }. El SII trunca el giro a 40 caracteres al recibir el DTE, así que conviene mandarlo ya recortado y revisado, no una glosa larga cortada a ciegas.

El nombre de fantasía del receptor

Muchos clientes se conocen por el nombre de su local, no por su razón social: la boleta la pide «Minimarket Don Pepe» y la empresa se llama COMERCIAL PÉREZ Y HERMANOS LIMITADA. El campo opcional receptor.nombreFantasia existe para eso.

No viaja al SII. El formato oficial del DTE no tiene un campo para esto, así que el nombre de fantasía no entra en el XML firmado ni en el timbre: sólo se imprime en el PDF. Máximo 100 caracteres.

Tiene tres comportamientos según lo que mandes, y la diferencia entre omitirlo y mandarlo en null es real:

Lo que mandas	Qué queda en el documento
No mandas la clave	El de la ficha del cliente, si la tiene. Si el documento se arma desde otro —una nota de crédito sobre una factura— hereda el del documento de origen. Si no hay ninguno, el documento sale sin nombre de fantasía.
"nombreFantasia": null (o "")	Nada: el documento sale sin nombre de fantasía, aunque la ficha del cliente tenga uno.
"nombreFantasia": "Minimarket Don Pepe"	Ese texto, congelado. Cambiar después la ficha del cliente no altera el documento ya emitido. Además, si la ficha del cliente todavía no tenía nombre de fantasía, se guarda ahí; si ya tenía uno, no se sobrescribe.

curl -X POST https://api.redcumbre.cl/tu-tenant/dte \
  -H "X-API-Key: tu-api-key" \
  -H "Content-Type: application/json" \
  -d '{
    "emisorDteId": "clxyz123abc456def",
    "tipoDte": "FACTURA_AFECTA",
    "receptor": {
      "rut": "77438768-4",
      "razonSocial": "COMERCIAL PEREZ Y HERMANOS LIMITADA",
      "nombreFantasia": "Minimarket Don Pepe",
      "giro": "VENTA AL POR MENOR",
      "direccion": "AV PROVIDENCIA 1234",
      "comuna": "PROVIDENCIA"
    },
    "lineas": [{ "nombre": "Servicio", "cantidad": 1, "precioUnitario": 50000 }]
  }'

Cómo se ve impreso

Depende del formato de papel de la plantilla, y son dos resultados distintos:

• Hoja (carta y oficio) — va junto a la razón social, entre paréntesis, en el bloque de identificación del receptor:

  RECEPTOR: COMERCIAL PEREZ Y HERMANOS LIMITADA (Minimarket Don Pepe)
  RUT: 77.438.768-4

  El rótulo exacto depende de la plantilla que tenga tu empresa; lo que no cambia es que el nombre de fantasía va entre paréntesis dentro del mismo campo que la razón social.

• Cinta (voucher de 80 mm y de 57 mm) — va en su propia fila, rotulada, porque el ancho no alcanza para la línea compuesta. Si no cabe, salta de línea: nunca se corta:

  RUT:                 77.438.768-4
  Razón Social:        COMERCIAL PEREZ Y
                       HERMANOS LIMITADA
  Nombre de fantasía:  Minimarket Don Pepe
  Giro:                VENTA AL POR MENOR

Si el nombre de fantasía es igual a la razón social —ignorando mayúsculas, tildes, puntuación y espacios— no se imprime: repetir el mismo texto dos veces no aporta nada.

Dónde NO se admite

Dos documentos no lo llevan, y mandarles un valor responde 400:

• la Factura de Compra (46), donde el receptor es el vendedor;
• la boleta al RUT de público general (66666666-6), donde el receptor es anónimo.

Una nota de crédito o de débito cuya cadena de referencias llega a una factura de compra recibe el mismo trato. En los tres casos, omitir la clave o mandarla en null se acepta y el documento sale como siempre: si hoy emites facturas de compra sin saber que este campo existe, nada cambia para ti.

La ficha del cliente

El nombre de fantasía vive en la ficha del cliente dentro de tu empresa, no en el repositorio del SII: es tuyo y ningún otro contribuyente lo ve. Se administra con POST /{tenantSlug}/clientes y PATCH /{tenantSlug}/clientes/{id}, donde null o una cadena vacía lo borran y omitir la clave lo deja intacto. Borrarlo de la ficha no cambia los documentos ya emitidos: cada uno conserva el que tenía.

GET /{tenantSlug}/clientes?search= también lo alcanza: un término que coincida con el RUT, la razón social o el nombre de fantasía devuelve el cliente.

Factura Afecta (33)

curl -X POST https://api.redcumbre.cl/tu-tenant/dte \
  -H "Authorization: Bearer $REDCUMBRE_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "emisorDteId": "clxyz123abc456def",
    "tipoDte": "FACTURA_AFECTA",
    "formaPago": "CREDITO",
    "receptor": {
      "rut": "77438768-4",
      "razonSocial": "REDCUMBRE SPA",
      "giro": "VENTA AL POR MENOR DE PRODUCTOS EN COMERCIOS ESPECIALIZADOS",
      "direccion": "LOS PEUMOS ST. 3 LT B",
      "comuna": "BULNES",
      "email": "contacto@empresa.cl"
    },
    "lineas": [
      {
        "nombre": "Servicio de consultoría especializada",
        "cantidad": 1,
        "precioUnitario": 100000,
        "subtotal": 100000
      }
    ],
    "idempotencyKey": "orden-12345"
  }'

Respuesta (201). El documento va en data.dte y los montos en data.montos — no sueltos en data:

{
  "success": true,
  "data": {
    "modo": "SINC_PARCIAL",
    "dte": {
      "id": "dte_5fe4ff45-...",
      "tipoDte": "FACTURA_AFECTA",
      "folio": 25403,
      "dhdrCodigo": "2831022103",
      "estado": "EMITIDO",
      "modoEmision": "SINC_PARCIAL"
    },
    "montos": {
      "montoNeto": 100000,
      "montoExento": 0,
      "montoIva": 19000,
      "montoTotal": 119000
    },
    "urls": {
      "pdfUrl": "https://api.redcumbre.cl/public/documentos/{token}/pdf",
      "xmlUrl": "https://api.redcumbre.cl/public/documentos/{token}/xml",
      "pdfSiiUrl": null,
      "webUrl": "https://app.redcumbre.cl/tu-tenant/dte/dte_5fe4ff45-..."
    },
    "estadoPdfSii": "PENDIENTE",
    "mensaje": "DTE emitido exitosamente"
  },
  "sandbox": false
}

Ramifica por el contenido, no por el modo

Si la respuesta trae data.dte, el documento existe y tiene folio. Si trae data.intentoId, quedó encolado y todavía no. Esa es la única regla que vale en los tres canales: el modo devuelto no te dice cuál de las dos formas recibiste.

Un 2xx significa emitido — estadoSii no es el criterio de éxito

Si la respuesta es 2xx, el documento se emitió. estadoSii es el trámite posterior ante el SII y evoluciona por su cuenta durante los minutos siguientes: en Portal MiPyme pasa por PROCESO_SII antes de llegar a ACEPTADO, y con firma local nace en PENDIENTE_ENVIO. En la respuesta de emisión por Portal MiPyme el campo no viene.

Una integración que exija estadoSii: "ACEPTADO" para dar la emisión por buena marca como fallidas facturas que salieron perfectas, y si reintenta sin idempotencyKey quema otro folio. Para seguir el trámite usa webhooks o verificar-estado-sii.

Guarda el folio que devuelve la API

El folio de la respuesta es el que el SII asignó, y es el único con el que después puedes consultar el documento. Si tu sistema guarda su propio correlativo y descarta este, cualquier consulta posterior por folio no va a encontrar nada. Es el error de integración más caro que vemos.

Factura Exenta (34)

Igual que la 33, cambiando el tipo. Sin IVA: montoNeto y montoTotal coinciden.

curl -X POST https://api.redcumbre.cl/tu-tenant/dte \
  -H "Authorization: Bearer $REDCUMBRE_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "emisorDteId": "clxyz123abc456def",
    "tipoDte": "FACTURA_EXENTA",
    "receptor": {
      "rut": "77438768-4",
      "razonSocial": "REDCUMBRE SPA",
      "giro": "VENTA AL POR MENOR DE PRODUCTOS EN COMERCIOS ESPECIALIZADOS",
      "direccion": "LOS PEUMOS ST. 3 LT B",
      "comuna": "BULNES"
    },
    "lineas": [
      {
        "nombre": "Servicio educacional exento de IVA",
        "cantidad": 1,
        "precioUnitario": 250000,
        "subtotal": 250000
      }
    ]
  }'

Boleta Afecta (39)

El receptor habitual es el RUT de público general (66666666-6), donde direccion y comuna son opcionales — si no los mandas, el documento sale sin ellos; si los mandas, se guardan igual que en cualquier otro receptor:

curl -X POST https://api.redcumbre.cl/tu-tenant/dte \
  -H "Authorization: Bearer $REDCUMBRE_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "emisorDteId": "clxyz123abc456def",
    "tipoDte": "BOLETA_AFECTA",
    "receptor": {
      "rut": "66666666-6",
      "razonSocial": "CLIENTE PASAJERO"
    },
    "lineas": [
      {
        "nombre": "Pan amasado",
        "cantidad": 1,
        "precioUnitario": 1190
      }
    ]
  }'

precioUnitario es el precio con IVA incluido, el que el cliente ve en la boleta: en el ejemplo de arriba el total emitido es exactamente 1190, no un valor redondeado desde un neto. Es el único tipo de documento donde precioUnitario es bruto; en el resto sigue siendo neto. Si en cambio ya calculaste el neto y quieres que la API lo tome así, agrega "montoNeto": true al cuerpo de la petición — ahí precioUnitario vuelve a interpretarse sin IVA, igual que en una factura.

Un receptor con RUT distinto de 66666666-6 sigue exigiendo direccion y comuna como cualquier otro documento.

Liquidación Factura (43)

Es el tipo con más particularidades. Se usa cuando un mandatario liquida ventas a su mandante: las líneas describen lo vendido y las comisiones describen lo que el mandatario retiene.

curl -X POST https://api.redcumbre.cl/tu-tenant/dte \
  -H "Authorization: Bearer $REDCUMBRE_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "emisorDteId": "clxyz123abc456def",
    "tipoDte": "LIQUIDACION_FACTURA",
    "receptor": {
      "rut": "77438768-4",
      "razonSocial": "REDCUMBRE SPA",
      "giro": "VENTA AL POR MENOR DE PRODUCTOS EN COMERCIOS ESPECIALIZADOS",
      "direccion": "LOS PEUMOS ST. 3 LT B",
      "comuna": "BULNES"
    },
    "lineas": [
      {
        "nombre": "NETO FACTURAS ELECTRONICAS",
        "cantidad": 8,
        "precioUnitario": 18000,
        "subtotal": 144000,
        "tipoDocumentoLiquidar": 33
      },
      {
        "nombre": "EXENTO FACTURAS ELECTRONICAS",
        "cantidad": 3,
        "precioUnitario": 12000,
        "subtotal": 36000,
        "esExento": true,
        "tipoDocumentoLiquidar": 33
      }
    ],
    "comisiones": [
      { "tipoMovimiento": "C", "glosa": "Comisión por venta", "valorNeto": 5000 }
    ]
  }'

tipoDocumentoLiquidar identifica qué tipo de documento se está liquidando en esa línea. Es exclusivo del 43:

Código	Documento
0	Sin especificar (es el valor que se envía si omites el campo)
33	Factura electrónica
34	Factura exenta
39	Boleta electrónica
48	Pago de cheque
52	Guía de despacho

esExento en una línea permite mezclar afectos y exentos en el mismo documento, cosa que los demás tipos no admiten.

Modos de emisión

El modo aplica a los emisores que emiten por Portal MiPyme. Con firma local se ignora, y la respuesta viene siempre con modo: "ASINCRONO" y el documento ya emitido.

modo	Qué hace	Cuándo usarlo
SINC_COMPLETO	Emite y genera el PDF del SII antes de responder	Necesitas el PDF en la misma petición
SINC_PARCIAL	Default. Emite en forma síncrona; el PDF del SII se genera en segundo plano con reintentos	El caso general
ASINCRONO	Solo valida y encola. Todo ocurre en segundo plano	Estás emitiendo desde una petición web y no quieres que el usuario espere al SII

Ramifica por data.dte, nunca por modo

El modo de la respuesta informa cómo operó el carril; no anuncia la forma de la respuesta. Un emisor de firma local responde modo: "ASINCRONO" y trae el documento igual, porque lo que ocurre en segundo plano es el envío al SII, no la emisión.

La regla que sí se cumple en todos los canales es una sola:

if (respuesta.data.dte) {
  // El documento existe y tiene folio. Sigue con tu flujo.
} else {
  // Quedó encolado: consulta respuesta.data.intentoId.
}

Un cliente escrito como if (modo === "ASINCRONO") poll(intentoId) busca un intentoId que no existe en la mayoría de los canales.

Cuando la emisión queda encolada, la respuesta trae un intentoId en lugar del documento:

{
  "success": true,
  "data": {
    "modo": "ASINCRONO",
    "intentoId": "dtei_3f2a1b8c-...",
    "estado": "PENDIENTE",
    "mensaje": "Solicitud de emisión registrada. El DTE se procesará en segundo plano."
  },
  "sandbox": false
}

El estado del intento recorre PENDIENTE, PROCESANDO, REINTENTANDO y termina en EMITIDO o FALLIDO. Se consulta con GET /{tenantSlug}/dte/intento/{intentoId}. Para enterarte sin hacer polling, usa webhooks.

Cuando un documento no llega a un veredicto del SII

En toda forma de emisión el documento ya existe —folio, timbre y XML firmado— antes de que el SII diga nada, y lo recibes en dte.emitido. Para entregárselo a tu receptor, espera dte.emision_terminada aceptado. Casi siempre el SII termina resolviéndolo y te enteras por dte.emision_terminada. Pero hay desenlaces en los que la plataforma deja de intentar confirmar el resultado sin obtener un veredicto del SII, y ahí recibes dte.emision_sin_confirmar en vez del hito de cierre.

estadoSii	motivo del evento	Qué significa	Qué hacer
RECHAZADO_SII	— (llega por dte.emision_terminada, resultado: RECHAZADO)	El SII rechazó el documento, o rechazó el sobre completo que lo contenía (rechazo.alcance: 'ENVIO')	Corrige lo que indica rechazo y emite un documento nuevo
ERROR_EMISION	ENVIO_INTENTOS_AGOTADOS	La plataforma intentó subir el documento al SII y no obtuvo confirmación. El envío pudo haber llegado	Verifica el folio en el sitio del SII antes de reemitir
FALLIDO_RECONCILIACION	ENVIO_INTENTOS_AGOTADOS	Una boleta cuyo envío no se confirmó: el SII no la tiene o no se pudo consultar	Verifica el folio en el sitio del SII antes de reemitir
ERROR_EMISION	ENVIO_PLAZO_VENCIDO	El documento nunca se subió al SII dentro del plazo	Puedes reemitir directamente: el SII no lo conoce por esta vía
TIMEOUT_SII	SEGUIMIENTO_AGOTADO	El documento se envió y el SII no dio un estado final dentro del plazo de seguimiento	Verifica el folio en el SII. Si después la plataforma obtiene un veredicto, llega dte.emision_terminada — ésa es la última palabra

No reemitas con la misma idempotencyKey

La clave es permanente — su alcance es emisor, ambiente, tipo de documento y la propia clave — así que reintentar con la misma idempotencyKey siempre te devuelve el documento original, nunca uno nuevo (ver Idempotencia). Para corregir, emite con una idempotencyKey distinta: eso consume un folio nuevo. El folio del documento que quedó en ERROR_EMISION o RECHAZADO_SII no se anula ni se reutiliza automáticamente: queda consumido del CAF, igual que el de cualquier documento rechazado.

Un documento ERROR_EMISION que todavía no tiene ningún envío registrado (nunca llegó a subirse) responde consultaOmitida: true en POST /{tenantSlug}/dte/{id}/verificar-estado-sii, con detalle.motivo igual al motivo del catálogo: la plataforma no va a volver a intentar el envío, así que consultar no cambia nada.

Borradores

Con "saveAsDraft": true el documento se guarda sin emitir. La respuesta es plana —no trae dte ni montos— y no consume folio:

{
  "success": true,
  "data": {
    "id": "dte_3b4e9827-...",
    "estado": "BORRADOR",
    "lineas": [{ "nombre": "Servicio de consultoría", "cantidad": 1, "precioUnitario": 100000, "subtotal": 100000 }],
    "trazaPrecios": []
  },
  "sandbox": false
}

Se puede editar y se emite después con POST /{tenantSlug}/dte/{id}/emitir.

Es también la forma de probar un payload sin emitir nada

Un borrador pasa por la misma validación que una emisión real, así que saveAsDraft: true seguido de DELETE /{tenantSlug}/dte/{id} te dice si tu petición es válida sin consumir folio ni generar un documento ante el SII. Es la manera recomendada de estrenar una integración, incluso contra producción.

Notificar al receptor

La emisión puede avisarle al receptor por email y por SMS. Son dos carriles independientes, y en ambos los destinatarios salen de la suma de tres orígenes, deduplicada:

Campo	Qué hace
receptor.email	Email del receptor. Recibe el PDF del documento
receptor.telefono	Teléfono del receptor. Recibe el SMS con el enlace al PDF si notificarSmsDte está activo. Para el SMS tiene que ser un móvil chileno (569XXXXXXXX)
emailsAdicionales	Hasta 20 destinatarios extra de email — el contador del cliente, por ejemplo
telefonosSmsAdicionales	Hasta 10 destinatarios extra de SMS, móviles chilenos
notificarSmsDte	Activa el SMS. Si no lo mandas, queda activo cuando tu tenant tiene el servicio de SMS habilitado
emailVoid / smsVoid	Excluyen destinatarios de esta emisión. No borran nada de la agenda
enviarDtePorEmail	Si es false, apaga el correo de cortesía completo (ver abajo). Si no lo mandas, vale true y el comportamiento es el de siempre

La agenda del cliente se puebla sola

Todo contacto que mandas en una emisión —los cuatro campos de arriba— queda guardado en la agenda de destinatarios DTE del cliente dentro de tu empresa, normalizado y sin duplicar. Desde la emisión siguiente al mismo receptor no hace falta repetirlo: ya está en la agenda y se notifica igual.

Eso vale también para los borradores: si guardas un borrador con contactos, la agenda se puebla ahí mismo, sin haber emitido.

Cuatro detalles que conviene tener presentes:

• El teléfono se normaliza al guardarlo (+56 9 8430 6244 → 56984306244) y sólo entran móviles chilenos. Un fijo se acepta en el documento pero no llega a la agenda ni recibe SMS.
• Las boletas a público general (66666666-6) no alimentan la agenda. La ficha sería compartida por todos los compradores anónimos.
• emailVoid y smsVoid no borran de la agenda. Excluyen del envío de esa emisión y nada más; para sacar un destinatario definitivamente están los endpoints de la agenda del cliente.
• Con enviarDtePorEmail: false los correos de la emisión no se guardan en la agenda; los teléfonos sí. Más abajo, en «Entregar el documento por tu cuenta», está el detalle.

El detalle de campos, largos y validaciones está en la especificación OpenAPI.

Entregar el documento por tu cuenta (enviarDtePorEmail)

Si tu integración ya le avisa al receptor por su lado, enviarDtePorEmail: false apaga el correo de cortesía de rCAPI para ese documento:

curl -X POST https://api.redcumbre.cl/tu-tenant/dte \
  -H "Authorization: Bearer $REDCUMBRE_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "emisorDteId": "clxyz123abc456def",
    "tipoDte": "FACTURA_AFECTA",
    "formaPago": "CREDITO",
    "receptor": {
      "rut": "77438768-4",
      "razonSocial": "REDCUMBRE SPA",
      "giro": "VENTA AL POR MENOR DE PRODUCTOS EN COMERCIOS ESPECIALIZADOS",
      "direccion": "LOS PEUMOS ST. 3 LT B",
      "comuna": "BULNES",
      "email": "contacto@empresa.cl"
    },
    "lineas": [
      {
        "nombre": "Servicio de consultoría especializada",
        "cantidad": 1,
        "precioUnitario": 100000,
        "subtotal": 100000
      }
    ],
    "enviarDtePorEmail": false
  }'

Qué apaga y qué no:

• No se envía a receptor.email, a los emails de la agenda del cliente ni a emailsAdicionales.
• La casilla de intercambio del SII se envía siempre, con false o sin el campo: es la entrega legal del documento, no un aviso de cortesía.
• receptor.email y emailsAdicionales de esta emisión no se guardan en la agenda del cliente (los teléfonos de SMS sí siguen guardándose igual).
• Si no queda ni destinatario de cortesía ni casilla de intercambio, el documento se emite igual — no se rechaza por falta de correo.
• El reenvío manual del documento (desde la plataforma) no se ve afectado: siempre manda, sin importar cómo se emitió el documento.

Si no mandas el campo, vale true y el correo de emisión sale como siempre.

Elegir la plantilla del PDF

Cada tipo de DTE tiene varias plantillas para el PDF de la plataforma: la estándar en hoja carta, las de cinta térmica (80 mm y 57 mm) y algunas especializadas. Si no eliges ninguna, el documento se representa con la que tu empresa tenga configurada, o con la de la plataforma si no configuró una.

Para ver las plantillas de un tipo, consulta GET /{tenantSlug}/dte/templates/{codigoSii}. Cada una trae su id, su formato de papel y clavesMetadataAdicional: las claves de metadataAdicional que esa plantilla imprime.

{
  "id": "tpl_dte41_005",
  "name": "Boleta Exenta con Profesional (Carta)",
  "paperFormat": "letter",
  "isDefault": false,
  "clavesMetadataAdicional": [
    {
      "clave": "NombreProfesional",
      "descripcion": "Nombre del profesional que realiza la atención."
    },
    {
      "clave": "RutProfesional",
      "descripcion": "RUT del profesional, tal como se imprime (por ejemplo `15.234.567-8`)."
    }
  ]
}

(Extracto: la respuesta trae todas las plantillas del tipo, y esta plantilla declara cuatro claves).

Para usar una, hay dos momentos:

• Al emitir, manda su id en templateId de POST /{tenantSlug}/dte. El documento queda asociado a esa plantilla: el PDF, el enlace del correo al receptor y la vista pública salen con ella. Usa un id de la lista de ese mismo tipo de documento; si el id no existe, la emisión no falla, pero el documento queda con la plantilla por defecto.
• Al descargar, GET /{tenantSlug}/dte/{id}/pdf?template_id=… genera el PDF de un documento ya emitido con otra plantilla, sin cambiar la que tiene asociada. Las plantillas que aplican a ese documento las lista GET /{tenantSlug}/dte/{id}/templates.

En modo de prueba

Un documento de prueba se representa con la plantilla estándar de la plataforma aunque lo hayas emitido con templateId. Para verlo con la tuya, pídela al descargar con ?template_id=.

Por ejemplo, una boleta exenta con la tarjeta del profesional que realiza la atención:

{
  "tipoDte": "BOLETA_EXENTA",
  "templateId": "tpl_dte41_005",
  "metadataAdicional": {
    "NombreProfesional": "Francisca Soto Martínez",
    "EspecialidadProfesional": "Médico Psiquiatra",
    "RutProfesional": "15.234.567-8",
    "RCMProfesional": "54218"
  }
}

(Sólo los campos de la plantilla: el emisor, el receptor y las líneas van como en cualquier emisión).

Metadata para la representación impresa

metadataAdicional es un objeto de pares clave-valor que se guarda como JSON junto al documento. No viaja al SII: no forma parte del XML firmado ni entra en el timbre. Sirve para alimentar la plantilla PDF de tu empresa con datos que el formato tributario no tiene dónde poner —el número de orden de compra, el centro de costo, el período facturado— y para dejarlos consultables después.

{
  "emisorDteId": "clxyz123abc456def",
  "tipoDte": "FACTURA_AFECTA",
  "receptor": { "rut": "77438768-4", "razonSocial": "REDCUMBRE SPA", "giro": "VENTA AL POR MENOR", "direccion": "LOS PEUMOS ST. 3 LT B", "comuna": "BULNES" },
  "lineas": [{ "nombre": "Servicio de consultoría", "cantidad": 1, "precioUnitario": 100000, "subtotal": 100000 }],
  "metadataAdicional": {
    "NumOrdenCompra": "OC-12345",
    "CentroCosto": "CC-001",
    "PeriodoFacturado": "FEB de 2026"
  }
}

Cinco cosas que conviene saber antes de usarlo:

• Las claves las define la plantilla PDF, no la API. No hay lista de nombres válidos ni tope de cantidad: lo que mandes se guarda tal cual. Las que imprime cada plantilla están en clavesMetadataAdicional de GET /{tenantSlug}/dte/templates/{codigoSii} (Elegir la plantilla del PDF); una clave que tu plantilla no declara queda almacenada y consultable, pero no se imprime en ninguna parte.
• Ninguna clave es obligatoria. Si no mandas una, la emisión sigue igual y la plantilla simplemente no imprime esa parte.
• Manda los valores como string. Es lo que declara el schema (additionalProperties: string) y lo que la plantilla espera recibir.
• No lo uses para datos que sí tienen campo propio. Un dato que el SII debe ver —referencias, descuentos, glosa del ítem— puesto acá no llega al documento tributario.
• Vuelve en el detalle del documento. GET /{tenantSlug}/dte/{id} lo devuelve en metadataAdicional, y null si no mandaste nada.

Si vienes de la guía SOAP, una convención no se traslada

La integración XML Format1 llena este mismo campo desde <Adicional>, con claves numeradas Uno…Veintiocho, y ahí dos posiciones tienen efecto sobre el receptor: Treintaydos puede convertirse en su email y Treintaytres en su teléfono. Por REST eso no ocurre: acá metadataAdicional es inerte y los contactos van en receptor.email y receptor.telefono. La numeración tampoco es un requisito de la API REST — es el vocabulario de ese XML.

Idempotencia

idempotencyKey (máximo 128 caracteres) protege contra reintentos por timeout o doble click. Si ya existe un documento emitido para la misma combinación de emisor, ambiente, tipo y clave, se devuelve el original sin crear uno nuevo ni consumir folio.

Dos cosas que conviene tener claras antes de integrar:

• El ambiente forma parte del alcance. La misma clave puede usarse una vez en certificación y una vez en producción. Cuando pases tu emisor a producción, las claves que gastaste probando no te devuelven los documentos de prueba: emiten los reales.
• Anular libera la clave. Un documento anulado deja de ocuparla y la misma clave vuelve a emitir uno nuevo.

Un reintento sobre una clave ya usada responde 201 con "idempotent": true y el documento original en data.dte — con el folio, el receptor y los montos de la primera emisión, no los del payload que acabas de mandar. El campo a mirar para distinguir “emití” de “ya estaba emitido” es idempotent, no el status.

Ver Reglas transversales.

Restricciones que conviene conocer antes

Estas son las que se descubren con un 400 en runtime si no se saben de antemano.

El precio que mandas es el precio final: las promociones no se aplican por API

Una venta emitida por la API de integración no recibe las promociones vigentes del tenant. El precioUnitario que envías en cada línea es el que se factura, sin descuentos automáticos.

En boleta afecta (39), precioUnitario es el precio con IVA incluido

En el resto de los documentos precioUnitario es neto (sin IVA). En BOLETA_AFECTA es el precio final que ve el cliente, IVA incluido, y el montoTotal emitido es exactamente la suma de las líneas que mandaste — para cualquier monto entero, no sólo los que dan un neto exacto. Si en vez de eso ya tienes el neto calculado, manda "montoNeto": true en el cuerpo y precioUnitario vuelve a interpretarse sin IVA. Ver el ejemplo en Boleta Afecta (39).

Es deliberado, no una limitación pendiente: quien integra por API ya calculó lo que va a cobrar. Un ERP que manda una línea de $10.000 y recibe una boleta por $6.666 lo trataría como un error — con razón, porque su propio cálculo dejó de ser el que salió en el documento.

Lo mismo aplica al endpoint XML (dte_xml_format1).

Si tu tenant usa promociones en el punto de venta

Una misma venta puede salir con precios distintos según por dónde entre. Un “3x2” configurado en Redcumbre se aplica en el punto de venta y en el portal, y no se aplica en lo que emitas por esta API. Si necesitas que el descuento aparezca en el documento, calcúlalo en tu sistema y manda el precio ya rebajado.

Precio unitario: el mínimo es 1, no 0

Cada línea debe tener precioUnitario >= 1. Un 0 se rechaza:

{ "statusCode": 400, "message": "El precio unitario debe ser al menos 1 en cada línea. 1 línea(s) tienen precio inválido." }

Hay tres excepciones, donde sí se aceptan líneas en 0:

• Guía de despacho (52) sin precios, cuando se envía marcada como tal
• Nota de crédito o débito (61 / 56) de corrección o anulación sin monto — las que sólo corrigen un texto o anulan, con referencia de código 1 o 2. El SII las certifica con total 0
• Liquidación factura (43), que admite líneas glosa con precio 0 legítimo

El DTO además rechaza valores negativos en precioUnitario.

Cantidad de líneas: depende del canal

No es un número fijo. El máximo lo determina el canal de integración del emisor: 10 líneas de detalle por Portal MiPyme, 60 con firma local y 500 por la API Oficial SII de boletas. Si te pasas:

{ "statusCode": 400, "message": "El documento tiene 12 líneas de detalle, pero el emisor ... permite máximo 10. Reduzca la cantidad de líneas." }

El mensaje te dice el máximo aplicable a tu emisor. No lo asumas desde el código.

Largo del nombre de ítem: se trunca, no se rechaza

El campo nombre acepta hasta 255 caracteres y no falla si te pasas de 80. Lo que ocurre es que al enviarlo al SII se trunca a 80, que es el límite del organismo. El dato completo queda guardado en la plataforma y aparece íntegro en el PDF interno; el que viaja al SII va cortado.

Si el nombre importa entero en el documento tributario, mantenlo bajo 80 caracteres. Para detalle largo existe descripcionExtendida (hasta 1.000 caracteres), que no viaja al SII.

Revertir una Liquidación Factura (43)

Un DTE 43 no se anula con nota de crédito ni de débito. Si lo intentas:

{ "statusCode": 400, "message": "Las Liquidaciones Factura (DTE 43) no pueden anularse con Nota de Crédito. Emita una nueva Liquidación Factura con valores negativos referenciando el documento original." }

La vía correcta es emitir otra liquidación con valores negativos, referenciando la original.

Y acá hay una asimetría que conviene entender, porque contradice la intuición:

• Las líneas de detalle no admiten valores negativos. El esquema XML del SII lo prohíbe.
• Las comisiones sí conservan el signo. Una comisión negativa —una devolución o un reverso— debe ir con su signo. Si se enviara en valor absoluto, la suma por línea contradiría el resumen de totales y el SII rechazaría el documento.

O sea: el signo de la reversión vive en las comisiones, no en las líneas.

Transporte en la guía de despacho y en facturas que amparan traslado (Res. Ex. SII N° 154/2025)

La Res. Ex. SII N° 154/2025 exige más datos de transporte en la guía de despacho (52) y los exige también en una factura (33, 34 o 46) cuando ampara un traslado de bienes. La norma rige desde el 2026-11-01, pero la Res. Ex. SII N° 52/2026 permite aplicarla antes de forma voluntaria, y la plataforma ya la aplica: desde el 2026-10-20 la API exige estos campos en todo documento que emites.

A quién aplica y desde cuándo

Documento	¿Cuándo aplica?
Guía de despacho (tipoDte: "GUIA_DESPACHO")	Siempre que amparas un traslado, que es su propósito
Factura afecta o exenta (33, 34) y Factura de Compra (46)	Sólo si mandas transporte.amparaTraslado: true. Sin esa marca, el documento no cambia

La fecha que decide si la regla se exige es la posterior entre hoy (hora de Chile) y la fechaEmision que mandas, y se compara con el 2026-10-20, el día desde el que la plataforma la aplica: como hoy ya es posterior, todo documento que emites queda dentro de la exigencia, aunque su fechaEmision sea anterior. Tres campos eran obligatorios en la guía desde antes de esta regla, con cualquier fecha: transporte.destino.comuna, el origen (dirección y comuna juntas, no una sola) y cantidad > 0 en cada línea.

Si falla la regla, la petición responde 400 y no se reserva folio ni se crea el documento: puedes corregir y reintentar sin dejar folios huérfanos.

Los campos nuevos de transporte

Campo	Formato / largo máximo	¿Obligatorio?
transporte.horaSalida	HH:MM:SS, de 00:00:00 a 23:59:59, hora de America/Santiago	No — ver La fecha y la hora de salida
transporte.fechaLlegada	YYYY-MM-DD, igual o posterior a la fecha de emisión (que es la fecha de salida). Ver fechaLlegada es obligatoria	Sí, siempre
transporte.origen.direccion	Hasta 60 caracteres	Sí (en la guía, desde antes de esta regla)
transporte.origen.comuna	Hasta 20 caracteres	Sí (idem)
transporte.origen.ciudad	Hasta 20 caracteres	No
transporte.destino.direccion	Hasta 70 caracteres	Sí
transporte.destino.comuna	Hasta 20 caracteres	Sí (en la guía, desde antes de esta regla)
transporte.destino.ciudad	Hasta 20 caracteres	No
transporte.vehiculo.patente	Hasta 8 caracteres tras normalizar. Informada o declarada desconocida	Sí
transporte.vehiculo.patenteCarro	Hasta 8 caracteres tras normalizar. Informada, declarada desconocida, o transporte.vehiculo.sinCarro: true	Sí
transporte.chofer.rut y transporte.chofer.nombre (≤ 30)	Los dos juntos, o declarados desconocidos	Sí
transporte.transporte.rut (empresa transportista)	RUT con dígito verificador válido. Informado, o transporte.emisorTransporta: true, o declarado desconocido	Sí
transporte.trasladoProlongado.motivo	Hasta 200 caracteres	Sólo si fechaLlegada es posterior a la fecha de emisión
guiaDespacho.motivoTraslado	Hasta 200 caracteres	Sólo si guiaDespacho.sinPrecios: true y el tipo de traslado no importa venta (ver más abajo)
lineas[].unidadMedida	Hasta 4 caracteres	Sí, en cada línea

Ninguno de estos largos se trunca en silencio: si te pasas, la petición responde 400 nombrando el campo de la API (no el tag del XML) y el máximo. El detalle completo de cada campo —tipo, ejemplo, qué DTO lo contiene— está en el esquema TransporteDto de la especificación OpenAPI.

El servidor normaliza vehiculo.patente y vehiculo.patenteCarro: les quita espacios, puntos y guiones y las deja en mayúsculas antes de validar el largo y de escribirlas en el documento. "ab-cd 12" se guarda y se emite como "ABCD12".

El origen se declara completo o no se declara

Si mandas transporte.origen, tiene que traer direccion y comuna juntas. El servidor nunca completa lo que falta con la dirección de tu sucursal: un origen a medias sale rechazado con 400, con cualquier fecha de emisión. Si no declaras transporte.origen, se usa la dirección registrada de la sucursal emisora.

La fecha de salida es la de emisión, la hora es opcional

transporte.fechaSalida no existe en el contrato: no lo mandes. La fecha de salida (FchSalida del XML y «Fecha de salida» del PDF) siempre es la fecha de emisión del documento (fechaEmision), porque ese es el día en que empieza el traslado. Si tu sistema todavía manda transporte.fechaSalida, el servidor lo descarta en silencio (igual que cualquier campo no reconocido) y responde 200: no valida ni usa ese valor.

La hora de salida (transporte.horaSalida) es opcional (Res. Ex. SII N° 144/2026, 7°.4) y es la del inicio del traslado. Va sólo si la mandas, con cualquier fecha de emisión, y se respeta tal cual (validando el formato). Sin ella, la guía sale sin <HraSalida> y el PDF no imprime hora. El servidor no la deriva de la emisión.

Una factura (33, 34 o 46) con transporte.amparaTraslado: true sigue la misma regla de hora, pero no admite fecha de emisión futura — con una fecha posterior a hoy responde 400 citando el art. 55 del DL 825, porque una factura con fecha posterior mueve el IVA al período de esa fecha.

Guías anticipadas: tope de tres días

Puedes emitir una guía de despacho con fechaEmision futura, hasta tres días corridos contados en hora de Chile desde hoy. Con una fecha más lejana, la petición responde 400 nombrando fechaEmision y la última fecha permitida. El tope es el mismo en la API, en el formulario web y en la emisión masiva: no depende de ninguna configuración de tu empresa.

Una vez emitida, la fecha de emisión de una guía no se puede editar. Si el traslado efectivo termina ocurriendo un día distinto del que declaraste al emitir, anula esa guía y emite una nueva con la fecha correcta — ver Guía de Despacho (52): anular, reemplazar y Libro de Guías más abajo. El Libro de Guías imputa cada guía al período de su fechaEmision, no al del envío al SII: una guía anticipada que emites en octubre con fechaEmision de noviembre aparece en el libro de noviembre, no en el de octubre.

Si integras por emisión masiva (carga de Excel), la plantilla no trae columnas FECHA_SALIDA ni HORA_SALIDA: la fecha de salida es la fecha de emisión que eliges al iniciar la carga. La hora es opcional: con una fecha futura, si la eliges en el asistente aplica a todas las guías de la carga; con la fecha de hoy, las guías salen sin hora.

indicadorTraslado y guiaDespacho.tipoTraslado no son el mismo dato

Son dos campos independientes del mismo documento, con dos catálogos distintos. Confundirlos es el error más común al integrar la 52:

Campo	Qué describe	Valores	Tag del XML
transporte.indicadorTraslado	Quién recibe el despacho — el modo de despacho	0 (no aplica, se omite el tag), 1 «Despacho por cuenta del receptor del documento (comprador)», 2 «Despacho por cuenta del emisor a instalaciones del cliente», 3 «Despacho por cuenta del emisor a otras instalaciones»	TipoDespacho
guiaDespacho.tipoTraslado	Por qué se traslada — el motivo tributario del traslado, exclusivo de la 52	1 a 9 (venta, ventas por efectuar, consignación, entrega gratuita, traslado interno, otros traslados no venta, devolución, exportación no venta, venta para exportación)	IndTraslado

El nombre indicadorTraslado es histórico — así se llamó en la API desde el inicio, y se conserva para no romper a quien ya integra— pero el valor que lleva no es un IndTraslado: es el TipoDespacho del XSD del SII. Si tu sistema fuente tiene un único campo “tipo de traslado” con una escala de 9 valores, ese va en guiaDespacho.tipoTraslado, no en transporte.indicadorTraslado.

Declarar un dato desconocido: nunca el destino

Al momento de emitir no siempre tienes los cuatro datos del vehículo y el transporte. La Res. 154 permite declarar que los desconoces en vez de omitirlos sin decir nada, con transporte.datoDesconocido:

Dato	Lo informas con	Lo declaras desconocido con	Otra forma
Patente del vehículo	vehiculo.patente	datoDesconocido.patente: true	—
Patente del carro o remolque	vehiculo.patenteCarro	datoDesconocido.patenteCarro: true	vehiculo.sinCarro: true, si el traslado no usa carro
Transportista	transporte.transporte.rut, o emisorTransporta: true si lo transporta el emisor	datoDesconocido.transportista: true	—
Chofer	chofer.rut y chofer.nombre, los dos	datoDesconocido.chofer: true	—

Informar un dato y declararlo desconocido a la vez es una contradicción: responde 400 nombrando el campo repetido. El destino no entra en esta lista: transporte.destino no admite declararse desconocido con cualquier fecha de emisión — siempre se informa.

El transportista y el chofer pueden ser la misma persona

Si transporte.transporte.rut y transporte.chofer.rut llegan iguales, la guía se emite igual: no es un error. La respuesta trae en advertencias el texto «El transportista y el chofer son la misma persona. ¿Es un transportista independiente?», sin bloquear nada — cubre al transportista independiente, que es las dos cosas a la vez.

En el XML, una patente declarada desconocida lleva Sin Dato en <Patente> o <PatenteCarro> (Res. Ex. SII N° 144/2026, 4°). El chofer y el transportista desconocidos se omiten: el formato del SII sólo admite un RUT en esos campos. Portal MiPyme no escribe Sin Dato en sus campos: la declaración va sólo en el detalle. En integración a medida (API_EXTERNA) la declaración no queda en el documento tributario: ver el límite conocido.

Lo que declaras queda como texto en el detalle de la primera línea (descripcionExtendida), con el prefijo Res. Ex. SII N° 144/2026:, separado por | de lo que tú escribiste. Por ejemplo, si declaras datoDesconocido.chofer: true y vehiculo.sinCarro: true, el detalle de la línea 1 queda así:

Despacho de mercadería | Res. Ex. SII N° 144/2026: Chofer: Sin Dato; el traslado no usa carro ni remolque

Ese bloque cuenta contra el largo máximo de 1.000 caracteres de descripcionExtendida. Si no cabe, la petición responde 400 nombrando lineas[0].descripcionExtendida: no se trunca.

fechaLlegada es obligatoria en la guía de despacho

transporte.fechaLlegada es, de los campos nuevos, el único que Swagger publica como obligatorio (required: true) en el esquema: toda guía de despacho vigente la necesita, sin excepción y sin valor por defecto. La plataforma nunca copia la fecha de emisión en su lugar si la omites.

Por qué es obligatoria: el formato DTE v2.5 que exige la Res. 154 agrega FchLlegada al bloque <Transporte> del XML, y el SII la espera siempre que hay traslado, para saber cuándo termina.

Cómo llenarla:

• Si el traslado llega el mismo día, usa la misma fecha que fechaEmision (que es la fecha de salida).
• Si dura más de un día (traslado prolongado), pon la fecha estimada de entrega en fechaLlegada y agrega transporte.trasladoProlongado.motivo (hasta 200 caracteres) explicando por qué. Sin el motivo, la petición responde 400 nombrando transporte.trasladoProlongado.motivo.

Si la omites en una guía vigente, la petición responde 400:

{
  "statusCode": 400,
  "message": "Falta `transporte.fechaLlegada`: la guía de despacho exige la fecha de llegada (formato DTE v2.5). Si el traslado llega el mismo día de la emisión, va la misma fecha de emisión; si dura más de un día, declara el traslado prolongado con `transporte.trasladoProlongado.motivo` y la fecha estimada de entrega en `transporte.fechaLlegada`."
}

Un traslado prolongado también queda declarado en el detalle de la primera línea:

Res. Ex. SII N° 144/2026: Traslado prolongado: Ruta a Punta Arenas. Fecha estimada de entrega: 04-11-2026

Guardar un borrador no exige nada de esto — puedes guardar una guía incompleta y completarla después. La regla se aplica recién al emitir el borrador (POST /{tenantSlug}/dte/{id}/emitir).

Guía sin precios: cuándo exige el motivo del traslado

Si mandas guiaDespacho.sinPrecios: true, la exigencia depende de guiaDespacho.tipoTraslado (IndTraslado):

• Con tipo 1 (constituye venta) o 9 (venta para exportación), no puedes ir sin precios: la petición responde 400 nombrando guiaDespacho.sinPrecios. Esos traslados importan venta y el SII exige el precio de cada línea.
• Con cualquier otro tipo (2 a 8), puedes ir sin precios, pero tienes que informar guiaDespacho.motivoTraslado (hasta 200 caracteres) con el motivo detallado del traslado — tipoTraslado por sí solo no alcanza. El motivo queda en la declaración de la primera línea.

El límite conocido en integración a medida (API_EXTERNA)

Si tu emisor usa el canal Integración a medida y tu sistema propio arma el XML (hoy, el caso de una integración Softland), la API valida y guarda en la plataforma todos los datos de transporte que mandes, y el PDF interno que genera rCAPI (DtePdfInternoService) los muestra completos. Pero el XML que termina armando ese sistema externo es más limitado:

• Sí lleva: Patente, RUTTrans (con el RUT del chofer, no del transportista, que es un dato erróneo según la Res. 154), DirDest, CmnaDest, CiudadDest y TipoDespacho.
• No lleva: RUTChofer, NombreChofer, PatenteCarro, las fechas y la hora de salida, la fecha de llegada, el origen declarado, ni la declaración de la Res. Ex. SII N° 144/2026 que queda en descripcionExtendida.

Por eso, si una guía 52 por este canal declara un dato faltante o un traslado prolongado, la emisión sigue adelante y la respuesta trae en advertencias: «Por este carril, la declaración no queda en el documento tributario, sólo en el PDF interno. Un traslado de más de un día vale sólo por la fecha de emisión, salvo que emitas una guía por etapa.» Declarar un dato faltante sigue siendo tu responsabilidad.

Es un límite conocido de ese driver, no de la API: si integras por este canal, el documento tributario que llega al SII no trae todavía el bloque de transporte completo de la Res. 144, aunque la plataforma ya lo tenga guardado. Para el bloque <Transporte> completo en el XML, integra por Portal MiPyme o por firma local (FULL_DTE).

Guía de Despacho (52): anular, reemplazar y Libro de Guías

Una guía de despacho no genera débito ni crédito, así que no se rectifica con nota de crédito ni de débito. Lo que pide el SII es que declares en el Libro de Guías de Despacho qué le pasó a cada guía: si se anuló, si se reemplazó o si se recibió sólo en parte. La API cubre las tres cosas.

Referenciar una guía: codigoReferencia es opcional

La <Referencia> de una guía 52 no lleva código de referencia. Por eso, en el arreglo referencias de una 52, codigoReferencia se puede omitir: la validación pasa y el XML sale sin <CodRef>. En la nota de crédito (61) y la nota de débito (56) sigue siendo obligatorio.

{
  "tipoDte": "GUIA_DESPACHO",
  "guiaDespacho": { "tipoTraslado": 1 },
  "referencias": [
    { "tipoDocumento": 52, "folio": "100", "fecha": "2026-10-02", "razonReferencia": "Cambio de patente" }
  ]
}

La relación inversa tampoco existe: una nota de crédito o de débito no puede referenciar una guía. Si lo intentas, responde 400 con code: "NOTA_SOBRE_GUIA". La guía se anula o se reemplaza con las operaciones de abajo.

Anular una guía

POST /{tenantSlug}/dte/{id}/anular

{id} es el id de la guía que devolvió la emisión (data.dte.id). Necesitas el permiso DTE_52_ANULAR. La operación es síncrona y no envía nada al SII: deja registrada la anulación en la plataforma y la incorpora al Libro de Guías.

Campo	Obligatorio	Qué es
motivo	Sí	Uno de CAMBIO_ORIGEN_DESTINO, CAMBIO_CHOFER_TRANSPORTISTA, CAMBIO_PATENTE, CAMBIO_BIENES, CAMBIO_RECEPTOR, ERROR_DIGITACION, OPERACION_NO_REALIZADA, RECEPCION_PARCIAL u OTRO
descripcion	No	Detalle libre del motivo, hasta 500 caracteres
recepcionParcial	No	true si los bienes se recibieron sólo en parte: la guía sigue vigente y queda modificada
montoModificado	No	Monto en pesos (entero, 0 o más) tras la recepción parcial. Sólo se acepta con recepcionParcial: true

CAMBIO_RECEPTOR cubre el caso de cambiar el intermediario o el cliente de la carga. No es uno de los casos a) a d) de la Res. 154 que la ley obliga a reemplazar: anular con este motivo es válido por sí solo, no exige que además emitas una guía de reemplazo.

curl -X POST https://api.redcumbre.cl/tu-tenant/dte/dte_5fe4ff45-.../anular \
  -H "Authorization: Bearer $REDCUMBRE_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "motivo": "ERROR_DIGITACION",
    "descripcion": "Patente mal digitada"
  }'

Respuesta (200), sin el envoltorio success / data:

{
  "anulacion": {
    "id": "cm5guia123",
    "dteId": "dte_5fe4ff45-...",
    "codigo": 2,
    "motivo": "ERROR_DIGITACION",
    "descripcion": "Patente mal digitada",
    "montoModificado": null,
    "guiaReemplazoId": null,
    "periodo": "2026-10",
    "registradaEn": "2026-10-17T15:04:05.000Z",
    "autor": { "tipo": "llave", "id": "17" }
  },
  "dte": {
    "id": "dte_5fe4ff45-...",
    "estado": "ANULADO",
    "estadoSii": "ACEPTADO",
    "folio": 1234
  },
  "libro": { "periodoCerrado": false, "ajustePendiente": false },
  "aviso": "API_EXTERNA_NO_PROPAGA"
}

El código lo deriva el sistema

No envías el código del libro: lo calcula la plataforma según el estado de la guía.

codigo	Cuándo	Qué pasa con la guía
1	La guía tiene folio pero falló al emitirse y nunca llegó al SII	Queda ANULADO. En el libro entra como folio anulado
2	La guía está vigente, o falló habiendo llegado al SII	Queda ANULADO. En el libro entra como guía anulada
3	Mandaste recepcionParcial: true sobre una guía vigente	No cambia de estado: sigue vigente y el libro lleva su monto modificado

En los códigos 1 y 2 el estadoSii no cambia: conserva el veredicto que el SII dio a la guía. anulacion.periodo es el mes de la fecha de emisión de la guía (AAAA-MM).

Avisos

aviso es null salvo que la anulación no se propague sola al otro sistema:

aviso	Cuándo	Qué debes hacer
MIPYME_REGISTRAR_EN_SII	La guía se emitió por Portal MiPyme	Registra la anulación también en el portal del SII: rCAPI no firma el libro de esos emisores
API_EXTERNA_NO_PROPAGA	La guía se emitió desde un ERP externo	La anulación queda en rCAPI y en el Libro de Guías, pero no se avisa al ERP: regístrala allá

Idempotencia

Una guía se anula una sola vez. Repetir la llamada con el mismo cuerpo devuelve 200 con la misma anulación y no vuelve a publicar el webhook. Repetirla con un cuerpo distinto (otro motivo, otro monto, o recepcionParcial distinto) responde 409 con GUIA_YA_ANULADA_DISTINTA. No necesitas idempotencyKey: el id de la guía en la ruta cumple ese papel.

Errores

Status	code	Causa
400	NOTA_DE_RECEPCION_PARCIAL_SIN_FLAG	Mandaste montoModificado sin recepcionParcial: true
400	—	El documento no es una guía 52, o el cuerpo es inválido
403	—	Falta el permiso DTE_52_ANULAR
404	—	La guía no existe en tu tenant
409	GUIA_RECHAZADA_SII	El SII rechazó la guía: nunca fue válida, no se anula acá. El folio entra solo al libro como anulado

Un folio con GUIA_RECHAZADA_SII no se anula con esta ruta porque no hay nada que anular: ante el SII ese folio nunca existió. El Libro de Guías lo detecta solo y lo incluye como folio anulado (código 1) mientras siga rechazado. Si además quieres darlo de baja ante el SII como folio no usado, hazlo con /{tenantSlug}/admin/folios-caf, no con esta ruta. | 409 | GUIA_EN_CURSO | La guía sigue en trámite ante el SII: espera su resultado | | 409 | GUIA_SIN_FOLIO | Todavía no tiene folio: no hay documento que anular | | 409 | GUIA_FACTURADA | Una factura vigente la referencia: anula o corrige la factura primero. La recepción parcial (código 3) sí se puede declarar | | 409 | GUIA_NO_VIGENTE | La guía no está vigente y no admite esta anulación; por ejemplo, una recepción parcial sobre una guía que falló al emitirse | | 409 | GUIA_CON_REEMPLAZO_EN_CURSO | Tiene un reemplazo pendiente: espera su resultado | | 409 | GUIA_YA_ANULADA_DISTINTA | Ya tiene una anulación registrada con datos distintos |

Ramifica por code, no por el texto del mensaje: el texto es para una persona y puede cambiar.

Cuando la anulación se registra, la plataforma publica el webhook dte.guia_anulada (códigos 1 y 2) o dte.guia_modificada (código 3).

Reemplazar una guía

POST /{tenantSlug}/dte/{id}/reemplazar

Reemplazar es emitir una guía nueva que referencia a la anterior. Necesitas los dos permisos: DTE_52_EMITIR y DTE_52_ANULAR. El cuerpo es el de emisión de una 52, con estas diferencias:

• tipoDte es siempre GUIA_DESPACHO.
• idempotencyKey es obligatoria y debe ser distinta de la de la guía que reemplazas. Si coincide, responde 409 con IDEMPOTENCY_KEY_DE_LA_REEMPLAZADA.
• Agregas motivo (el mismo catálogo de la anulación) y, si quieres, descripcion.
• No se envían saveAsDraft ni borradorId: un reemplazo no se guarda como borrador.

No hace falta que agregues la referencia a la guía anterior: la plataforma la pone primero (tipo 52, sin codigoReferencia) y respeta las demás referencias que mandes.

curl -X POST https://api.redcumbre.cl/tu-tenant/dte/dte_5fe4ff45-.../reemplazar \
  -H "Authorization: Bearer $REDCUMBRE_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "emisorDteId": "clxyz123abc456def",
    "tipoDte": "GUIA_DESPACHO",
    "motivo": "CAMBIO_PATENTE",
    "guiaDespacho": { "tipoTraslado": 1 },
    "receptor": { "rut": "77438768-4", "razonSocial": "REDCUMBRE SPA", "giro": "COMERCIO", "direccion": "LOS PEUMOS ST. 3 LT B", "comuna": "BULNES" },
    "lineas": [{ "nombre": "Pallet de insumos", "cantidad": 10, "precioUnitario": 5000, "subtotal": 50000 }],
    "idempotencyKey": "reemplazo-guia-1234-patente"
  }'

La respuesta (200) es la de la emisión —data.dte, data.montos, data.urls— más data.reemplazo:

{
  "success": true,
  "data": {
    "modo": "ASINCRONO",
    "dte": { "id": "dte_9a8b7c6d-...", "tipoDte": "GUIA_DESPACHO", "folio": 1235, "estado": "EMITIDO" },
    "reemplazo": { "guiaAnteriorId": "dte_5fe4ff45-...", "estado": "PENDIENTE" }
  }
}

data.dte.id es la guía nueva; data.reemplazo.guiaAnteriorId, la reemplazada. El estado del reemplazo es:

reemplazo.estado	Qué significa	La guía anterior
PENDIENTE	La guía nueva todavía no queda vigente ante el SII	Sigue vigente
REGISTRADA	La nueva quedó vigente	Queda ANULADO con código 2
DESCARTADA	La nueva se rechazó o falló	Sigue vigente

La anterior sólo se anula cuando la nueva queda vigente: si el SII rechaza la nueva, el traslado no se queda sin guía. Mientras el reemplazo está PENDIENTE no puedes anular (códigos 1 o 2) ni volver a reemplazar la anterior (409 con GUIA_CON_REEMPLAZO_EN_CURSO). Para saber cómo terminó, consulta la guía o espera el webhook dte.guia_anulada, que trae guiaReemplazoId.

Sólo se reemplaza una guía vigente. Una guía que falló al emitirse responde 409 con GUIA_NO_VIGENTE: anúlala con /anular y emite una guía nueva sin referencia. Si la guía sigue en trámite ante el SII, responde 409 con GUIA_EN_CURSO.

La emisión del reemplazo se cobra como cualquier emisión de DTE. La anulación, no.

Libro de Guías de Despacho

El Libro de Guías de Operación declara al SII, mes a mes, las guías de cada emisor con sus anulaciones y modificaciones. rCAPI lo arma, lo firma, lo custodia y lo deja a tu disposición para que lo consultes o lo exhibas cuando el SII lo pida.

• Cuándo se cierra. El período anterior queda PROVISORIO hasta el día 10: se calcula al momento, pero no se firma. El día 11 a las 05:00 (hora de Chile) se genera el cierre definitivo, que se firma y se guarda.
• A quién alcanza. Emisores de firma local (FULL_DTE) y de integración a medida (API_EXTERNA). En los emisores de Portal MiPyme rCAPI no firma el libro: el emisor declara la anulación en el portal del SII, como indica el aviso MIPYME_REGISTRAR_EN_SII.
• Si eres API_EXTERNA y también emites guías por otro sistema, el libro legal de rCAPI sólo incluye las guías emitidas por esta plataforma. Consolidarlo con las que emitiste por tu otro sistema es responsabilidad tuya: rCAPI no las conoce ni las suma.
• Si anulas después del cierre, el período CERRADO no se reescribe: la anulación sale en un envío adicional de tipo AJUSTE. Mientras ese envío no sale, el período aparece con ajustePendiente: true.
• Servicio y permisos. Las tres rutas exigen el servicio DTE_52 habilitado en tu tenant y el permiso DTE_52_VER. Sin alguno de los dos, responden 403.

Listar los períodos

GET /{tenantSlug}/libros/guias

Parámetro	Obligatorio	Qué es
emisorRut	No	Limita a un emisor, con guion y dígito verificador (71669300-7)
periodoDesde, periodoHasta	No	Rango de períodos, formato AAAA-MM
page, limit	No	Paginación (por defecto, página 1 de 20)

{
  "data": [
    {
      "id": "cm5libro123",
      "emisorRut": "71669300-7",
      "emisorRazonSocial": "EMPRESA SPA",
      "periodo": "2026-10",
      "estado": "CERRADO",
      "motivoPendiente": null,
      "ajustePendiente": false,
      "totales": { "guias": 40, "anuladas": 2, "foliosAnulados": 0, "venta": 35, "montoVenta": 4200000 },
      "envios": [
        {
          "id": "cm5envio123",
          "tipoEnvio": "TOTAL",
          "numeroSegmento": null,
          "firmadoEn": "2026-11-11T08:00:12.000Z",
          "hashSha256": "9f2c...e1",
          "conservarHasta": "2034-11-30T00:00:00.000Z"
        }
      ]
    }
  ],
  "meta": { "total": 1, "page": 1, "limit": 20 }
}

estado puede ser:

estado	Significado
ABIERTO	Período en curso: totales calculados al momento, sin envíos
PROVISORIO	Período anterior antes de su cierre del día 11: totales al momento, sin envíos
CERRADO	Cerrado, firmado y custodiado; envios lista los archivos
CIERRE_PENDIENTE	El cierre no pudo firmarse; motivoPendiente dice por qué y el cierre se reintenta solo

motivoPendiente es EMISOR_SIN_CERTIFICADO, CERTIFICADO_VENCIDO o EMISOR_SIN_RESOLUCION_SII. En los períodos ABIERTO y PROVISORIO el id viene en null.

totales.anuladas cuenta las guías anuladas (código 2) y totales.foliosAnulados, los folios anulados (código 1). tipoEnvio es TOTAL, PARCIAL, FINAL o AJUSTE: un período con más de 5.000 detalles se parte en segmentos. conservarHasta es el piso de conservación legal (6 años), no una fecha de borrado.

Exhibir el libro firmado al momento

GET /{tenantSlug}/libros/guias/exhibir

Genera y firma al momento, sin guardarlo ni enviarlo al SII, el libro de un emisor. Sirve para responder una notificación del SII.

Parámetro	Obligatorio	Qué es
emisorRut	Sí	RUT del emisor
periodoDesde, periodoHasta	Sí	Rango AAAA-MM. Máximo 12 períodos por consulta
folioNotificacion	Sí	Folio de la notificación del SII; va en la carátula del libro
rutReceptor	No	Limita a las guías de un receptor

La respuesta es un archivo, no JSON: un solo libro sale como application/xml; charset=ISO-8859-1; si el rango abarca varios, como application/zip con un XML por período (LGD-<rut>-<AAAA-MM>.xml). Un período sin guías sale como libro firmado sin detalle.

curl -G https://api.redcumbre.cl/tu-tenant/libros/guias/exhibir \
  -H "Authorization: Bearer $REDCUMBRE_API_KEY" \
  --data-urlencode "emisorRut=71669300-7" \
  --data-urlencode "periodoDesde=2026-10" \
  --data-urlencode "periodoHasta=2026-10" \
  --data-urlencode "folioNotificacion=123456" \
  -o libro-guias-2026-10.xml

Status	code	Causa
400	FOLIO_NOTIFICACION_REQUERIDO	Falta folioNotificacion
400	FOLIO_NOTIFICACION_INVALIDO	No es un entero positivo
400	RANGO_DE_PERIODOS_EXCEDIDO	El rango pasa de 12 períodos
404	—	El RUT no es un emisor de tu tenant
409	EMISOR_SIN_CERTIFICADO	El emisor no tiene certificado digital activo para firmar
409	CERTIFICADO_VENCIDO	El certificado del emisor está vencido
409	EMISOR_SIN_RESOLUCION_SII	Al emisor le falta registrar la resolución del SII (número y fecha)

Descargar un envío custodiado

GET /{tenantSlug}/libros/guias/envios/{id}/xml

{id} es el envios[].id del listado. Entrega el XML firmado tal como se guardó, byte a byte, por medio de la API y sin URL pública. La cabecera X-Content-SHA256 trae el hash registrado: calcula el SHA-256 del archivo descargado y compáralo con ella (y con envios[].hashSha256) para comprobar que no cambió. Un envío que no es de tu tenant responde 404.

curl -D - https://api.redcumbre.cl/tu-tenant/libros/guias/envios/cm5envio123/xml \
  -H "Authorization: Bearer $REDCUMBRE_API_KEY" \
  -o envio-cm5envio123.xml

El envío custodiado no es el que exhibes

El archivo custodiado lleva una carátula interna de custodia. Para responder una notificación del SII usa siempre exhibir: genera el libro con el folio de la notificación en la carátula.

Consultar y descargar

Para	Endpoint
Listar documentos	GET /{tenantSlug}/dte
Detalle de uno	GET /{tenantSlug}/dte/{id}
PDF de la plataforma	GET /{tenantSlug}/dte/{id}/pdf (con ?template_id= para otra plantilla)
Plantillas aplicables al documento	GET /{tenantSlug}/dte/{id}/templates
PDF timbrado del SII	GET /{tenantSlug}/dte/{id}/pdf-sii
Estado ante el SII	POST /{tenantSlug}/dte/{id}/verificar-estado-sii
Archivos asociados (XML, PDF)	GET /{tenantSlug}/dte/{id}/archivos
Historial de eventos	GET /{tenantSlug}/dte/{id}/logs

El índice completo de rutas del dominio está en /api-docs/index.txt.

Errores y reintentos

Código	Causa típica	¿Reintentar?
400	Payload inválido, precio bajo el mínimo, exceso de líneas, tipo de referencia no permitido	No. Corrige el payload
403	La API key no alcanza el endpoint, o el servicio de DTE no está habilitado en el tenant	No
404	El emisorDteId no existe en tu tenant	No. Verifícalo en el panel (Configuración → Emisores, campo ID) o en la respuesta de tu tokenización
409	Tu emisor tiene conflictos de sincronización pendientes	No. Se resuelve sobre el emisor; escribe a tu contacto en REDCUMBRE
422	Sin folios CAF disponibles, o límite de crédito del cliente excedido	No. Ver el aviso de abajo
5xx	Falla de la API o del SII	Sí, con backoff. Usa idempotencyKey para que el reintento no duplique

Un rechazo del SII no es un 5xx: el documento se emite y queda con estadoSii en estado de rechazo. Se consulta con verificar-estado-sii, no se reintenta el POST.

CREDENCIAL_PORTAL_RECHAZADA — la emisión por Portal MiPyme está detenida

Cuando el SII rechaza la credencial con la que rCAPI entra a su portal para operar el RUT de tu emisor, la emisión por Portal MiPyme se detiene y la petición falla con este código sin que se llame al SII. No es un rechazo del documento: es que la credencial dejó de servir.

Código	CREDENCIAL_PORTAL_RECHAZADA
¿Reintentar?	No. Reintentar no lo arregla, y cada intento acerca la credencial al bloqueo del SII
Qué dice el mensaje	Nombre y RUT del titular de la credencial, el motivo que dio el SII y qué hacer
Cómo se resuelve	El titular corrige la credencial en el portal del SII, y alguien de tu equipo vuelve a probar la conexión desde rCAPI

Alcanza sólo al canal que entra por el portal del SII. La emisión por servicio web no se detiene: el mismo certificado sigue obteniendo token de semilla y emitiendo con normalidad, porque el ingreso al portal es una habilitación distinta.

Mientras la credencial está rechazada también quedan detenidas la solicitud automática de folios y la sincronización del Registro de Compras y Ventas, por el mismo motivo.

El 422 por falta de folios deja el documento guardado

Cuando no hay folios CAF disponibles, la petición falla con 422 pero el documento queda guardado como borrador. Reintentar el mismo envío no lo emite: acumula borradores. Lo que corresponde es conseguir folios y emitir el borrador existente con POST /{tenantSlug}/dte/{id}/emitir.

Siguiente paso

• Webhooks — enterarte del resultado sin hacer polling
• Reglas transversales — paginación, idempotencia, errores
• Procesos Batch — emisión masiva desde Excel
• Especificación OpenAPI — todos los campos, tipos y esquemas