De cero a leer datos

Nodda es una capa de conexión, sincronización y normalización de datos externos. No es una API de scraping en vivo: tú creas una conexión a una fuente, Nodda la sincroniza —manual o programado— y tú consultas datos persistidos y trazables vía una API rápida, autenticada con API keys.

Esta guía te lleva de cero hasta leer documentos del SII con curl.

1. Genera una API key

En el dashboard, anda a app.nodda.cl/settings/api-keys y crea una key.

El token tiene la forma nodda_sk_… y se muestra una sola vez — guárdalo en tu gestor de secretos.

La key pertenece a una sola organización. Nodda resuelve la organización desde la key; no necesitas enviar ningún header adicional.

2. Descubre fuentes y scopes

Consulta qué fuentes externas están disponibles y qué scopes (capacidades) expone cada una. Este endpoint es público — no requiere autenticación.

curl https://app.nodda.cl/api/external-sources
# {
#   "data": [
#     {
#       "code": "sii",
#       "name": "SII",
#       "supported_scopes": ["rcv", "guias"],
#       "scopes": [
#         {
#           "name": "rcv",
#           "label": "Registro de Compras y Ventas",
#           "sync_metadata": { "period": "YYYY-MM" },
#           "data_path_template": "/api/connections/{connection_id}/sii-rcv-documents",
#           "filters": { "direction": ["received", "issued"], "period": "YYYY-MM" }
#         },
#         {
#           "name": "guias",
#           "label": "Guías de Despacho",
#           "sync_metadata": { "period": "YYYY-MM" },
#           "data_path_template": "/api/connections/{connection_id}/sii-dispatch-guides",
#           "filters": { "period": "YYYY-MM" }
#         }
#       ]
#     }
#   ]
# }

Anota los name de los scopes que te interesan (p. ej. rcv) y los parámetros que acepta sync_metadata (p. ej. period).

3. Descubre tus conexiones

Lista las conexiones de tu organización. Las conexiones se crean desde la UI; aquí obtienes el id que usarás en los pasos siguientes y ves qué scopes tiene habilitados cada una.

curl https://app.nodda.cl/api/connections \
  -H "Authorization: Bearer nodda_sk_tu_token"
# {
#   "data": [
#     {
#       "id": "conn_abc123",
#       "external_source_code": "sii",
#       "enabled_scopes": ["rcv", "guias"],
#       "scopes": [
#         {
#           "name": "rcv",
#           "label": "Registro de Compras y Ventas",
#           "data_url": "/api/connections/conn_abc123/sii-rcv-documents",
#           "filters": { "direction": ["received", "issued"], "period": "YYYY-MM" },
#           "sync_metadata": { "period": "YYYY-MM" }
#         },
#         {
#           "name": "guias",
#           "label": "Guías de Despacho",
#           "data_url": "/api/connections/conn_abc123/sii-dispatch-guides",
#           "filters": { "period": "YYYY-MM" },
#           "sync_metadata": { "period": "YYYY-MM" }
#         }
#       ]
#     }
#   ]
# }

Guarda el id de la conexión (p. ej. conn_abc123) y nota scopes[].data_url — es la URL relativa donde leerás los datos una vez sincronizados.

4. Gatilla un sync

Un sync corre fuera del request (asíncrono). La API crea una corrida durable y responde 202 de inmediato con el sync_id.

Pasa en el body los scopes que quieres sincronizar y los parámetros de metadata que requiere cada scope (p. ej. period para el RCV del SII).

curl -X POST "https://app.nodda.cl/api/connections/conn_abc123/sync" \
  -H "Authorization: Bearer nodda_sk_tu_token" \
  -H "Content-Type: application/json" \
  -d '{"scopes":["rcv"],"metadata":{"period":"2026-05"}}'
# {
#   "sync_id": "sync_xyz789",
#   "connection_id": "conn_abc123",
#   "scopes": ["rcv"],
#   "status": "queued"
# }

Anota el sync_id — lo usarás para hacer polling en el paso siguiente.

5. Sigue el progreso (polling)

Consulta el estado de la corrida hasta que status sea succeeded o partial. Recomendamos esperar 2–5 segundos entre intentos.

curl "https://app.nodda.cl/api/connections/conn_abc123/sync-runs/sync_xyz789" \
  -H "Authorization: Bearer nodda_sk_tu_token"
# {
#   "data": {
#     "id": "sync_xyz789",
#     "status": "succeeded",
#     "scope_outcomes": [
#       {
#         "scope": "rcv",
#         "status": "ok",
#         "records_found": 123,
#         "period": "2026-05",
#         "error_code": null,
#         "error_message": null
#       }
#     ]
#   }
# }

Criterio de éxito: status ∈ {"succeeded", "partial"}. Si el status es partial, revisa scope_outcomes[] para ver qué scope quedó ok y cuál failed.

Loop de ejemplo:

while true; do
  STATUS=$(curl -s "https://app.nodda.cl/api/connections/conn_abc123/sync-runs/sync_xyz789" \
    -H "Authorization: Bearer nodda_sk_tu_token" | jq -r '.data.status')
  echo "status: $STATUS"
  [[ "$STATUS" == "succeeded" || "$STATUS" == "partial" ]] && break
  sleep 3
done

6. Lee los datos

Usa el data_url del scope (obtenido en el paso 3) para consultar los documentos proyectados. Agrega los filtros que necesites.

curl "https://app.nodda.cl/api/connections/conn_abc123/sii-rcv-documents?period=2026-05&direction=received" \
  -H "Authorization: Bearer nodda_sk_tu_token"
# {
#   "data": [ { ... }, { ... } ],
#   "pagination": {
#     "total": 123,
#     "limit": 50,
#     "offset": 0,
#     "has_more": false
#   }
# }

Usa direction=received para compras y direction=issued para ventas. Para guías de despacho, el path es /sii-dispatch-guides con los mismos filtros.

7. Próximos pasos

Conexiones — cómo crear y gestionar conexiones desde la UI.
Sync — schedule, retry, scope outcomes y webhooks de sync.
Fuentes externas — SII, Banco Security, BCI PyME y todos los scopes disponibles.
Referencia de la API — todos los endpoints y convenciones.
Autenticación — formato de la key, ciclo de vida, revocación.
Webhooks — recibe sync.succeeded / sync.failed y verifica la firma HMAC.

On this page