API de Nextcloud Tables

Integración con Nextcloud Tables para operaciones CRUD, gestión de esquemas de tablas, paginación de filas y proxy de autenticación del lado del servidor.

Última actualización: 2025-02-18

API de Nextcloud Tables

Certexi se integra con Nextcloud Tables para la gestión de datos estructurados. Todas las llamadas API se envían a través de un proxy del lado del servidor para evitar problemas de CORS y proteger credenciales.

Autenticación

Todas las solicitudes requieren headers de autenticación de Nextcloud:

Authorization: Bearer <token> | Basic <credentials>
X-NextCloud-Instance: https://cloud.example.com
X-NextCloud-Username: username

La API soporta tokens OAuth Bearer con fallback automático a App Password.

Operaciones de Tablas

GET/api/tables

Listar todas las tablas

Retorna todas las tablas accesibles al usuario autenticado con metadatos.

{
  "success": true,
  "data": {
    "tables": [
      {
        "id": 1,
        "title": "Shipments",
        "emoji": "📦",
        "rowsCount": 150,
        "columnsCount": 8,
        "lastEditAt": "2024-01-15T10:30:00Z",
        "ownerDisplayName": "John Doe"
      }
    ],
    "count": 1
  }
}
GET/api/tables/:tableId

Obtener detalles de tabla con esquema

Retorna información completa de la tabla incluyendo esquema de columnas, estadísticas y filas de ejemplo.

El esquema incluye tipos de columna, reglas de validación y configuración de visualización:

{
  "schema": [
    {
      "id": 1,
      "title": "Shipment ID",
      "type": "text",
      "mandatory": true,
      "textAllowedPattern": "^[A-Z]{2}[0-9]{6}$",
      "textMaxLength": 8
    },
    {
      "id": 2,
      "title": "Weight",
      "type": "number",
      "numberMin": 0,
      "numberMax": 1000,
      "numberDecimals": 2,
      "numberSuffix": "kg"
    }
  ]
}
POST/api/tables

Crear una nueva tabla

{
  "title": "New Shipments Table",
  "emoji": "📦",
  "template": "custom",
  "description": "Table for tracking shipment data"
}

El título es requerido (máximo 200 caracteres). Retorna la tabla creada con su ID.

PUT/api/tables/:tableId

Actualizar metadatos de tabla

Actualizar título, emoji o descripción. Solo los campos proporcionados se modifican.

DELETE/api/tables/:tableId

Eliminar una tabla

🚨

Operación Destructiva

Eliminar una tabla remueve permanentemente todas las filas y definiciones de columnas. Esta acción no se puede deshacer.

Operaciones de Filas

GET/api/tables/:tableId/rows

Obtener filas paginadas

Soporta paginación con limit (1-1000, por defecto 50) y parámetros offset.

{
  "success": true,
  "data": {
    "items": [
      {
        "id": 1,
        "data": { "1": "SH123456", "2": 25.5 },
        "createdBy": "user123",
        "createdAt": "2024-01-15T10:30:00Z"
      }
    ],
    "total": 150,
    "limit": 50,
    "offset": 0,
    "hasMore": true
  }
}
POST/api/tables/:tableId/rows

Crear una fila

Los datos se proporcionan como mapeo de ID de columna a valor:

{
  "data": {
    "1": "SH789012",
    "2": 45.2,
    "3": "Los Angeles"
  }
}
PUT/api/tables/:tableId/rows/:rowId

Actualizar una fila

Solo los valores de columna proporcionados se actualizan. Las columnas omitidas permanecen sin cambios.

DELETE/api/tables/:tableId/rows/:rowId

Eliminar una fila

Remueve permanentemente la fila de la tabla.

Cliente TypeScript

Certexi proporciona un cliente API tipado para integración frontend:

import {
  tablesApiClient,
  configureTablesApiClient,
} from '@/lib/nextcloud/tables-api-client';

configureTablesApiClient({
  Authorization: 'Bearer your_token',
  'X-NextCloud-Instance': 'https://cloud.example.com',
  'X-NextCloud-Username': 'username',
});

const { tables } = await tablesApiClient.getTables();
const { items: rows } = await tablesApiClient.getRows(tableId, { limit: 100 });
const newRow = await tablesApiClient.createRow(tableId, {
  data: { '1': 'Value' },
});

Códigos de Error

CódigoDescripción
INVALID_TABLE_IDEl ID de tabla no es un entero válido
INVALID_ROW_IDEl ID de fila no es un entero válido
MISSING_TITLEEl título de tabla es requerido para la creación
TITLE_TOO_LONGEl título excede 200 caracteres
INVALID_ROW_DATALos datos de fila faltan o están malformados
EMPTY_ROW_DATAEl objeto de datos de fila no tiene entradas
NEXTCLOUD_API_ERRORError del API upstream de Nextcloud
CONNECTION_ERRORNo se puede conectar a la instancia de Nextcloud

Seguridad

  • Todas las llamadas API de Nextcloud se envían a través de un proxy del lado del servidor
  • Las credenciales nunca se exponen al navegador
  • Validación de entrada en todos los parámetros de solicitud
  • Límites de tasa protegen contra abuso de la API
  • Las respuestas de error se sanitizan para prevenir fuga de información

Relacionado