Conceptos

Nodda es una capa de conexión, sync y normalización sobre fuentes externas como el SII o Banco Security. No hace scraping en vivo: cuando lees datos por la API, estás leyendo información que ya fue sincronizada y persistida. Esto hace que las lecturas sean rápidas, confiables y auditables, sin depender de la disponibilidad de la fuente en ese instante.

Organización

La unidad de aislamiento (multi-tenant). Toda conexión, corrida de sync, payload y API key pertenece a una organización. Una API key está atada a una sola organización y solo alcanza los datos de esa organización — el aislamiento se aplica en cada consulta por organization_id.

Conexión

El vínculo entre tu organización y una fuente externa (SII, Banco Security). Una conexión guarda las credenciales cifradas, los scopes habilitados y el estado operacional. Se crea y configura desde el dashboard de la plataforma en app.nodda.cl.

`status`	Significado
`pending`	recién creada, aún sin validar/sincronizar
`active`	operativa
`error`	última operación falló
`disabled`	deshabilitada

Con una API key puedes listar conexiones, consultar su estado, gatillar syncs y configurar el schedule, pero no crearlas ni borrarlas (eso es solo-dashboard). Ver Conexiones.

Scopes

Un scope es la unidad que seleccionas para sincronizar. Cada fuente tiene sus propios scopes:

Fuente	Scope	Qué sincroniza
`sii`	`rcv`	Compras y ventas RCV (documentos del Registro de Compras y Ventas)
`sii`	`guias`	Guías de despacho
`banco_security`	`directas`	Transferencias directas
`banco_security`	`masivas`	Nóminas masivas
`banco_security`	`saldos`	Saldos de cuenta corriente
`banco_security`	`movimientos`	Movimientos de la cuenta corriente (cartola)
`bci_pyme`	`saldos`	Saldos de cuenta
`bci_pyme`	`movimientos`	Movimientos detallados de la cuenta corriente

Modelo de sesión

Los scopes que habilites en una conexión corren todos en un solo login. No existe una operación previa de descubrimiento — el connector abre sesión una vez, ejecuta cada scope habilitado en secuencia, y cierra. Esto minimiza el número de autenticaciones contra la fuente.

Sync run (corrida de sincronización)

Una ejecución durable de un sync. Corre fuera del request: Nodda encola el trabajo, el endpoint de sync responde 202 con un sync_id, y el workflow lo procesa de forma asíncrona. Una corrida transiciona por estos estados:

`status`	Significado
`queued`	encolada, aún no empieza
`running`	en ejecución
`succeeded`	terminó OK
`failed`	falló
`partial`	terminó con resultados parciales en algún scope

Cada corrida expone scope_outcomes[] con el resultado por scope, además de contadores (records_found/created/updated) y, si falló, un error_code/error_message con secretos redactados. Ver Sync.

Datos crudos vs proyectados

El connector guarda el payload crudo y opaco que devuelve la fuente, hasheado y persistido para auditoría. Sobre ese payload, un projector genera filas normalizadas que sí se exponen por la API:

Scope	Datos proyectados accesibles vía API
`rcv`	Documentos RCV del SII (`/sii-rcv-documents`)
`guias`	Guías de despacho del SII
`directas`	Transferencias directas de Banco Security
`masivas`	Nóminas masivas de Banco Security
`saldos`	Saldos de cuenta (`/security-balances`, `/bci-balances`)
`movimientos`	Movimientos de cuenta (`/security-movements`, `/bci-movements`)

El puente scope → datos

Cada scope habilitado en una conexión trae un campo data_url en la respuesta de GET /api/connections/{id}. Ese URL apunta al endpoint de datos proyectados para ese scope. Un agente puede descubrir dónde leer los datos directamente desde el objeto de conexión — sin hardcodear rutas:

# 1. Consulta la conexión
curl -H "Authorization: Bearer nodda_sk_tu_key" \
  https://app.nodda.cl/api/connections/conn_abc123
 
# La respuesta incluye data_url por cada scope habilitado:
# {
#   "data": {
#     "id": "conn_abc123",
#     "enabled_scopes": ["rcv", "guias"],
#     "scopes": [
#       { "name": "rcv",   "label": "Compras y ventas (RCV)", "data_url": "/api/connections/conn_abc123/sii-rcv-documents",  "filters": { "period": "YYYY-MM", "direction": ["received","issued"], "from": "YYYY-MM-DD", "to": "YYYY-MM-DD" }, "sync_metadata": { } },
#       { "name": "guias", "label": "Guías de despacho",      "data_url": "/api/connections/conn_abc123/sii-dispatch-guides", "filters": { "period": "YYYY-MM", "direction": ["received","issued"], "q": "string", "from": "YYYY-MM-DD", "to": "YYYY-MM-DD" }, "sync_metadata": { } }
#     ]
#   }
# }
 
# 2. Lee directamente usando el data_url (base URL + data_url)
curl -H "Authorization: Bearer nodda_sk_tu_key" \
  https://app.nodda.cl/api/connections/conn_abc123/sii-dispatch-guides

Cómo encaja todo

Organización
  └─ Conexión (a una fuente, con scopes habilitados)
       ├─ Sync run  ──gatilla──>  Payloads crudos  ──proyecta──>  Datos normalizados (por scope)
       └─ Webhooks  <──emite──    sync.succeeded / sync.failed   (Ver Webhooks)

On this page