API: DTEs

Emisión asíncrona de facturas (33/34) y notas (56/61), lectura de detalle, PDF, XML firmado y re-consulta de estado al SII

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) y Nota de Crédito (61). 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. Consulta GET /dtes/:id hasta ver un estado terminal (EPR, RPR, RFR, RCT).

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.

Campo	Tipo	Requerido	Descripción
`tipo_dte`	int	sí	`33`, `34`, `56` o `61`. Las boletas 39/41 van por `POST /boletas` (aquí responden `dte.tipo_not_supported`).
`rut_emisor`	string	sí	RUT canónico `BODY-DV` sin puntos, p. ej. `76123456-0`. DV validado módulo 11.
`receptor.rut`	string	sí	RUT del receptor, p. ej. `11111111-1`.
`receptor.razon_social`	string	sí	Razón social (se recorta el whitespace; no puede quedar vacía).
`receptor.giro` · `direccion` · `comuna`	string	condicional	Obligatorios para 33 y 34 (no vacíos): giro, dirección y comuna del receptor. En 56/61/39/41/52 son opcionales.
`forma_pago`	int	condicional	Obligatorio para 33 y 34: `1`=Contado, `2`=Crédito, `3`=Sin costo. No se exige en NC (61), ND (56), boletas (39/41) ni guías (52).
`fecha_emision`	string	sí	`YYYY-MM-DD`.
`items[]`	array	sí	1 a 60 ítems. Cada uno: `nombre` (string), `cantidad` (int), `precio_unitario` (int CLP), `exento` (boolean), `monto_item` (int CLP — puede ser negativo en NC).
`references[]`	array	condicional	Obligatorias para 56 y 61; en 33/34 son opcionales y comerciales (orden de compra, contrato, HES). Ver tabla siguiente.
`nd_reason`	enum	56: sí	`correccion_monto` · `reposicion_nc_anulada` · `interese_moratorio_contractual`.
`override_cedida`	boolean	no	Solo 61: confirma una NC sobre factura cedida (Corte Suprema 2025).
`monto_neto` · `monto_exento` · `iva` · `monto_total`	int	no	Si los mandas se valida coherencia aritmética contra los ítems; si no, Notta los calcula.
`certificate_id`	uuid	no	Certificado de firma; normalmente el mismo UUID que va en `X-Cert-Id`.
`sii_env`	enum	no	`cert` (default) o `prod`.

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

Campo	Tipo	Descripción
`line_num`	int 1–40	Número de línea de la referencia.
`tipo_doc_ref`	int	Tipo del documento referenciado (NC: solo 33 o 34; ND con `reposicion_nc_anulada`: 61).
`folio_ref`	int positivo	Folio del documento referenciado.
`fecha_ref`	string	`YYYY-MM-DD` del documento referenciado.
`cod_ref`	1 \| 2 \| 3	1 anula, 2 corrige texto (exige montos en 0), 3 corrige montos.
`razon_ref`	string	Motivo (mínimo 1 carácter).

Campos extra de 56 y 61

La Nota de Débito exige nd_reason con combos válidos de cod_ref (el motivo interese_moratorio_legal está bloqueado por el Oficio SII 2011/2020), y la Nota de Crédito aplica el plazo de 6 meses (Ley 21.398) y el bloqueo por factura cedida. El detalle completo está en Nota de Débito 56 y Nota de Crédito 61.

Requisitos de 33 y 34

La factura afecta (33) y la exenta (34) exigen el receptor completo — receptor.giro, receptor.direccion y receptor.comuna no pueden quedar vacíos — y forma_pago (1=Contado, 2=Crédito, 3=Sin costo). Este requisito es condicional al tipo: las notas (56/61), las boletas (39/41) y las guías (52) no lo exigen.

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",
  "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"
  }
}

links.events apunta a un endpoint aún no habilitado — para seguir el estado usa links.self o refresh-status.

Errores posibles:

Código	HTTP	`next_action`
`idempotency_key_missing`	400	`send_idempotency_key_header`
`invalid_json`	400	`fix_json_body_and_retry`
`validation_failed` (incluye `issues[]` de Zod)	400	`fix_body_and_retry`
`cert_id_missing`	400	`send_cert_id_header`
`dte.tipo_not_supported`	400	`fix_tipo_dte_and_retry`
`unauthorized` · `invalid_api_key` · `api_key_revoked` · `api_key_expired`	401	`regenerate_api_key`
`billing.free_tier_exceeded`	402	`upgrade_plan`
`forbidden` (scope insuficiente)	403	`use_api_key_with_required_scope`
`caf_not_found` · `cert_not_found`	404	—
`idempotency_conflict` (mismo key, body distinto)	409	—
`caf_exhausted` · `caf_expired` · `cert_expired` · `emisor_rut_mismatch`	422	—
`dte.34.invalid_exenta`	422	`fix_tipo_dte_and_retry`
`dte.nota_credito.fuera_plazo`	422	`consult_lawyer_or_use_correction_path`
`nc.over_cedida.blocked`	422	`confirm_override_and_retry`
`dte.nota_debito.interese_moratorio_legal`	422	`consult_oficio_2011_2020`
`dte.nota_debito.invalid_reason`	422	`fix_reason_and_retry`

`GET /dtes`

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

Query param	Tipo	Requerido	Descripción
`limit`	int	no	1–100, default 20.
`sort`	enum	no	`folio` · `monto_total` · `fecha_emision` · `sii_status` · `created_at`.
`dir`	enum	no	`asc` · `desc`.

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",
      "monto_total": 297500,
      "sii_status": "EPR",
      "fecha_emision": "2026-06-09",
      "created_at": "2026-06-09T14:32:48.000Z",
      "links": { "self": "/api/v1/dtes/01977f2a-1b50-7000-8000-000000000001" }
    }
  ],
  "next_cursor": null
}

Errores posibles: 401 (auth) y 403 forbidden si el key no tiene dte:read.

`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",
  "monto_neto": 250000,
  "monto_exento": 0,
  "iva": 47500,
  "monto_total": 297500,
  "sii_env": "cert",
  "sii_status": "EPR",
  "sii_glosa": null,
  "track_id": 998877665544,
  "fecha_emision": "2026-06-09",
  "created_at": "2026-06-09T14:32:48.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"
  }
}

Errores posibles:

Código	HTTP	`next_action`
`not_found`	404	—

`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:

Código	HTTP	`next_action`
`not_found`	404	—
`dte.pdf.not_signed` (todavía sin firmar; incluye `xml_url`)	409	`poll_self`

`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_..."

Errores posibles:

Código	HTTP	`next_action`
`not_found`	404	—
`dte.xml.not_yet_available` (workflow de firma en curso)	404	`poll_self`

`POST /dtes/:id/refresh-status`

Fuerza una re-consulta del estado del DTE al SII (útil tras una caída del SII); el poll corre en background y actualiza el documento.

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:

{ "id": "01977f2a-1b50-7000-8000-000000000001", "status": "refresh_enqueued" }

Errores posibles:

Código	HTTP	`next_action`
`not_found`	404	—
`dte.refresh_status.no_track_id` (aún no subido al SII)	409	`wait_for_emit_workflow`
`dte.refresh_status.no_cert` (la org no tiene certificado activo)	409	—

`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:

Código	HTTP	`next_action`
`dte.muestras.empty`	422	`emit_and_sign_dtes_first`

`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:

Código	HTTP	`next_action`
`dte.muestras.no_samples`	422	`emit_and_sign_dtes_first`
`dte.muestras.too_large` (lote supera 3MB del SII)	422	`paginate_into_multiple_emails`
`dte.muestras.send_not_configured`	422	`contact_support`
`dte.muestras.send_not_wired`	501	—

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.

API: DTEs

En esta página