DTE XML Format1 (AppOctava)

DTE XML Format1 — Compatibilidad AppOctava

TL;DR - Acceso Rápido

Endpoint: POST /{tenantSlug}/dte_xml_format1 Content-Type: application/xml o text/xml Respuesta: text/xml; charset=utf-8 Modo: Síncrono parcial (SINC_PARCIAL)

Este endpoint permite que sistemas que actualmente emiten DTEs usando el protocolo SOAP XML de AppOctava migren a Redcumbre sin modificar su código. El único cambio necesario es la URL del servicio y las credenciales de autenticación.

El endpoint acepta un request SOAP XML con la estructura ProcesaDte, procesa el DTE usando el pipeline de emisión estándar de Redcumbre, y responde en el mismo formato SOAP XML ProcesaDteResponse.

---

Requisitos Previos

• API Key configurada en tu tenant con rol FULL-API (o DTE_ROL_FULL / DTE_ROL_EMISOR)
• Emisor DTE activo registrado en el tenant con el RUT que usarás en el XML
• Content-Type del request configurado como application/xml o text/xml

---

Autenticación

La autenticación se realiza mediante API Key (JWT Bearer Token) en el header HTTP:

Authorization: Bearer <tu_api_key_jwt>

El acceso es por tenant: la URL incluye el {tenantSlug} para identificar la organización.

Requisito	Valor
Header	Authorization: Bearer <jwt>
Rol requerido	FULL-API, DTE_ROL_FULL o DTE_ROL_EMISOR
Tenant	Identificado por {tenantSlug} en la URL

Diferencia con AppOctava

La autenticación NO usa el campo <TOKEN> del XML. Este campo se ignora por completo. Toda la autenticación se realiza a través del header HTTP Authorization.

---

Estructura del Request SOAP XML

El request usa un envelope SOAP estándar con el namespace de AppOctava:

<soapenv:Envelope
    xmlns:soapenv="http://schemas.xmlsoap.org/soap/envelope/"
    xmlns:app="http://www.appoctava.cl">
  <soapenv:Header/>
  <soapenv:Body>
    <app:ProcesaDte>
      <STRINGXML><![CDATA[...DTE XML...]]></STRINGXML>
      <STRINGXMLADICIONAL><![CDATA[...XML adicional...]]></STRINGXMLADICIONAL>
      <TIPOIMPRESO>tpl_dte41_002</TIPOIMPRESO>
      <ASIGNAFOLIO>False</ASIGNAFOLIO>
      <AMBIENTE>1</AMBIENTE>
      <TOKEN>...</TOKEN>
    </app:ProcesaDte>
  </soapenv:Body>
</soapenv:Envelope>

Campos de ProcesaDte

Campo	Tipo	Obligatorio	Descripción
STRINGXML	CDATA	Sí	DTE XML estándar SII embebido en CDATA
STRINGXMLADICIONAL	CDATA	No	XML con campos adicionales (metadata personalizada)
TIPOIMPRESO	String	No	ID del template PDF (ej: tpl_dte41_002). Si no se envía o el ID no existe en el catálogo, usa el default del tenant
SHORTURLS	String	No	Si es True, genera URLs cortas (<255 chars) para PDF/XML. Útil para BD legacy. Ver URLs Cortas
IdempotencyKey	String	No	Clave de idempotencia (max 128 chars). Protege contra emisiones duplicadas por reintentos. Ver Idempotencia
ASIGNAFOLIO	String	No	IGNORADO — el folio siempre se asigna internamente
AMBIENTE	Integer	No	IGNORADO — el ambiente se determina por la configuración del emisor
TOKEN	String	No	IGNORADO — la autenticación es por API Key en header HTTP

---

Estructura del DTE XML (STRINGXML)

Dentro de STRINGXML va el DTE XML con formato estándar SII. La estructura general es:

<DTE version="1.0">
  <Documento ID="F1T33">
    <Encabezado>
      <IdDoc>...</IdDoc>
      <Emisor>...</Emisor>
      <Receptor>...</Receptor>
      <Totales>...</Totales>
    </Encabezado>
    <Detalle>...</Detalle>
  </Documento>
</DTE>

Campos de IdDoc

Campo	Tipo	Obligatorio	Descripción
TipoDTE	Integer	Sí	Código SII del tipo de documento (ver tabla de tipos)
Folio	Integer	No	IGNORADO — el folio se asigna internamente por el SII
FchEmis	String	No	Fecha de emisión en formato YYYY-MM-DD. Si no se envía, usa la fecha actual
FchVenc	String	No	Fecha de vencimiento en formato YYYY-MM-DD
IndServicio	Integer	No	Tipo de venta/servicio: 1 = Servicio periódico domiciliario, 2 = Otros servicios periódicos, 3 = Ventas y servicios, 4 = Espectáculo por cuenta de terceros

Campos de Emisor

Campo	Tipo	Obligatorio	Descripción
RUTEmisor	String	Sí	RUT del emisor (ej: 76123456-7). Se usa para buscar el emisor activo en el tenant
RznSocEmisor	String	No	Razón social del emisor (informativo, no se usa para la emisión)

Resolución de Emisor

El sistema busca automáticamente un emisor DTE activo con el RUT indicado dentro del tenant. Si no se encuentra, retorna un error. No es necesario enviar un emisorDteId.

Campos de Receptor

Campo	Tipo	Obligatorio	Descripción
RUTRecep	String	Sí	RUT del receptor
RznSocRecep	String	Sí	Razón social del receptor
GiroRecep	String	No	Giro comercial del receptor
DirRecep	String	No	Dirección del receptor
CmnaRecep	String	No	Comuna del receptor
CiudadRecep	String	No	Ciudad del receptor
CorreoRecep	String	No	Email del receptor. Si se incluye, se envía automáticamente el PDF del documento por email al receptor después de la emisión exitosa

Campos de Detalle (líneas del documento)

Cada <Detalle> representa una línea del documento. Puede haber múltiples elementos <Detalle>.

Campo	Tipo	Obligatorio	Descripción
NroLinDet	Integer	No	Número de línea (informativo)
NmbItem	String	Sí	Nombre del ítem o servicio
QtyItem	Decimal	Sí	Cantidad
PrcItem	Decimal	Sí	Precio unitario
MontoItem	Decimal	Sí	Subtotal de la línea (cantidad × precio)
IndExe	Integer	No	Si es 1, la línea está exenta de IVA

---

Metadata Adicional (STRINGXMLADICIONAL)

Opcionalmente se puede enviar metadata adicional dentro de STRINGXMLADICIONAL. Esta información se almacena como JSON en el campo metadataAdicional del DTE y queda disponible para templates PDF personalizados.

También disponible via REST

El campo metadataAdicional también se puede enviar en la API REST (POST /{tenantSlug}/dte) como un objeto JSON de pares clave-valor. Esto permite que cualquier integración (no solo AppOctava) almacene metadata personalizada en el DTE.

<Adicional>
  <Uno>valor1</Uno>
  <Dos>valor2</Dos>
  <Tres>valor3</Tres>
  <!-- ... hasta Veintiocho -->
</Adicional>

Los campos son numerados del Uno al Veintiocho. Todos son opcionales y de tipo string. Los campos vacíos se preservan como strings vacíos.

---

Tipos de DTE Soportados

Código SII	Tipo de Documento
33	Factura Afecta
34	Factura Exenta
39	Boleta Afecta
41	Boleta Exenta
43	Liquidación Factura
46	Factura de Compra
52	Guía de Despacho
56	Nota de Débito
61	Nota de Crédito

---

Estructura del Response SOAP XML

La respuesta siempre es un SOAP XML con la estructura ProcesaDteResponse.

Response Exitoso

<?xml version="1.0"?>
<SOAP-ENV:Envelope xmlns:SOAP-ENV="http://schemas.xmlsoap.org/soap/envelope/"
                    xmlns:xsd="http://www.w3.org/2001/XMLSchema"
                    xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
                    xmlns:SOAP-ENC="http://schemas.xmlsoap.org/soap/encoding/">
  <SOAP-ENV:Body>
    <ns1:ProcesaDteResponse xmlns:ns1="http://www.appoctava.cl">
      <return>
        <item>
          <DescripcionResultado>TVAL</DescripcionResultado>
          <IdResultadoFE>0</IdResultadoFE>
          <ResultadoFE>DTE procesado correctamente.</ResultadoFE>
          <UrlPdf>https://api.redcumbre.cl/public/documentos/{token}/pdf</UrlPdf>
          <UrlXmlSii>https://api.redcumbre.cl/public/documentos/{token}/xml</UrlXmlSii>
          <UrlXmlReceptor>https://api.redcumbre.cl/public/documentos/{token}/xml</UrlXmlReceptor>
          <FolioAsignado>37898</FolioAsignado>
          <IdDte>cm8x1y2z3abc456def789</IdDte>
          <TiempoEjecucion>0.96504092</TiempoEjecucion>
        </item>
      </return>
    </ns1:ProcesaDteResponse>
  </SOAP-ENV:Body>
</SOAP-ENV:Envelope>

Response de Error

<?xml version="1.0"?>
<SOAP-ENV:Envelope xmlns:SOAP-ENV="http://schemas.xmlsoap.org/soap/envelope/"
                    xmlns:xsd="http://www.w3.org/2001/XMLSchema"
                    xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
                    xmlns:SOAP-ENC="http://schemas.xmlsoap.org/soap/encoding/">
  <SOAP-ENV:Body>
    <ns1:ProcesaDteResponse xmlns:ns1="http://www.appoctava.cl">
      <return>
        <item>
          <DescripcionResultado>ERROR</DescripcionResultado>
          <IdResultadoFE>1</IdResultadoFE>
          <ResultadoFE>No se encontró un emisor DTE activo con RUT 99999999-9 en el tenant</ResultadoFE>
          <UrlPdf></UrlPdf>
          <UrlXmlSii></UrlXmlSii>
          <UrlXmlReceptor></UrlXmlReceptor>
          <FolioAsignado>0</FolioAsignado>
          <IdDte></IdDte>
          <TiempoEjecucion>0.12345000</TiempoEjecucion>
        </item>
      </return>
    </ns1:ProcesaDteResponse>
  </SOAP-ENV:Body>
</SOAP-ENV:Envelope>

Campos del Response

Campo	Tipo	Éxito	Error	Descripción
DescripcionResultado	String	TVAL	ERROR	Código de resultado
IdResultadoFE	Integer	0	1	0 = éxito, otro valor = error
ResultadoFE	String	Mensaje de éxito	Mensaje descriptivo del error	Descripción del resultado
UrlPdf	URL	URL del PDF	vacío	URL pública para descargar el PDF del DTE. Formato depende de dteTokenMode del tenant (ver URLs Cortas)
UrlXmlSii	URL	URL del XML	vacío	URL pública para descargar el XML del DTE. Mismo formato que UrlPdf
UrlXmlReceptor	URL	URL del XML	vacío	URL pública del XML del DTE (misma que UrlXmlSii)
FolioAsignado	Integer	Folio real	0	Folio asignado por el SII
IdDte	String	CUID	vacío	Identificador único del DTE generado en el sistema
TiempoEjecucion	Decimal	Segundos	Segundos	Tiempo de procesamiento en segundos

---

Campos Ignorados y Comportamiento Automático

Importante para integradores AppOctava

Si migrás desde AppOctava, tené en cuenta que los siguientes campos se comportan diferente:

Campo	Comportamiento en Redcumbre
<Folio> en el XML	IGNORADO — el folio se asigna automáticamente por el SII (Portal MiPyme o CAF según el tipo de DTE)
<ASIGNAFOLIO>	IGNORADO — siempre se asigna internamente
<AMBIENTE>	IGNORADO — el ambiente (certificación/producción) se determina por la configuración del emisor
<TOKEN>	IGNORADO — la autenticación es por API Key en el header HTTP Authorization

Podés seguir enviando estos campos por compatibilidad, pero no tienen efecto.

---

Flujo de Procesamiento

Tu Sistema                          Redcumbre
    │                                   │
    │── POST /{tenantSlug}/dte_xml_format1 ──▶│
    │   Headers:                        │
    │   - Authorization: Bearer <jwt>   │
    │   - Content-Type: application/xml │
    │   Body: SOAP XML (ProcesaDte)     │
    │                                   │
    │                                   │── Parsea SOAP envelope
    │                                   │── Extrae DTE XML de STRINGXML
    │                                   │── Resuelve emisor por RUT
    │                                   │── Emite DTE via SII
    │                                   │── Genera PDF y XML
    │                                   │
    │◀── SOAP XML (ProcesaDteResponse) ─│
    │    - FolioAsignado                │
    │    - UrlPdf                       │
    │    - UrlXmlSii                    │

---

Ejemplo Completo

Request

<soapenv:Envelope xmlns:soapenv="http://schemas.xmlsoap.org/soap/envelope/"
                   xmlns:app="http://www.appoctava.cl">
  <soapenv:Header/>
  <soapenv:Body>
    <app:ProcesaDte>
      <STRINGXML><![CDATA[<DTE version="1.0">
<Documento ID="F1T41">
  <Encabezado>
    <IdDoc>
      <TipoDTE>41</TipoDTE>
      <Folio>0</Folio>
      <FchEmis>2026-02-26</FchEmis>
      <IndServicio>1</IndServicio>
      <FchVenc>2026-03-26</FchVenc>
    </IdDoc>
    <Emisor>
      <RUTEmisor>76123456-7</RUTEmisor>
      <RznSocEmisor>MI EMPRESA SPA</RznSocEmisor>
    </Emisor>
    <Receptor>
      <RUTRecep>12345678-5</RUTRecep>
      <RznSocRecep>JUAN PEREZ GONZALEZ</RznSocRecep>
      <DirRecep>AV. PRINCIPAL 1234</DirRecep>
      <CmnaRecep>SANTIAGO</CmnaRecep>
      <CiudadRecep>SANTIAGO</CiudadRecep>
      <CorreoRecep>juan.perez@ejemplo.cl</CorreoRecep>
    </Receptor>
    <Totales>
      <MntExe>15000</MntExe>
      <MntTotal>15000</MntTotal>
    </Totales>
  </Encabezado>
  <Detalle>
    <NroLinDet>1</NroLinDet>
    <IndExe>1</IndExe>
    <NmbItem>Servicio de Agua Potable - Enero 2026</NmbItem>
    <QtyItem>1</QtyItem>
    <PrcItem>15000</PrcItem>
    <MontoItem>15000</MontoItem>
  </Detalle>
</Documento>
</DTE>]]></STRINGXML>
      <STRINGXMLADICIONAL><![CDATA[<Adicional>
<Uno>1001</Uno>
<Dos>Enero 2026</Dos>
<Tres></Tres>
</Adicional>]]></STRINGXMLADICIONAL>
      <TIPOIMPRESO>tpl_dte41_002</TIPOIMPRESO>
      <IdempotencyKey>servicio-agua-enero-2026</IdempotencyKey>
      <ASIGNAFOLIO>False</ASIGNAFOLIO>
      <AMBIENTE>1</AMBIENTE>
      <TOKEN></TOKEN>
    </app:ProcesaDte>
  </soapenv:Body>
</soapenv:Envelope>

Ejemplo con curl

curl -X POST "https://api.redcumbre.cl/{tenantSlug}/dte_xml_format1" \
  -H "Authorization: Bearer <tu_api_key_jwt>" \
  -H "Content-Type: application/xml" \
  -d @request.xml

Donde request.xml contiene el SOAP envelope completo del ejemplo anterior.

---

URLs Cortas para BD Legacy

Si tu sistema almacena las URLs de documentos (PDF, XML) en campos con límite de 255 caracteres, las URLs estándar con JWT (~260 chars) pueden exceder ese límite.

Activación

Agrega el campo <SHORTURLS>True</SHORTURLS> dentro de <app:ProcesaDte> en tu request SOAP XML. Las URLs en la respuesta usarán el formato corto automáticamente.

Para la API REST (POST /{tenantSlug}/dte), usa "shortUrl": true en el body JSON.

Una vez emitido un DTE con URLs cortas, los emails posteriores (re-envíos) mantienen el formato corto automáticamente.

Formato de URLs

Modo	Formato	Longitud aprox.
STANDARD (default)	/public/documentos/{jwt_token}/{pdf|xml|pdf-sii}	~260 chars
SHORT	/public/d/{dteId}/{shortToken}/{pdf|xml|pdf-sii}	~89 chars

Ejemplo con modo SHORT

En el response SOAP XML, las URLs se ven así:

<UrlPdf>https://api.redcumbre.cl/public/d/cm1abc2def3g/A1b2C3d4E5f6/pdf</UrlPdf>
<UrlXmlSii>https://api.redcumbre.cl/public/d/cm1abc2def3g/A1b2C3d4E5f6/xml</UrlXmlSii>
<UrlXmlReceptor>https://api.redcumbre.cl/public/d/cm1abc2def3g/A1b2C3d4E5f6/xml</UrlXmlReceptor>

Notas

• El shortToken se genera automáticamente la primera vez y se reutiliza en llamadas posteriores para el mismo DTE.
• Las URLs son permanentes en ambos modos (STANDARD y SHORT) — no expiran nunca.
• La seguridad se mantiene: el acceso requiere conocer tanto el dteId como el shortToken.
• No es necesario cambiar código de integración — solo cambia el formato de las URLs recibidas.

---

Idempotencia

Si tu sistema puede reintentar requests (por timeout, error de red, o doble-click), podés usar el tag <IdempotencyKey> para proteger contra emisiones duplicadas.

Qué es

La idempotencia garantiza que un mismo request enviado múltiples veces produzca el mismo resultado: solo se emite un DTE, y los reintentos retornan el DTE original sin crear uno nuevo ni consumir folio.

Cómo usarla

Agregá el tag <IdempotencyKey> dentro de <app:ProcesaDte> con un valor único por operación:

<app:ProcesaDte>
  <STRINGXML><![CDATA[...DTE XML...]]></STRINGXML>
  <IdempotencyKey>order-12345-factura</IdempotencyKey>
</app:ProcesaDte>

Reglas:

• Máximo 128 caracteres
• El scope de unicidad es: emisor + tipo de DTE + key. Esto significa que podés usar la misma key para diferentes emisores o diferentes tipos de DTE sin colisión
• La key es permanente — no expira. Un DTE emitido con una key siempre retornará el mismo resultado ante reintentos
• Solo DTEs con estado EMITIDO se consideran para idempotencia. Si la primera emisión falló, podés reintentar con la misma key y se creará un DTE nuevo
• El campo es opcional. Si no se envía, el comportamiento no cambia

Ejemplo XML con idempotencia

<app:ProcesaDte>
  <STRINGXML><![CDATA[<DTE version="1.0">
<Documento ID="F1T33">
  <Encabezado>
    <IdDoc>
      <TipoDTE>33</TipoDTE>
      <FchEmis>2026-03-03</FchEmis>
    </IdDoc>
    <Emisor>
      <RUTEmisor>76123456-7</RUTEmisor>
    </Emisor>
    <Receptor>
      <RUTRecep>77438768-4</RUTRecep>
      <RznSocRecep>EMPRESA EJEMPLO SPA</RznSocRecep>
      <GiroRecep>VENTA AL POR MENOR</GiroRecep>
      <DirRecep>AV PROVIDENCIA 1234</DirRecep>
      <CmnaRecep>PROVIDENCIA</CmnaRecep>
    </Receptor>
  </Encabezado>
  <Detalle>
    <NmbItem>Servicio de consultoría</NmbItem>
    <QtyItem>1</QtyItem>
    <PrcItem>100000</PrcItem>
    <MontoItem>100000</MontoItem>
  </Detalle>
</Documento>
</DTE>]]></STRINGXML>
  <IdempotencyKey>order-12345-factura</IdempotencyKey>
</app:ProcesaDte>

Comportamiento en reintentos

Situación	Resultado
Primera emisión con key	DTE se emite normalmente, key se guarda
Reintento con misma key (DTE ya emitido)	Retorna el DTE original sin crear nuevo
Misma key pero diferente emisor o tipo DTE	Se emite un DTE nuevo (scope diferente)
Misma key pero DTE original en estado ERROR	Se emite un DTE nuevo (solo EMITIDO cuenta)

También disponible via REST

En la API REST (POST /{tenantSlug}/dte), usá el campo "idempotencyKey" en el body JSON para la misma funcionalidad.

---

Errores Comunes

Error	Causa	Solución
Request body vacío o no es XML	Content-Type incorrecto o body vacío	Verificar que Content-Type sea application/xml o text/xml
SOAP Envelope no encontrado	XML no tiene estructura SOAP	Verificar el namespace soapenv y la estructura del envelope
Campo STRINGXML es obligatorio	No se incluyó el campo STRINGXML	Agregar el campo con el DTE XML en CDATA
TipoDTE no es un número válido	Código de tipo no reconocido	Usar uno de los códigos soportados (33, 34, 39, 41, etc.)
No se encontró un emisor DTE activo con RUT X	El RUT no tiene emisor activo en el tenant	Verificar que el RUT del emisor esté registrado y activo