Conexiones

Una conexión vincula tu organización con una fuente externa. Con una API key puedes listar y consultar conexiones; crearlas o eliminarlas requiere sesión de usuario (se hace desde la plataforma). Las credenciales nunca se exponen en las respuestas.

Listar conexiones

GET /connections

Devuelve todas las conexiones de la organización derivada de la key.

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

Respuesta (200):

{
  "data": [
    {
      "id": "3f1c9e2a-7b44-4d51-9a0e-1c2d3e4f5a6b",
      "organization_id": "11111111-2222-3333-4444-555555555555",
      "external_source_code": "sii",
      "external_source_name": "SII",
      "name": "SII — Mi Empresa SpA",
      "status": "active",
      "enabled_scopes": ["rcv", "guias"],
      "scopes": [
        {
          "name": "rcv",
          "label": "RCV (Registro de Compras y Ventas)",
          "data_url": "/api/connections/3f1c9e2a-7b44-4d51-9a0e-1c2d3e4f5a6b/sii-rcv-documents",
          "filters": { "period": "YYYY-MM", "direction": ["received", "issued"], "from": "YYYY-MM-DD", "to": "YYYY-MM-DD" },
          "sync_metadata": {
            "period": { "type": "string", "description": "Período YYYY-MM" }
          }
        },
        {
          "name": "guias",
          "label": "Guías de despacho",
          "data_url": "/api/connections/3f1c9e2a-7b44-4d51-9a0e-1c2d3e4f5a6b/sii-dispatch-guides",
          "filters": { "period": "YYYY-MM", "direction": ["received", "issued"], "q": "string", "from": "YYYY-MM-DD", "to": "YYYY-MM-DD" },
          "sync_metadata": {
            "period": { "type": "string", "description": "Período YYYY-MM" },
            "issueType": { "type": "string", "enum": ["issued", "received"], "description": "Opcional" }
          }
        }
      ],
      "metadata": {},
      "sync_schedule_enabled": true,
      "sync_frequency_minutes": 1440,
      "next_scheduled_sync_at": "2026-06-10T00:00:00.000Z"
    }
  ]
}

Obtener una conexión

GET /connections/{id}

Como el listado, pero para una sola conexión e incluye además last_successful_sync_at y last_sync_status.

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

Respuesta (200):

{
  "data": {
    "id": "3f1c9e2a-7b44-4d51-9a0e-1c2d3e4f5a6b",
    "organization_id": "11111111-2222-3333-4444-555555555555",
    "external_source_code": "sii",
    "external_source_name": "SII",
    "name": "SII — Mi Empresa SpA",
    "status": "active",
    "enabled_scopes": ["rcv", "guias"],
    "scopes": [
      {
        "name": "rcv",
        "label": "RCV (Registro de Compras y Ventas)",
        "data_url": "/api/connections/3f1c9e2a-7b44-4d51-9a0e-1c2d3e4f5a6b/sii-rcv-documents",
        "filters": { "period": "YYYY-MM", "direction": ["received", "issued"], "from": "YYYY-MM-DD", "to": "YYYY-MM-DD" },
        "sync_metadata": {
          "period": { "type": "string", "description": "Período YYYY-MM" }
        }
      },
      {
        "name": "guias",
        "label": "Guías de despacho",
        "data_url": "/api/connections/3f1c9e2a-7b44-4d51-9a0e-1c2d3e4f5a6b/sii-dispatch-guides",
        "filters": { "period": "YYYY-MM", "direction": ["received", "issued"], "q": "string", "from": "YYYY-MM-DD", "to": "YYYY-MM-DD" },
        "sync_metadata": {
          "period": { "type": "string", "description": "Período YYYY-MM" },
          "issueType": { "type": "string", "enum": ["issued", "received"], "description": "Opcional" }
        }
      }
    ],
    "metadata": {},
    "last_successful_sync_at": "2026-06-09T00:14:02.000Z",
    "last_sync_status": "succeeded",
    "sync_schedule_enabled": true,
    "sync_frequency_minutes": 1440,
    "next_scheduled_sync_at": "2026-06-10T00:00:00.000Z"
  }
}

Si la conexión no existe o no pertenece a tu organización → 404 connection_not_found.

Campos de una conexión

Campo	Tipo	Notas
`id`	UUID	identificador de la conexión
`organization_id`	UUID	organización dueña
`external_source_code`	string	slug de la fuente (p. ej. `sii`, `banco_security`)
`external_source_name`	string	nombre legible de la fuente
`name`	string	nombre que le diste a la conexión
`status`	string	`pending` · `active` · `error` · `disabled`
`enabled_scopes`	string[]	nombres de scopes habilitados (p. ej. `["rcv", "guias"]`)
`scopes`	object[]	descriptores de scopes — ver abajo
`metadata`	object	metadata propia (nunca contiene credenciales)
`last_successful_sync_at`	datetime \| null	último sync exitoso (solo en `GET /{id}`)
`last_sync_status`	string \| null	estado del último sync (solo en `GET /{id}`)
`sync_schedule_enabled`	boolean	si el sync programado está activo
`sync_frequency_minutes`	number \| null	intervalo del schedule en minutos
`next_scheduled_sync_at`	datetime \| null	próxima corrida programada

Descriptor de scope (`scopes[]`)

Cada entrada en scopes describe un scope habilitado en la conexión:

Campo	Tipo	Notas
`name`	string	identificador del scope (p. ej. `rcv`, `masivas`)
`label`	string	nombre legible
`data_url`	string \| null	URL relativa del endpoint de datos para este scope
`filters`	object \| null	parámetros de filtrado disponibles en `data_url` (nombre → tipo/valores aceptados)
`sync_metadata`	object \| null	JSON Schema de los metadatos aceptados al gatillar un sync para este scope

data_url sirve para construir el request de lectura directamente desde el objeto conexión. Por ejemplo, si data_url es /api/connections/{id}/sii-rcv-documents, haz GET https://app.nodda.cl{data_url} para leer los documentos de ese scope.

Scopes por fuente

Fuente	Scopes disponibles
`sii`	`rcv`, `guias`
`banco_security`	`directas`, `masivas`, `saldos`, `movimientos`
`bci_pyme`	`saldos`, `movimientos`

Crear o eliminar una conexión (solo sesión)

POST /connections y DELETE /connections/{id} no son alcanzables con API key (responden 403 forbidden): requieren sesión de usuario y se usan desde la plataforma.

Las credenciales se guardan cifradas y se referencian por separado; nunca aparecen en estas respuestas.