API REST | DUODTE - Documentación para Desarrolladores

Visión general

La API de DUODTE permite a desarrolladores y equipos de tecnología integrar todas las capacidades de facturación electrónica disponibles en la plataforma directamente en su propio sistema o aplicación.

Base URL https://api.duodte.cl/v1

Todas las peticiones deben realizarse sobre HTTPS. El protocolo HTTP no está soportado y las solicitudes serán rechazadas automáticamente.

JSON

Formato de request y response

HTTPS

Protocolo requerido

ApiKey

Header principal de integración

v1

Versión actual

Autenticación

Para integraciones externas con DteController utiliza el header ApiKey. El esquema JWT sigue disponible para flujos internos, pero la documentación oficial de esta API se basa en API Keys.

Header requerido

ApiKey: tu_api_key_de_integracion Content-Type: application/json Accept: application/json

Nunca compartas tu API Key en código público, repositorios o logs. Si crees que tu clave fue comprometida, revócala inmediatamente desde el panel de tu cuenta.

Headers soportados

Header	Uso	Descripción
`ApiKey`	Integración externa	Obligatorio para consumir `/dte`, `/dte/{id}` y `/dte/{id}/status`.
`Authorization: Bearer ...`	Interno	Disponible para paneles o flujos administrativos, no es el mecanismo principal documentado para esta integración.

Rate limits

Para garantizar la estabilidad del servicio, aplicamos límites de tasa por API Key.

Plan	Solicitudes / minuto	DTEs / mes
Starter	30	100
Profesional	120	2.000
Empresa	500	Ilimitados
Enterprise	Personalizado	Personalizado

Cuando superes el límite, la API responderá con 429 Too Many Requests. El header Retry-After indica cuántos segundos esperar antes de reintentar.

Manejo de errores

La API utiliza códigos HTTP estándar. En los endpoints documentados de DteController, los errores se retornan en JSON con el formato real del middleware del servicio.

Código	Significado
`200`	Operación exitosa.
`400`	Solicitud inválida o error de validación de campos/reglas de negocio.
`401`	No autenticado. API Key inválida o ausente.
`404`	Recurso no encontrado.
`409`	Conflicto de negocio cuando aplica en operaciones del servicio.
`500`	Error interno del servicio.

400 Ejemplo de respuesta de error

{
  "error": {
    "message": "`Documento.Encabezado.Receptor.RUTRecep` es obligatorio. | Para DTE tipo 61, debe informar al menos una `Referencia`."
  }
}

Emitir DTE

Crea o actualiza un DTE usando un payload JSON compatible con la estructura del SII. Si envías un folio existente activo, el documento se actualiza; si no informas folio, el servicio obtiene el siguiente disponible, genera el XML, lo firma y guarda la transacción.

Tipos de documento soportados

33 Factura electrónica

34 Factura no afecta o exenta

39 Boleta electrónica

41 Boleta no afecta o exenta

61 Nota de crédito

52 Guía de despacho

POST /dte Crea o actualiza un DTE

Endpoint oficial para integraciones ERP, SAP y plataformas externas. Soporta estructura SII, asignación automática de folio, actualización por folio informado, validaciones por tipo de documento y reglas de negocio antes de firmar el XML.

Comportamiento de folio: si documento.encabezado.idDoc.folio viene en 0 o no se informa, el servicio asigna el siguiente folio disponible. Si viene informado y existe una transacción activa con ese folio y tipo de documento, la emisión se actualiza reutilizando el mismo registro.

Body parameters

Campo	Tipo	Requerido	Descripción
`storeCode`	string	requerido	Código del local o sucursal usado para obtener folios y registrar la transacción.
`posCode`	string	requerido	Código del POS, canal o integrador que emite el DTE.
`documentType`	integer	opcional	Tipo de DTE. Si no se informa, se usa `documento.encabezado.idDoc.tipoDTE`.
`date`	datetime	opcional	Fecha operativa para el registro interno. Si no se informa, se usa la fecha del documento o UTC actual.
`documento`	object	requerido	Estructura principal del DTE, compatible con el formato SII.
`documento.encabezado.idDoc.tipoDTE`	integer	requerido	Tipos soportados: `33`, `34`, `39`, `41`, `52`, `56`, `61`.
`documento.encabezado.idDoc.folio`	integer	opcional	Folio del documento. Si es `0` o se omite, se asigna automáticamente.
`documento.encabezado.emisor`	object	requerido	Datos del emisor según SII. Incluye soporte para `rutEnvia`, `correoEmisor`, `sucursal`, `cdgVendedor`, `cdgCaja` y más.
`documento.encabezado.receptor`	object	requerido	Datos del receptor. Incluye soporte para `correoRecep`, `cdgIntRecep`, `dirPostal`, `cmnaPostal` y `ciudadPostal`.
`documento.encabezado.totales`	object	requerido	Totales tributarios. Incluye soporte para `mntNeto`, `mntExe`, `mntBase`, `IVA`, `ivaNoRet`, `credEC`, `otraMoneda` y más.
`documento.detalle`	array	requerido	Debe incluir al menos una línea válida con `nroLinDet`, `nmbItem`, `qtyItem` y `montoItem`.
`documento.referencia`, `documento.dscRcgGlobal`, `documento.subTotInfo`, `documento.otraMoneda`, `documento.comisiones`, `documento.encabezado.transporte`	object / array	opcional	Secciones avanzadas soportadas por la nueva integración oficial de DTE.

Ejemplo de request

curl -X POST https://api.duodte.cl/v1/dte \
  -H "ApiKey: tu_api_key_de_integracion" \
  -H "Content-Type: application/json" \
  -d '{
    "storeCode": "CASA_MATRIZ",
    "posCode": "SAP",
    "documento": {
      "encabezado": {
        "idDoc": {
          "tipoDTE": 33,
          "folio": 0,
          "fchEmis": "2026-03-05T00:00:00",
          "fmaPago": 1
        },
        "emisor": {
          "rutEmisor": "6193567-3",
          "rznSoc": "DUODTE SPA",
          "giroEmis": "DESARROLLO DE SOFTWARE",
          "dirOrigen": "Av. Providencia 1234",
          "cmnaOrigen": "Providencia",
          "ciudadOrigen": "Santiago"
        },
        "receptor": {
          "rutRecep": "76543210-K",
          "rznSocRecep": "Empresa ABC Ltda.",
          "giroRecep": "Servicios de consultoría",
          "dirRecep": "Av. Apoquindo 1000",
          "cmnaRecep": "Las Condes",
          "ciudadRecep": "Santiago"
        },
        "totales": {
          "mntNeto": 1100000,
          "tasaIVA": 19,
          "iva": 209000,
          "mntTotal": 1309000
        }
      },
      "detalle": [
      {
        "nroLinDet": 1,
        "nmbItem": "Servicio de consultoría técnica",
        "qtyItem": 1,
        "prcItem": 850000,
        "montoItem": 850000
      },
      {
        "nroLinDet": 2,
        "nmbItem": "Asesoría en transformación digital",
        "qtyItem": 5,
        "prcItem": 50000,
        "montoItem": 250000
      }
      ]
    }
  }'

const response = await fetch('https://api.duodte.cl/v1/dte', {
  method: 'POST',
  headers: {
    'ApiKey': 'tu_api_key_de_integracion',
    'Content-Type': 'application/json',
  },
  body: JSON.stringify({
    storeCode: 'CASA_MATRIZ',
    posCode: 'SAP',
    documento: {
      encabezado: {
        idDoc: { tipoDTE: 33, folio: 0, fchEmis: '2026-03-05T00:00:00', fmaPago: 1 },
        emisor: {
          rutEmisor: '6193567-3',
          rznSoc: 'DUODTE SPA',
          giroEmis: 'DESARROLLO DE SOFTWARE',
          dirOrigen: 'Av. Providencia 1234',
          cmnaOrigen: 'Providencia',
          ciudadOrigen: 'Santiago',
        },
        receptor: {
          rutRecep: '76543210-K',
          rznSocRecep: 'Empresa ABC Ltda.',
          giroRecep: 'Servicios de consultoría',
          dirRecep: 'Av. Apoquindo 1000',
          cmnaRecep: 'Las Condes',
          ciudadRecep: 'Santiago',
        },
        totales: { mntNeto: 1100000, tasaIVA: 19, iva: 209000, mntTotal: 1309000 },
      },
      detalle: [
        { nroLinDet: 1, nmbItem: 'Servicio de consultoría técnica', qtyItem: 1, prcItem: 850000, montoItem: 850000 },
        { nroLinDet: 2, nmbItem: 'Asesoría en transformación digital', qtyItem: 5, prcItem: 50000, montoItem: 250000 },
      ],
    },
  }),
});

const dte = await response.json();
console.log(dte.folioNumber);

import requests

response = requests.post(
    'https://api.duodte.cl/v1/dte',
    headers={
        'ApiKey': 'tu_api_key_de_integracion',
        'Content-Type': 'application/json',
    },
    json={
        'storeCode': 'CASA_MATRIZ',
        'posCode': 'SAP',
        'documento': {
            'encabezado': {
                'idDoc': {'tipoDTE': 33, 'folio': 0, 'fchEmis': '2026-03-05T00:00:00', 'fmaPago': 1},
                'emisor': {
                    'rutEmisor': '6193567-3',
                    'rznSoc': 'DUODTE SPA',
                    'giroEmis': 'DESARROLLO DE SOFTWARE',
                    'dirOrigen': 'Av. Providencia 1234',
                    'cmnaOrigen': 'Providencia',
                    'ciudadOrigen': 'Santiago',
                },
                'receptor': {
                    'rutRecep': '76543210-K',
                    'rznSocRecep': 'Empresa ABC Ltda.',
                    'giroRecep': 'Servicios de consultoría',
                    'dirRecep': 'Av. Apoquindo 1000',
                    'cmnaRecep': 'Las Condes',
                    'ciudadRecep': 'Santiago',
                },
                'totales': {'mntNeto': 1100000, 'tasaIVA': 19, 'iva': 209000, 'mntTotal': 1309000},
            },
            'detalle': [
                {'nroLinDet': 1, 'nmbItem': 'Servicio de consultoría técnica', 'qtyItem': 1, 'prcItem': 850000, 'montoItem': 850000},
                {'nroLinDet': 2, 'nmbItem': 'Asesoría en transformación digital', 'qtyItem': 5, 'prcItem': 50000, 'montoItem': 250000},
            ],
        },
    }
)

dte = response.json()
print(dte['folioNumber'])

Respuesta exitosa

200 application/json

{
  "id": "6e8ff1df-d8d4-4d0b-91d2-d67b31f2e1d9",
  "folioNumber": 1234,
  "electronicStamp": "<TED version=\"1.0\">...</TED>"
}

Payload SII y validaciones

El endpoint POST /dte recibe un contrato basado en la estructura del SII. Además de los campos clásicos del documento, la integración soporta secciones avanzadas como referencia, dscRcgGlobal, subTotInfo, otraMoneda, comisiones y transporte.

Bloque	Descripción	Observaciones
`documento.encabezado.idDoc`	Identificación tributaria del documento.	Incluye `tipoDTE`, `folio`, `fchEmis`, `fmaPago`, `fchVenc`, `tipoDespacho`, `indTraslado`, entre otros.
`documento.encabezado.emisor`	Datos del emisor.	Soporta campos adicionales como `rutEnvia`, `correoEmisor`, `sucursal`, `cdgVendedor` y `cdgCaja`.
`documento.encabezado.receptor`	Datos del receptor.	Soporta `correoRecep`, `cdgIntRecep`, `dirPostal`, `cmnaPostal` y `ciudadPostal`.
`documento.encabezado.totales`	Totales del documento.	Incluye campos para IVA, montos exentos, impuestos retenidos, `credEC` y moneda alternativa.
`documento.detalle`	Líneas del documento.	Debe existir al menos una línea con numeración única.

Validaciones incluidas: campos obligatorios comunes, reglas por tipo de DTE, referencias obligatorias para notas, validación de transporte para guías, numeración única de líneas, coherencia básica de IVA y validaciones de negocio para folios y totales.

Consultar DTE

GET /dte/{id} Obtiene los datos persistidos de un DTE por su ID

Path parameters

Parámetro	Tipo	Descripción
`id`	string	Identificador GUID del DTE retornado por la emisión. Ej: `6e8ff1df-d8d4-4d0b-91d2-d67b31f2e1d9`

Ejemplo de request

curl -X GET https://api.duodte.cl/v1/dte/6e8ff1df-d8d4-4d0b-91d2-d67b31f2e1d9 \
  -H "ApiKey: tu_api_key_de_integracion"

const res = await fetch('https://api.duodte.cl/v1/dte/6e8ff1df-d8d4-4d0b-91d2-d67b31f2e1d9', {
  headers: { 'ApiKey': 'tu_api_key_de_integracion' },
});
const dte = await res.json();

Respuesta exitosa

200 application/json

{
  "id": "6e8ff1df-d8d4-4d0b-91d2-d67b31f2e1d9",
  "companyCode": "6193567-3",
  "storeCode": "CASA_MATRIZ",
  "posCode": "SAP",
  "date": "2026-03-05T00:00:00",
  "documentId": "f7d8b4bb-01e7-4f34-bf51-6f2c98d6f8a1",
  "documentType": 33,
  "folioNumber": 1234,
  "customerCode": "76543210-K",
  "customerName": "Empresa ABC Ltda.",
  "netTotal": 1100000,
  "exemptTotal": 0,
  "grossTotal": 1309000,
  "ceded": false,
  "siiTrackId": "123456789",
  "siiStatus": 1,
  "siiSentAt": "2026-03-05T14:35:10",
  "siiStatusAt": null,
  "siiMessage": "",
  "state": 0,
  "jobId": null,
  "pdfPath": null,
  "logs": [],
  "exchangeSent": false,
  "exchangeSentAt": null,
  "createdAt": "2026-03-05T14:32:00",
  "updatedAt": null
}

Listar DTEs

GET /dte Lista documentos DTE usando los parámetros estándar de consulta

Query parameters

Parámetro	Tipo	Descripción
`page`, `pageSize`	integer	Paginación estándar del servicio.
`sort`, `order`	string	Ordenamiento según el motor de consultas estándar.
`filters`	string / array	Permite filtrar por campos como `documentType`, `folioNumber`, `customerCode`, fechas y estados según soporte del listado estándar.

Ejemplo de request

curl -X GET "https://api.duodte.cl/v1/dte?page=1&pageSize=20&sort=createdAt&order=desc" \
  -H "ApiKey: tu_api_key_de_integracion"

Respuesta exitosa

200 application/json

{
  "data": [
    {
      "id": "6e8ff1df-d8d4-4d0b-91d2-d67b31f2e1d9",
      "documentType": 33,
      "folioNumber": 1234,
      "customerCode": "76543210-K",
      "customerName": "Empresa ABC Ltda.",
      "grossTotal": 1309000,
      "siiStatus": 1,
      "date": "2026-03-05T00:00:00",
      "createdAt": "2026-03-05T14:32:00"
    }
  ],
  "meta": {
    "page": 1,
    "pageSize": 20,
    "total": 245,
    "total_pages": 13
  }
}

Consultar estado en el SII

GET /dte/{id}/status Consulta la respuesta vigente del SII para un DTE

Retorna la respuesta cruda del SII para la transacción indicada. Dependiendo del tipo de DTE, el cuerpo puede ser XML o texto plano con el resultado del servicio tributario.

Path parameters

Parámetro	Tipo	Descripción
`id`	string	ID GUID del DTE a consultar en el SII.

Ejemplo de request

curl -X GET https://api.duodte.cl/v1/dte/6e8ff1df-d8d4-4d0b-91d2-d67b31f2e1d9/status \
  -H "ApiKey: tu_api_key_de_integracion"

Respuesta exitosa

200 text/plain / application/xml

<SII:RESPUESTA xmlns:SII="http://www.sii.cl/XMLSchema">
  <SII:RESP_HDR>
    <ESTADO>EPR</ESTADO>
    <GLOSA>DTE aceptado por el SII</GLOSA>
  </SII:RESP_HDR>
</SII:RESPUESTA>

Ceder documento

La cesión de facturas permite transferir los derechos de cobro de un documento a un cesionario (banco, factor o empresa). DUODTE realiza el proceso completo ante el SII y el RCOF (Registro de Compra y Venta).

POST /cesion Inicia la cesión de un DTE a un cesionario

Body parameters

Campo	Tipo	Requerido	Descripción
`dte_id`	string	requerido	ID del DTE a ceder.
`cesionario.rut`	string	requerido	RUT del cesionario (banco o factor).
`cesionario.razon_social`	string	requerido	Razón social del cesionario.
`monto_cesion`	number	requerido	Monto cedido en pesos. No puede superar el total del DTE.
`contacto_cesionario`	string	opcional	Email de contacto del cesionario para notificación.

Respuesta exitosa

201 application/json

{
  "cesion_id": "ces_9XoJ2kMnRvPq",
  "dte_id": "dte_MxKv9s3LpQrT",
  "estado": "enviada",
  "cesionario": {
    "rut": "97006000-6",
    "razon_social": "Banco Estado"
  },
  "monto_cesion": 1309000,
  "fecha_cesion": "2026-03-05T17:00:00-03:00"
}

Estado de cesión

GET /cesion/{cesion_id} Consulta el estado de una cesión

Respuesta exitosa

200 application/json

{
  "cesion_id": "ces_9XoJ2kMnRvPq",
  "dte_id": "dte_MxKv9s3LpQrT",
  "estado": "aceptada",
  "cesionario": {
    "rut": "97006000-6",
    "razon_social": "Banco Estado"
  },
  "monto_cesion": 1309000,
  "fecha_cesion": "2026-03-05T17:00:00-03:00",
  "fecha_aceptacion": "2026-03-05T17:05:42-03:00"
}

Webhooks

Los webhooks permiten que DUODTE notifique a tu sistema en tiempo real cuando ocurren eventos relevantes. Configura una URL pública HTTPS que recibirá peticiones POST con el payload del evento en formato JSON.

POST /webhooks Registra un nuevo endpoint de webhook

Body parameters

Campo	Tipo	Requerido	Descripción
`url`	string	requerido	URL HTTPS donde se enviarán los eventos.
`eventos`	array	requerido	Lista de eventos a suscribir. Usa `["*"]` para todos.
`secret`	string	opcional	Clave para validar la firma HMAC-SHA256 del header `X-Duodte-Signature`.

Eventos de webhooks

dte.emitido

DTE emitido

Se activa cuando un documento es generado y enviado al SII correctamente.
dte.aceptado

DTE aceptado por el SII

El SII confirmó la recepción y validez del documento.
dte.rechazado

DTE rechazado por el SII

El documento fue rechazado. El payload incluye el código de error del SII.
dte.anulado

DTE anulado

Un documento fue marcado como anulado en el sistema.
cesion.enviada

Cesión enviada

Una cesión fue enviada al RCOF pendiente de aceptación.
cesion.aceptada

Cesión aceptada

El cesionario aceptó la cesión del documento.

Ejemplo de payload de evento

POST Tu endpoint recibe este payload

{
  "event": "dte.aceptado",
  "created_at": "2026-03-05T14:35:10-03:00",
  "data": {
    "id": "dte_MxKv9s3LpQrT",
    "tipo_dte": 33,
    "folio": 1234,
    "estado": "aceptado",
    "estado_sii": "DOK",
    "totales": { "total": 1309000 }
  }
}

Para verificar que el webhook proviene de DUODTE, valida el header X-Duodte-Signature usando HMAC-SHA256 con el secret que configuraste al registrar el endpoint.

API REST DUODTE

Visión general

Autenticación

Header requerido

Headers soportados

Rate limits

Manejo de errores

Emitir DTE

Payload SII y validaciones

Consultar DTE

Listar DTEs

Consultar estado en el SII

Ceder documento

Estado de cesión

Webhooks

Eventos de webhooks

Ejemplo de payload de evento