API: DTEs

El recurso /dtes cubre los documentos que viajan por el pipeline SOAP del SII: Factura Electrónica (33), Factura Exenta (34), Nota de Débito (56), Nota de Crédito (61) y la Factura de Exportación de servicios (110) con su nota de crédito (112). Las boletas (39/41) tienen pipeline REST propio, ver API: Boletas.

Base URL: https://app.notta.cl/api/v1. Autenticación: Authorization: Bearer ntt_cert_… con scope dte:read para lecturas y dte:write para mutaciones, ver Autenticación. Todo POST a este recurso exige además el header X-Cert-Id (UUID que devuelve POST /certificates) y Idempotency-Key.

La emisión es asíncrona: el POST responde 202 con sii_status: "queued" y el upload al SII corre en un workflow. Toda respuesta que trae sii_status trae también el bloque estado con ese mismo valor ya clasificado: espera hasta que estado.terminal sea true y ramifica por estado.categoria: la tabla completa de los estados, con su cadencia real, está en Estados del DTE. Cortar por sii_status === "EPR" deja el bucle girando ante un rechazo.

Endpoints

POST /dtes

Emite un DTE: valida el input, asigna folio desde tu CAF, firma con tu certificado y encola el envío al SII.

Referencias correctivas (56/61)

Para 56/61, cada elemento de references[] lleva todos estos campos:

Referencias comerciales (33/34/52)

En factura afecta (33), exenta (34) y guía de despacho (52) las referencias son opcionales y no llevan cod_ref. Documentan el papel que origina la operación (orden de compra, contrato, DUS, otra factura, etc.). Hay dos formas equivalentes:

Alias, atajo para los 3 casos más comunes:

Crudo, cualquier código del catálogo oficial del SII:

Ejemplo, una factura 33 que referencia una orden de compra (código crudo) y un contrato (alias):

"references": [
  { "tipo_doc_ref": "801", "folio_ref": "OC-4471", "fecha_ref": "2026-07-01", "razon_ref": "Orden de compra del cliente" },
  { "type": "contrato", "folio": "CTR-2026-09", "date": "2026-05-01" }
]

curl -X POST https://app.notta.cl/api/v1/dtes \
  -H "Authorization: Bearer ntt_cert_..." \
  -H "X-Cert-Id: 01977f00-0000-7000-8000-000000000abc" \
  -H "Idempotency-Key: $(uuidgen)" \
  -H "Content-Type: application/json" \
  -d '{
    "tipo_dte": 33,
    "rut_emisor": "76123456-0",
    "receptor": { "rut": "11111111-1", "razon_social": "Cliente Ejemplo SpA", "giro": "Comercio", "direccion": "Av Siempre Viva 123", "comuna": "Santiago" },
    "forma_pago": 2,
    "fecha_emision": "2026-06-09",
    "items": [
      { "nombre": "Consultoría mayo", "cantidad": 5, "precio_unitario": 50000, "exento": false, "monto_item": 250000 }
    ]
  }'

Respuesta 202 Accepted:

{
  "id": "01977f2a-1b50-7000-8000-000000000001",
  "status": "queued",
  "folio": 1234,
  "tipo_dte": 33,
  "rut_emisor": "76123456-0",
  "rut_receptor": "11111111-1",
  "monto_neto": 250000,
  "monto_exento": 0,
  "iva": 47500,
  "monto_total": 297500,
  "sii_env": "cert",
  "sii_status": "queued",
  "estado": {
    "code": "queued",
    "label": "en cola",
    "descripcion": "El documento se creó en Notta y está en cola para firmarse y subirse al SII.",
    "terminal": false,
    "poll_activo": false,
    "categoria": "en_proceso",
    "accion": "esperar"
  },
  "fecha_emision": "2026-06-09",
  "links": {
    "self": "/api/v1/dtes/01977f2a-1b50-7000-8000-000000000001",
    "pdf": "/api/v1/dtes/01977f2a-1b50-7000-8000-000000000001/pdf",
    "xml": "/api/v1/dtes/01977f2a-1b50-7000-8000-000000000001/xml",
    "events": "/api/v1/dtes/01977f2a-1b50-7000-8000-000000000001/events"
  }
}

estado es el mismo valor de sii_status ya clasificado, y viene en todas las respuestas de este recurso: terminal te dice cuándo dejar de esperar y categoria / accion son enums cerrados para ramificar sin leer la prosa. El catálogo completo está en Estados del DTE.

links.events es el feed de transiciones del documento: GET /dtes/:id/events devuelve, en orden cronológico, cada estado por el que pasó con la glosa del SII. Es el camino recomendado para seguir la emisión, ver GET /dtes/:id/events.

Errores posibles:

Exportación de servicios (110/112)

La factura de exportación (110) y su nota de crédito (112) se emiten por el mismo POST /dtes, con un cuerpo propio. Tu organización necesita el tipo autorizado por el SII; sin eso la respuesta es 403.

Tres cosas funcionan distinto y conviene tenerlas claras antes del primer intento:

1. Los montos van en la moneda del documento, con hasta 4 decimales. tpo_moneda lleva la glosa del catálogo del SII ("DOLAR USA", "EURO", "PESO CL"), nunca el código ISO: "USD" es rechazado.
2. El tipo de cambio lo resuelve el servidor el día de la emisión. Si mandas tpo_cambio se guarda como evidencia de lo que declaraste, pero no convierte. Cuando la fuente no responde, la emisión se detiene sin quemar folio en vez de asumir un valor.
3. El receptor extranjero no lleva rut. El servidor pone el comodín 55555555-5 que el SII define para eso; la identificación real del cliente va en receptor.extranjero.num_id.

{
  "tipo_dte": 110,
  "receptor": {
    "razon_social": "IMPLAN Group LLC",
    "direccion": "16905 Northcross Drive Ste 120 Huntersville, NC 28078",
    "ciudad": "Huntersville",
    "extranjero": { "num_id": "46-2728753" }
  },
  "items": [
    { "nombre": "Rediseño del sitio", "cantidad": 1, "precio_unitario": 5250, "monto_item": 5250, "exento": true }
  ],
  "tpo_moneda": "DOLAR USA",
  "monto_total": 5250,
  "ind_servicio": 3,
  "aduana": {
    "cod_pto_embarque": 9999,
    "id_adic_pto_emb": "Servicio digital",
    "cod_pto_desemb": 9999,
    "id_adic_pto_desemb": "Servicio digital",
    "cod_pais_destin": 225
  }
}

En las respuestas, monto_total sigue siendo pesos chilenos (es lo que consumen el Libro de Ventas y el F29), y lo que declara la factura viene en monto_moneda junto a moneda_documento. El detalle agrega además tipo_cambio y su fuente, para que la cifra en pesos sea auditable.

Desde el CLI: notta dte emit-exportacion --name "IMPLAN Group LLC" --item "Rediseño del sitio:1:5250" --pais-destino 225.

GET /dtes

Lista los DTEs de tu organización, los más recientes primero.

curl "https://app.notta.cl/api/v1/dtes?limit=50&sort=folio&dir=asc" \
  -H "Authorization: Bearer ntt_cert_..."

Respuesta 200 OK (envelope de paginación):

{
  "data": [
    {
      "id": "01977f2a-1b50-7000-8000-000000000001",
      "folio": 1234,
      "tipo_dte": 33,
      "rut_emisor": "76123456-0",
      "rut_receptor": "11111111-1",
      "razon_social_receptor": "Cliente SpA",
      "monto_neto": 250000,
      "monto_exento": 0,
      "iva": 47500,
      "monto_total": 297500,
      "sii_status": "EPR",
      "estado": {
        "code": "EPR",
        "label": "aceptado",
        "descripcion": "El SII procesó el envío y no reportó rechazos ni reparos sobre este documento.",
        "terminal": true,
        "poll_activo": false,
        "categoria": "aceptado",
        "accion": "ninguna"
      },
      "sii_glosa": "Envio aceptado",
      "track_id": 998877665544,
      "sii_env": "prod",
      "sii_last_polled": "2026-06-09T15:02:11.000Z",
      "fecha_emision": "2026-06-09",
      "documento_disponible": true,
      "created_at": "2026-06-09T14:32:48.000Z",
      "receptor_estado": "reclamado",
      "receptor_reclamado_at": "2026-06-12",
      "receptor_acuse_at": null,
      "fecha_recepcion_sii": "2026-06-09T18:04:22.000Z",
      "plazo_reclamo_cierra": "2026-06-17T18:04:22.000Z",
      "references": [
        {
          "line_num": 1,
          "tipo_doc_ref": "801",
          "folio_ref": "OC-4471",
          "fecha_ref": "2026-07-01",
          "cod_ref": null,
          "razon_ref": "Orden de compra del cliente"
        }
      ],
      "links": { "self": "/api/v1/dtes/01977f2a-1b50-7000-8000-000000000001" }
    }
  ],
  "next_cursor": "eyJ2IjoxLCJzIjoiY3JlYXRlZF9hdCIsLi4ufQ"
}

sii_glosa, track_id, sii_env y sii_last_polled vienen en el listado, no solo en el detalle: para reconciliar estados no necesitas un GET /dtes/:id por documento. Lo mismo con razon_social_receptor, monto_neto e iva: alcanzan para armar una tabla o cuadrar el IVA del período sin bajar cada documento. documento_disponible te dice si ya hay XML firmado (o sea, si /dtes/{id}/pdf, /xml y /pdf-url responden) sin que gastes un request en descubrir un 409.

monto_exento y references completan el par: el primero cuadra una exenta (34) —o el exento de una 33 mixta— sin bajar el documento; el segundo dice a qué apunta cada referencia, con el mismo shape que el detalle. En una NC/ND es el dato que decide si una factura sigue viva: cod_ref distingue anula (1) de corrige texto (2) y corrige montos (3), una distinción que el Registro de Compras y Ventas del SII no publica. Un documento sin referencias trae [], nunca null, y las comerciales (una orden de compra) viajan con cod_ref: null — el código sólo existe en las correctivas, así que null ahí es un valor, no un dato faltante. fecha_ref es la fecha del documento referenciado: sin ella, dos facturas con el mismo (tipo, folio) en períodos distintos son indistinguibles, porque el folio se reinicia por emisor y por ambiente.

Qué hizo tu cliente con el documento

sii_status es el veredicto del SII. receptor_estado es lo que hizo tu cliente, y son dos cosas distintas: el SII puede haber aceptado la factura (EPR) y el receptor reclamarla igual. Los cinco campos vienen tanto en el listado como en GET /dtes/{id}.

fecha_recepcion_sii es el ancla del plazo (no fecha_emision), y plazo_reclamo_cierra es esa fecha-hora más 192 horas. Es un instante, no un día: el SII cuenta fecha-hora a fecha-hora y a partir de ese momento rechaza el reclamo, así que tomar el día entero como disponible le regala al receptor horas que ya no tiene. Cuando no hay ancla, plazo_reclamo_cierra viene en null: no hay plazo que calcular. Los tres últimos estados se derivan contra el instante del request y cambian solos con el reloj: no los guardes como si fueran definitivos.

Este plazo corre contra el receptor. Al emisor no le abre ninguna ventana ni le exige ninguna acción.

curl "https://app.notta.cl/api/v1/dtes?receptor_estado=reclamado&limit=100" \
  -H "Authorization: Bearer ntt_prod_..."

El filtro acepta los mismos cinco valores que publica cada fila. Los tres derivados sirven para una foto del momento, no para paginar: como se calculan contra el instante de cada request, un documento puede cruzar de en_plazo a aceptado_tacito entre la página 1 y la página 2 de la misma consulta. Si necesitas un recorrido estable, filtra por reclamado o aceptado (que son hechos y no se mueven) o baja las filas y decide en tu lado con fecha_recepcion_sii y plazo_reclamo_cierra. Un valor fuera de esos cinco devuelve 422 dte.list.receptor_estado_invalido.

El detalle de qué es un reclamo, de dónde arrancan las 192 horas y por qué no se puede revertir está en Reclamo del receptor.

Encontrar un documento que ya conoces

GET /dtes/{id}, /dtes/{id}/pdf-url y /dtes/{id}/xml piden el id interno de Notta (un UUID), no el folio. Para llegar a él sin recorrer el histórico, filtra por folio:

curl "https://app.notta.cl/api/v1/dtes?folio=1042&tipo_dte=33" \
  -H "Authorization: Bearer ntt_prod_..."

El folio no es una clave por sí solo. El SII lo asigna por serie: la unicidad es (rut_emisor, tipo_dte, folio, ambiente), así que el folio 1042 puede existir como factura y como guía de despacho. Por eso ?folio= devuelve una lista y no un documento: súmale tipo_dte para la coordenada exacta.

Para todo lo que le emitiste a un cliente, filtra por su RUT:

curl "https://app.notta.cl/api/v1/dtes?rut_receptor=76.123.456-0&fecha_emision_desde=2026-01-01" \
  -H "Authorization: Bearer ntt_prod_..."

El RUT se normaliza en el servidor: puntos, espacios y la k en minúscula dan lo mismo. El dígito verificador no se valida, a propósito: rut_receptor es lo que declaró el emisor (o lo que trajo el Respaldo del SII), y un DV que no cierra corresponde igual a documentos reales que tienes que poder encontrar.

Seguir los cambios de estado sin forzar un refresco

El poll durable ya lleva cada DTE a estado terminal por su cuenta. Para enterarte no hace falta POST /dtes/:id/refresh-status: filtra por los estados que aún no son terminales y lee.

curl "https://app.notta.cl/api/v1/dtes?sii_status=queued,sending,signed,SOK,CRT,FOK,PDR,PRD,-11&limit=100" \
  -H "Authorization: Bearer ntt_prod_..."

polled_since es «tocado desde», no «cambiado desde». sii_last_polled se estampa en cada escritura de estado, no solo en las consultas al SII: también en las transiciones de la emisión (queued, sending, signed), así que un DTE recién emitido ya la trae poblada. El filtro nunca pierde un cambio, pero sí devuelve documentos cuyo estado no cambió: trátalo como un límite inferior barato, no como un log de cambios. Para las transiciones exactas de un documento, usa GET /dtes/{id}/events.

Errores posibles: 401 (auth), 403 forbidden si el key no tiene dte:read, y 422 con dte.list.cursor_invalido, dte.list.status_desconocido, dte.list.tipo_invalido, dte.list.folio_invalido, dte.list.rut_receptor_invalido, dte.list.fecha_invalida, dte.list.polled_since_invalido o dte.list.receptor_estado_invalido.

GET /dtes/:id

Devuelve el detalle de un DTE, incluyendo sus ítems por línea y el estado SII.

curl https://app.notta.cl/api/v1/dtes/01977f2a-1b50-7000-8000-000000000001 \
  -H "Authorization: Bearer ntt_cert_..."

Respuesta 200 OK:

{
  "id": "01977f2a-1b50-7000-8000-000000000001",
  "folio": 1234,
  "tipo_dte": 33,
  "rut_emisor": "76123456-0",
  "rut_receptor": "11111111-1",
  "razon_social_receptor": "Cliente Ejemplo SpA",
  "giro_receptor": "Comercio",
  "direccion_receptor": "Av Siempre Viva 123",
  "comuna_receptor": "Santiago",
  "monto_neto": 250000,
  "monto_exento": 0,
  "iva": 47500,
  "monto_total": 297500,
  "sii_env": "cert",
  "sii_status": "EPR",
  "estado": {
    "code": "EPR",
    "label": "aceptado",
    "descripcion": "El SII procesó el envío y no reportó rechazos ni reparos sobre este documento.",
    "terminal": true,
    "poll_activo": false,
    "categoria": "aceptado",
    "accion": "ninguna"
  },
  "sii_glosa": null,
  "track_id": 998877665544,
  "fecha_emision": "2026-06-09",
  "created_at": "2026-06-09T14:32:48.000Z",
  "receptor_estado": "reclamado",
  "receptor_reclamado_at": "2026-06-12",
  "receptor_acuse_at": null,
  "fecha_recepcion_sii": "2026-06-09T18:04:22.000Z",
  "plazo_reclamo_cierra": "2026-06-17T18:04:22.000Z",
  "items": [
    {
      "position": 1,
      "nombre": "Consultoría mayo",
      "descripcion": null,
      "cantidad": 5,
      "precio_unitario": 50000,
      "monto_item": 250000,
      "exento": false
    }
  ],
  "links": {
    "self": "/api/v1/dtes/01977f2a-1b50-7000-8000-000000000001",
    "pdf": "/api/v1/dtes/01977f2a-1b50-7000-8000-000000000001/pdf",
    "xml": "/api/v1/dtes/01977f2a-1b50-7000-8000-000000000001/xml",
    "events": "/api/v1/dtes/01977f2a-1b50-7000-8000-000000000001/events"
  }
}

giro_receptor, direccion_receptor y comuna_receptor vienen null cuando el documento no los trajo: son obligatorios en 33 y 34, opcionales en 52/56/61. No hace falta bajar el XML para leerlos.

Errores posibles:

GET /dtes/:id/pdf

Descarga la representación impresa del DTE (formato SII con timbre PDF417), como application/pdf.

curl -o DTE-33-1234.pdf \
  https://app.notta.cl/api/v1/dtes/01977f2a-1b50-7000-8000-000000000001/pdf \
  -H "Authorization: Bearer ntt_cert_..."

Errores posibles:

GET /dtes/:id/xml

Devuelve el XML firmado del DTE (application/xml), apto para verificación de firma y cesión.

curl https://app.notta.cl/api/v1/dtes/01977f2a-1b50-7000-8000-000000000001/xml \
  -H "Authorization: Bearer ntt_cert_..."

Decodifica según el charset del Content-Type, no asumas UTF-8. Los bytes siempre coinciden con la declaración del prólogo del documento:

Un DTE emitido baja en bytes ISO-8859-1 a propósito: así queda byte-idéntico al que recibió el SII, que es lo que necesitas si lo vuelves a subir al portal o lo cedes. Leerlo como UTF-8 te va a dar basura en cualquier campo con tildes (Construcción, N° 2800).

Errores posibles:

GET /dtes/:id/events

El feed de transiciones de estado del documento: el mismo que anuncia links.events en el 202 de la emisión y en el detalle. Es el endpoint canónico para seguir un DTE: devuelve toda su historia de estados en orden cronológico ascendente (del más antiguo al más reciente), cada uno con la glosa que reportó el SII. Es de solo lectura, pide scope dte:read y está acotado a tu organización: un id de otra org responde 404.

curl https://app.notta.cl/api/v1/dtes/01977f2a-1b50-7000-8000-000000000001/events \
  -H "Authorization: Bearer ntt_cert_..."

Respuesta 200 OK:

{
  "data": [
    { "status": "queued", "at": "2026-06-09T14:32:48.000Z", "source": "local", "glosa": null },
    { "status": "sending", "at": "2026-06-09T14:32:52.000Z", "source": "local", "glosa": null },
    { "status": "-11", "at": "2026-06-09T14:33:19.000Z", "source": "sii", "glosa": null },
    { "status": "EPR", "at": "2026-06-09T14:35:02.000Z", "source": "sii", "glosa": "Envio aceptado" }
  ],
  "links": {
    "self": "/api/v1/dtes/01977f2a-1b50-7000-8000-000000000001/events",
    "dte": "/api/v1/dtes/01977f2a-1b50-7000-8000-000000000001"
  }
}

Este es el endpoint de seguimiento; refresh-status no lo es. El feed te dice por dónde pasó el documento (incluidos los estados transitorios que un GET /dtes/:id ya no muestra, porque ese devuelve solo el último) y trae la glosa del rechazo en el mismo request, sin volver a pedir el detalle. POST /dtes/:id/refresh-status es la escotilla para un poll que se murió: llamarlo en bucle no acelera nada y abre sesiones contra el SII con tu certificado.

Este feed lo lees tú: es el carril de pull. Si prefieres que Notta te avise, registra un webhook y recibe cada transición por push, firmada. Los dos conviven: el feed es además el camino de recuperación cuando una entrega no llega.

Errores posibles:

POST /dtes/:id/refresh-status

Escotilla para revivir el seguimiento de un DTE cuyo poll murió, típicamente tras una caída del SII.

curl -X POST https://app.notta.cl/api/v1/dtes/01977f2a-1b50-7000-8000-000000000001/refresh-status \
  -H "Authorization: Bearer ntt_cert_..." \
  -H "X-Cert-Id: 01977f00-0000-7000-8000-000000000abc" \
  -H "Idempotency-Key: $(uuidgen)"

Respuesta 202 Accepted (encolado):

{
  "id": "01977f2a-1b50-7000-8000-000000000001",
  "status": "refresh_enqueued",
  "estado": {
    "code": "stuck",
    "label": "atascado en SII",
    "descripcion": "El SII no entregó un veredicto dentro de la ventana del poll y el workflow se agotó.",
    "terminal": false,
    "poll_activo": false,
    "categoria": "requiere_accion",
    "accion": "reintentar_consulta"
  }
}

Respuesta 200 OK (no se encoló, con el motivo). retry_after viene en segundos y dice cuánto falta para que esta llamada deje de ser un no-op, no es una promesa sobre cuándo responde el SII:

{
  "id": "01977f2a-1b50-7000-8000-000000000001",
  "status": "poll_in_progress",
  "sii_status": "SOK",
  "sii_last_polled": "2026-06-09T15:02:11.000Z",
  "retry_after": 86400,
  "estado": {
    "code": "SOK",
    "label": "schema del envío validado",
    "descripcion": "El SII validó el esquema del sobre. Es una etapa del procesamiento del envío, no un veredicto.",
    "terminal": false,
    "poll_activo": true,
    "categoria": "en_proceso",
    "accion": "esperar"
  }
}

La otra rama 200 es la que más importa leer: already_terminal sobre un documento rechazado también responde 2xx.

{
  "id": "01977f2a-1b50-7000-8000-000000000001",
  "status": "already_terminal",
  "sii_status": "RCH",
  "sii_glosa": "Documento rechazado por el SII",
  "estado": {
    "code": "RCH",
    "label": "documento rechazado",
    "descripcion": "El SII aceptó el envío pero rechazó ESTE documento por su contenido.",
    "terminal": true,
    "poll_activo": false,
    "categoria": "rechazado",
    "accion": "reemitir"
  }
}

Errores posibles:

GET /dtes/muestras

Flujo de certificación SII: arma un ZIP con un PDF por cada DTE firmado (33/34/56/61) de tu org para el lote de Muestras Impresas; ?source=set_pruebas lo acota al set de pruebas.

curl -o muestras.zip "https://app.notta.cl/api/v1/dtes/muestras?source=set_pruebas" \
  -H "Authorization: Bearer ntt_cert_..."

Errores posibles:

POST /dtes/muestras/send

Flujo de certificación SII: Notta arma y envía el correo de Muestras Impresas a sii_dte_impresos@sii.cl con los PDFs adjuntos.

curl -X POST https://app.notta.cl/api/v1/dtes/muestras/send \
  -H "Authorization: Bearer ntt_cert_..." \
  -H "X-Cert-Id: 01977f00-0000-7000-8000-000000000abc" \
  -H "Idempotency-Key: $(uuidgen)"

Respuesta 200 OK:

{ "data": { "sent": 8, "sentAt": "2026-06-09T15:02:11.000Z" } }

Errores posibles:

Próximos pasos

• Emitir Factura 33: la guía paso a paso del caso más común, con el mismo payload de esta referencia.
• API: Boletas, el pipeline REST para boletas 39/41, individual y en batch.
• Catálogo de errores: todos los códigos con su next_action para manejo programático.
• Paginación: el envelope { data, next_cursor } y los parámetros de orden.