Para agentes

Nodda está diseñado para operar sin intervención humana. Un agente puede descubrir conexiones, disparar syncs, esperar resultados y leer datos usando únicamente la API REST — sin scraping, sin sesiones de navegador.

El loop autónomo

1. Descubrir fuentes disponibles

curl https://app.nodda.cl/api/external-sources \
  -H "Authorization: Bearer nodda_sk_tu_token_aqui"

Devuelve el catálogo público de fuentes (SII, Banco Security…) con sus scopes disponibles. No requiere conexión activa.

2. Listar conexiones de la organización

curl https://app.nodda.cl/api/connections \
  -H "Authorization: Bearer nodda_sk_tu_token_aqui"

Devuelve todas las conexiones de la organización asociada a la key. Cada conexión incluye su campo scopes[] con name, label, data_url, filters y sync_metadata — suficiente para que el agente sepa qué datos puede consultar y cómo disparar un sync con los parámetros correctos.

3. Sincronizar

curl -X POST https://app.nodda.cl/api/connections/3f1c9e2a-7b44-4d51-9a0e-1c2d3e4f5a6b/sync \
  -H "Authorization: Bearer nodda_sk_tu_token_aqui" \
  -H "Content-Type: application/json" \
  -d '{ "scopes": ["rcv"], "metadata": { "period": "2026-05" } }'

La API responde 202 de inmediato con la corrida encolada:

{
  "sync_id": "9b8c7d6e-5f4a-3b2c-1d0e-9f8a7b6c5d4e",
  "connection_id": "3f1c9e2a-7b44-4d51-9a0e-1c2d3e4f5a6b",
  "scopes": ["rcv"],
  "status": "queued"
}

El 202 confirma que la corrida quedó encolada. El sync real ocurre en un workflow asíncrono fuera del request.

4. Esperar

Haz polling sobre GET /connections/{id}/sync-runs/{sync_id} hasta que status sea terminal (succeeded, partial o failed):

curl https://app.nodda.cl/api/connections/3f1c9e2a-7b44-4d51-9a0e-1c2d3e4f5a6b/sync-runs/9b8c7d6e-5f4a-3b2c-1d0e-9f8a7b6c5d4e \
  -H "Authorization: Bearer nodda_sk_tu_token_aqui"

Estados terminales:

Cuando el estado es partial, scope_outcomes[] te dice exactamente qué scope falló y por qué:

{
  "scope_outcomes": [
    { "scope": "rcv",   "status": "ok",     "records_found": 42, "period": "2026-05", "error_code": null, "notices": [] },
    { "scope": "guias", "status": "failed",  "records_found": null, "period": "2026-05", "error_code": "fetch_error", "error_message": "No se pudo conectar al portal", "notices": [] }
  ]
}

Un scope ok puede traer notices: avisos informativos que no degradan la corrida. P. ej. SII solo conserva el detalle de guías de los últimos 6 meses; para periodos más viejos el scope guias termina ok con un aviso de código estable:

{
  "scope": "guias",
  "status": "ok",
  "records_found": 0,
  "notices": [
    { "code": "sii.guias.out_of_window", "message": "2 period(s) outside the 6-month detail window" }
  ]
}

5. Leer

Con la corrida en succeeded o partial, usa el data_url del scope (del descriptor de la conexión) para consultar los datos proyectados:

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"

Contrato legible por máquina

La especificación completa de la API está disponible en formato OpenAPI 3.1:

https://app.nodda.cl/api/openapi.json

Cualquier framework de agentes (LangChain, LlamaIndex, Claude Tool Use, OpenAI Function Calling…) puede introspectarla directamente para descubrir endpoints, parámetros y esquemas de respuesta sin necesidad de documentación adicional.

Versión Markdown de cada página

Cada página de esta documentación se sirve también en Markdown para consumo por LLMs. Basta agregar .md al final de la URL:

• https://nodda.cl/docs/agents.md
• https://nodda.cl/docs/index.md
• https://nodda.cl/docs/sync.md
• https://nodda.cl/docs/connections.md

Reglas clave para un agente

• La organización se resuelve desde la key: el header Authorization: Bearer nodda_sk_… determina la organización — no hay que pasar organization_id explícitamente.
• direction usa received/issued: no recibida/emitida. Así lo devuelve la API en todos los endpoints.
• Los montos vienen como strings JSON: "amount": "2500000.00" — parsea a decimal antes de operar aritméticamente.
• Usa …/periods para descubrir periodos disponibles: los siete endpoints de lista principal (sii-rcv-documents, sii-dispatch-guides, sii-boletas, security-transfers, security-nominas, security-movements, bci-movements) exponen un sub-recurso /periods que lista los periodos con registros. Úsalo en vez de adivinar rangos de fecha. El sub-listado …/pagos no tiene /periods.
• scope_outcomes[] te dice qué falló en un partial: cuando status es partial, itera scope_outcomes para saber qué scopes completaron y cuáles no, en vez de asumir que todos fallaron. Después de iterar scope_outcomes, usa scope_outcomes[].period para llamar al read endpoint de cada scope con el periodo correcto (?period=); en scopes point-in-time period es null y se consulta con ?latest=true.
• Revisa notices incluso en ok/succeeded: un scope puede completar ok y aun así dejar avisos informativos (notices: [{ code, message }], con code estable). P. ej. sii.guias.out_of_window significa que esos periodos quedaron fuera de la ventana de 6 meses de SII: no es un error y reintentar no los recupera, así que no los reintentes en loop.
• Crear o eliminar conexiones es solo-dashboard: las API keys reciben 403 en esas operaciones. El agente puede leer y sincronizar, pero la gestión de conexiones es tarea del operador humano desde la plataforma.
• Paginación limit/offset: todos los endpoints de lista aceptan limit (1–200, por defecto 50) y offset (por defecto 0). Usa has_more en la respuesta para saber si hay más páginas.