SII

El SII (Servicio de Impuestos Internos de Chile) es una fuente activa de Nodda. Una conexión al SII sincroniza el RCV (Registro de Compras y Ventas), las guías de despacho y las boletas electrónicas, proyectando sus documentos a un formato consultable por API.

Scopes del SII

Scope	Qué sincroniza
`rcv`	Documentos del Registro de Compras y Ventas
`guias`	Guías de despacho (consemitidos)
`boletas`	Resumen diario de boletas electrónicas de venta (afecta y exenta)

Habilítalos al crear la conexión (enabled_scopes) y elígelos al gatillar un sync.

Modos de credencial

El SII soporta dos modos (configurados al crear la conexión en la plataforma):

portal_credentials — RUT + clave del portal SII.
certificate — certificado digital (.pfx).

El material de certificado y las credenciales se cifran y nunca salen por la API ni se envían a componentes que no los necesiten.

Webhook de sync

Al terminar un sync, Nodda emite un webhook sync.succeeded (o sync.partial / sync.failed). El sobre y la firma son genéricos; lo específico del SII es data.scopeOutcomes[], con una entrada por scope sincronizado. Cada entrada trae el scope y el period (YYYY-MM) que sincronizó, para que llames al read endpoint con el período correcto:

{
  "type": "sync.succeeded",
  "timestamp": "2026-06-05T14:05:33.000Z",
  "data": {
    "syncRunId": "9b8c7d6e-5f4a-3b2c-1d0e-aabbccddee01",
    "organizationId": "11111111-2222-3333-4444-555555555555",
    "connectionId": "3f1c9e2a-7b44-4d51-9a0e-1c2d3e4f5a6b",
    "status": "succeeded",
    "scopes": ["rcv"],
    "scopeOutcomes": [
      { "scope": "rcv", "status": "ok", "recordsFound": 42, "period": "2026-05" }
    ]
  }
}

El scope rcv cubre ambas direcciones (compras y ventas) en una sola entrada. Con su period, lista los documentos: GET /connections/{id}/sii-rcv-documents?period=2026-05.
Si habilitas guias o boletas, cada uno emite su propia entrada en scopeOutcomes[] con su period.
Itera scopeOutcomes[] y actúa por scope según su status (ok / partial / failed). El period viene incluso en outcomes partial o failed.

Scope `rcv` — RCV (Registro de Compras y Ventas)

Metadata de sync

Al gatillar un sync del scope rcv puedes pasar los siguientes parámetros en metadata:

Parámetro	Tipo	Notas
`period`	string	Período a sincronizar en formato `YYYY-MM` (p. ej. `2026-05`)

El scope rcv sincroniza siempre ambas direcciones (received y issued) y todos los tipos de documento del SII.

Cobertura por estado contable

El scope rcv captura todos los estados contables de compras en cada sincronización —tanto las programadas como las manuales—: REGISTRO, PENDIENTE, NO_INCLUIR y RECLAMADO. Esto garantiza que ningún documento queda fuera del historial independientemente de su casilla registral. Las ventas se capturan siempre en estado REGISTRO.

El campo `estado`

Cada documento RCV expone el campo estado, que refleja el estadoContab (casilla contable) asignado por el SII al momento de la sincronización:

Valor	Descripción
`registro`	Documento ingresado al libro de compras/ventas (estado normal)
`pendiente`	Documento recibido pero aún no contabilizado
`no_incluir`	Documento marcado para no incluir en el período
`reclamado`	Documento reclamado ante el SII

estado ≠ status: Son dos campos distintos. estado representa la casilla contable en el RCV (en qué bolsillo registral está el documento). status representa el evento de acuse o reclamo sobre el DTE (p. ej. accept, claimed) tal como lo reporta la leyenda del SII. Un documento puede estar en estado registro y al mismo tiempo tener status: "accept".

Listar documentos RCV

GET /connections/{id}/sii-rcv-documents

Lista los documentos RCV proyectados de una conexión, ordenados por la fecha de emisión del documento (issued_at) descendente y paginados (50 por página por defecto). Cada fila incluye todos los campos de contenido del documento (montos, fechas, partes, estado…) para que puedas procesar el listado sin una consulta por documento. El detalle agrega además raw_row y los identificadores internos de trazabilidad.

Query	Tipo	Notas
`period`	string	período contable en formato `YYYY-MM` (p. ej. `2026-05`)
`direction`	string	`received` (compra) o `issued` (venta)
`estado`	string	filtra por estado contable: `registro`, `pendiente`, `no_incluir` o `reclamado`
`from`	string	fecha mínima de emisión `YYYY-MM-DD`
`to`	string	fecha máxima de emisión `YYYY-MM-DD`
`limit`	number	máximo de documentos a devolver (por defecto 50, máximo 200)
`offset`	number	documentos a omitir para paginar (por defecto 0)

curl "https://app.nodda.cl/api/connections/3f1c9e2a-7b44-4d51-9a0e-1c2d3e4f5a6b/sii-rcv-documents?period=2026-05&direction=received" \
  -H "Authorization: Bearer nodda_sk_tu_token_aqui"

Respuesta (200):

{
  "data": [
    {
      "id": "7c6b5a49-3e2d-1c0b-9a8f-7e6d5c4b3a21",
      "period": "2026-05",
      "direction": "received",
      "document_type": "33",
      "folio": "12345",
      "issuer_rut": "76.123.456-7",
      "issuer_name": "Proveedor SpA",
      "receiver_rut": "77.987.654-3",
      "receiver_name": "Mi Empresa SpA",
      "issued_at": "2026-05-15T10:30:00.000Z",
      "received_at": "2026-05-16T08:00:00.000Z",
      "net_amount": "1260504.00",
      "exempt_amount": null,
      "vat_amount": "239496.00",
      "total_amount": "1500000.00",
      "currency": "CLP",
      "estado": "registro",
      "status": "accept",
      "referenced_document_type": null,
      "referenced_folio": null,
      "acknowledged_at": null,
      "claimed_at": null,
      "transaction_type": null,
      "created_at": "2026-05-20T12:00:00.000Z"
    }
  ],
  "pagination": { "total": 181, "limit": 50, "offset": 0, "has_more": true }
}

Los documentos se ordenan por la fecha de emisión del documento (issued_at, descendente; los documentos sin fecha quedan al final), desempatando por tipo y folio (orden numérico), y finalmente por created_at. has_more indica si existen más páginas. Cuando offset es mayor o igual a total (paginando más allá del final), total se reporta como 0.

Campos de un documento RCV

Cada fila del listado expone estos campos de contenido del documento:

Campo	Tipo	Notas
`id`	UUID	identificador del documento en Nodda
`period`	string	período contable `YYYY-MM`
`direction`	string	`received` (compra) · `issued` (venta)
`document_type`	string	código de tipo de documento del SII (p. ej. `33` factura, `34` exenta, `61` nota de crédito)
`folio`	string	folio asignado por el SII
`issuer_rut`	string \| null	RUT del emisor
`issuer_name`	string \| null	razón social del emisor
`receiver_rut`	string \| null	RUT del receptor
`receiver_name`	string \| null	razón social del receptor
`issued_at`	datetime \| null	fecha de emisión
`received_at`	datetime \| null	fecha de recepción registrada en el SII
`net_amount`	string \| null	monto neto (decimal como string, 2 decimales)
`exempt_amount`	string \| null	monto exento (decimal como string, 2 decimales)
`vat_amount`	string \| null	IVA (decimal como string, 2 decimales)
`total_amount`	string \| null	monto total (decimal como string, 2 decimales)
`currency`	string	moneda del documento (por defecto `CLP`)
`estado`	string	casilla contable en el RCV: `registro` · `pendiente` · `no_incluir` · `reclamado`
`status`	string \| null	evento de acuse/reclamo sobre el DTE (p. ej. `accept`, `claimed`)
`referenced_document_type`	string \| null	tipo de documento referenciado (p. ej. en una nota de crédito)
`referenced_folio`	string \| null	folio referenciado
`acknowledged_at`	datetime \| null	fecha de acuse de recibo
`claimed_at`	datetime \| null	fecha de reclamo
`transaction_type`	string \| null	tipo de transacción declarado en el RCV
`created_at`	datetime \| null	cuándo Nodda proyectó esta fila

Los montos se serializan como string para no perder precisión decimal. Filtros combinables con AND. period debe ser exactamente YYYY-MM; direction solo received o issued; estado solo registro, pendiente, no_incluir o reclamado. Valores fuera de rango responden 400 validation_error. Si la conexión no existe en tu organización → 404 connection_not_found.

El detalle (/sii-rcv-documents/{document_id}) devuelve estos mismos campos y además raw_row (el JSON crudo del SII) y los identificadores internos de trazabilidad: connection_id, sync_run_id, raw_payload_id y source_document_id.

Obtener un documento RCV

GET /connections/{id}/sii-rcv-documents/{document_id}

Devuelve un documento RCV individual con los mismos campos de contenido del listado y además raw_row (el JSON crudo de la fila tal como la entregó el SII) y los identificadores internos de trazabilidad (connection_id, sync_run_id, raw_payload_id, source_document_id). document_id es el UUID del documento en Nodda (campo id del listado).

curl "https://app.nodda.cl/api/connections/3f1c9e2a-7b44-4d51-9a0e-1c2d3e4f5a6b/sii-rcv-documents/7c6b5a49-3e2d-4c0b-9a8f-7e6d5c4b3a21" \
  -H "Authorization: Bearer nodda_sk_tu_token_aqui"

Respuesta (200):

{
  "data": {
    "id": "7c6b5a49-3e2d-4c0b-9a8f-7e6d5c4b3a21",
    "connection_id": "3f1c9e2a-7b44-4d51-9a0e-1c2d3e4f5a6b",
    "sync_run_id": "9b8a7c6d-5e4f-3a2b-1c0d-9e8f7a6b5c4d",
    "raw_payload_id": "2d3e4f5a-6b7c-8d9e-0a1b-2c3d4e5f6a7b",
    "source_document_id": "received:2026-05:33:12345:76.123.456-7:",
    "period": "2026-05",
    "direction": "received",
    "document_type": "33",
    "folio": "12345",
    "issuer_rut": "76.123.456-7",
    "issuer_name": "Proveedor SpA",
    "receiver_rut": "77.987.654-3",
    "receiver_name": "Mi Empresa SpA",
    "issued_at": "2026-05-15T10:30:00.000Z",
    "received_at": "2026-05-16T08:00:00.000Z",
    "net_amount": "1260504.00",
    "exempt_amount": null,
    "vat_amount": "239496.00",
    "total_amount": "1500000.00",
    "currency": "CLP",
    "estado": "registro",
    "status": "accept",
    "referenced_document_type": null,
    "referenced_folio": null,
    "acknowledged_at": null,
    "claimed_at": null,
    "transaction_type": null,
    "raw_row": { "detNroDoc": "12345", "detRznSoc": "Proveedor SpA", "detMntTotal": 1500000 },
    "created_at": "2026-05-20T12:00:00.000Z"
  }
}

Un document_id con formato inválido responde 400 validation_error. Si el documento no existe en tu organización → 404 rcv_document_not_found; si la conexión no existe → 404 connection_not_found.

Períodos disponibles (RCV)

GET /connections/{id}/sii-rcv-documents/periods

Devuelve la lista de períodos YYYY-MM que tienen al menos un documento RCV proyectado.

curl "https://app.nodda.cl/api/connections/3f1c9e2a-7b44-4d51-9a0e-1c2d3e4f5a6b/sii-rcv-documents/periods" \
  -H "Authorization: Bearer nodda_sk_tu_token_aqui"

Respuesta (200):

{
  "data": ["2026-05", "2026-04", "2026-03"]
}

Scope `guias` — Guías de despacho

Metadata de sync

Al gatillar un sync del scope guias puedes pasar los siguientes parámetros en metadata:

Parámetro	Tipo	Notas
`period`	string	Período a sincronizar en formato `YYYY-MM`
`issueType`	string	`issued` o `received` (opcional)

Listar guías de despacho

GET /connections/{id}/sii-dispatch-guides

Lista las guías de despacho proyectadas de una conexión, ordenadas por fecha de creación descendente y paginadas (50 por página por defecto).

Query	Tipo	Notas
`period`	string	período contable en formato `YYYY-MM`
`direction`	string	`received` o `issued`
`from`	string	fecha mínima de emisión `YYYY-MM-DD`
`to`	string	fecha máxima de emisión `YYYY-MM-DD`
`q`	string	búsqueda libre por texto (razón social, folio, RUT)
`limit`	number	máximo de registros a devolver (por defecto 50, máximo 200)
`offset`	number	registros a omitir para paginar (por defecto 0)

curl "https://app.nodda.cl/api/connections/3f1c9e2a-7b44-4d51-9a0e-1c2d3e4f5a6b/sii-dispatch-guides?period=2026-05&direction=issued" \
  -H "Authorization: Bearer nodda_sk_tu_token_aqui"

Respuesta (200):

{
  "data": [
    {
      "id": "a1b2c3d4-e5f6-7890-abcd-ef1234567890",
      "period": "2026-05",
      "direction": "issued",
      "folio": "98765",
      "counterparty_rut": "76.123.456-7",
      "counterparty_name": "Cliente SpA",
      "issued_at": "2026-05-10T09:00:00.000Z",
      "total_amount": "250000.00",
      "vat_amount": "39916.00",
      "status": null
    }
  ],
  "pagination": { "total": 14, "limit": 50, "offset": 0, "has_more": false }
}

Obtener una guía de despacho

GET /connections/{id}/sii-dispatch-guides/{guide_id}

Devuelve una guía individual con todos sus campos, incluido raw_row.

curl "https://app.nodda.cl/api/connections/3f1c9e2a-7b44-4d51-9a0e-1c2d3e4f5a6b/sii-dispatch-guides/a1b2c3d4-e5f6-7890-abcd-ef1234567890" \
  -H "Authorization: Bearer nodda_sk_tu_token_aqui"

Respuesta (200):

{
  "data": {
    "id": "a1b2c3d4-e5f6-7890-abcd-ef1234567890",
    "connection_id": "3f1c9e2a-7b44-4d51-9a0e-1c2d3e4f5a6b",
    "sync_run_id": "9b8c7d6e-5f4a-3b2c-1d0e-9f8a7b6c5d4e",
    "raw_payload_id": "c4d5e6f7-0123-4567-89ab-cdef01234567",
    "source_guide_id": "GD-98765",
    "direction": "issued",
    "document_type": "52",
    "period": "2026-05",
    "folio": "98765",
    "counterparty_rut": "76.123.456-7",
    "counterparty_name": "Cliente SpA",
    "net_amount": "210084.00",
    "exempt_amount": null,
    "vat_amount": "39916.00",
    "total_amount": "250000.00",
    "vat_rate": "19.00",
    "issued_at": "2026-05-10T09:00:00.000Z",
    "received_at": null,
    "event_order": null,
    "event_description": null,
    "dhdr_codigo": null,
    "raw_row": { "folio": "98765", "rznSocRecep": "Cliente SpA" },
    "created_at": "2026-05-11T08:00:00.000Z"
  }
}

Períodos disponibles (guías)

GET /connections/{id}/sii-dispatch-guides/periods

curl "https://app.nodda.cl/api/connections/3f1c9e2a-7b44-4d51-9a0e-1c2d3e4f5a6b/sii-dispatch-guides/periods" \
  -H "Authorization: Bearer nodda_sk_tu_token_aqui"

Respuesta (200):

{
  "data": ["2026-05", "2026-04"]
}

Scope `boletas` — Boletas electrónicas

Resumen diario de boletas electrónicas de venta. A diferencia del RCV, el SII no expone las boletas folio a folio: solo entrega un agregado por día y por tipo de documento. Cada fila representa un día; en cada sincronización se actualiza (no se duplica), y el campo updated_at indica cuán reciente es el dato. El historial de cada sincronización queda íntegro en los payloads crudos.

Tipos de documento incluidos: 39 (boleta electrónica afecta) y 41 (boleta exenta electrónica). Son siempre de venta.

Metadata de sync

Al gatillar un sync del scope boletas puedes pasar los siguientes parámetros en metadata:

Parámetro	Tipo	Notas
`period`	string	Período a sincronizar en formato `YYYY-MM`. Por defecto, el período tributario actual

Listar boletas diarias

GET /connections/{id}/sii-boletas

Lista el resumen diario de boletas de una conexión, ordenado por fecha descendente y paginado (50 por página por defecto).

Query	Tipo	Notas
`period`	string	período en formato `YYYY-MM`
`document_type`	string	`39` (afecta) o `41` (exenta)
`from`	string	fecha mínima `YYYY-MM-DD`
`to`	string	fecha máxima `YYYY-MM-DD`
`limit`	number	máximo de filas a devolver (por defecto 50, máximo 200)
`offset`	number	filas a omitir para paginar (por defecto 0)

curl "https://app.nodda.cl/api/connections/3f1c9e2a-7b44-4d51-9a0e-1c2d3e4f5a6b/sii-boletas?period=2026-06&document_type=39" \
  -H "Authorization: Bearer nodda_sk_tu_token_aqui"

Respuesta (200):

{
  "data": [
    {
      "id": "b1a2c3d4-e5f6-7890-abcd-ef1234567890",
      "period": "2026-06",
      "document_type": "39",
      "day": 1,
      "date": "2026-06-01T00:00:00.000Z",
      "total_documentos": 101,
      "net_amount": "705288.00",
      "exempt_amount": "0.00",
      "vat_amount": "134002.00",
      "total_amount": "839290.00",
      "channel": "9",
      "updated_at": "2026-06-19T17:30:00.000Z"
    }
  ],
  "pagination": { "total": 18, "limit": 50, "offset": 0, "has_more": false }
}

Campos de una boleta diaria

Campo	Tipo	Notas
`id`	UUID	identificador de la fila diaria en Nodda
`period`	string	período `YYYY-MM`
`document_type`	string	`39` boleta afecta · `41` boleta exenta
`day`	number	día del mes (1–31)
`date`	datetime \| null	fecha del día (medianoche UTC)
`total_documentos`	number \| null	cantidad de boletas de venta de ese día
`net_amount`	string \| null	monto neto (decimal como string, 2 decimales)
`exempt_amount`	string \| null	monto exento
`vat_amount`	string \| null	IVA
`total_amount`	string \| null	monto total
`channel`	string \| null	canal de transacción reportado por el SII
`updated_at`	datetime \| null	última vez que la fila se refrescó en una sincronización

Filtros combinables con AND. period debe ser exactamente YYYY-MM y document_type solo 39 o 41; otros valores responden 400 validation_error. Si la conexión no existe en tu organización → 404 connection_not_found.

Períodos disponibles (boletas)

GET /connections/{id}/sii-boletas/periods

Devuelve la lista de períodos YYYY-MM que tienen al menos una boleta diaria proyectada.

curl "https://app.nodda.cl/api/connections/3f1c9e2a-7b44-4d51-9a0e-1c2d3e4f5a6b/sii-boletas/periods" \
  -H "Authorization: Bearer nodda_sk_tu_token_aqui"

Respuesta (200):

{
  "data": ["2026-06", "2026-05"]
}

On this page