Documentación API

Autenticación

Usa el mismo usuario de Comunidesk. El token OAuth identifica tu aplicación; el JWT de usuario autoriza qué puede hacer en cada edificio, igual que en la web.

# Token OAuth de tu aplicación
Authorization: Bearer <oauth_access_token>

# JWT de la cuenta Comunidesk del usuario
x-comunidesk-user-authorization: Bearer <user_jwt>

import Foundation

let gateway = "https://gateway.comunidesk.com"
let clientId = "CLIENT_ID"
let clientSecret = "CLIENT_SECRET"

var req = URLRequest(url: URL(string: "\(gateway)/oauth/token")!)
req.httpMethod = "POST"
let basic = Data("\(clientId):\(clientSecret)".utf8).base64EncodedString()
req.setValue("Basic \(basic)", forHTTPHeaderField: "Authorization")
req.setValue("application/x-www-form-urlencoded", forHTTPHeaderField: "Content-Type")
req.httpBody = "grant_type=client_credentials&scope=comunidesk:read%20comunidesk:write"
  .data(using: .utf8)

let (data, _) = try await URLSession.shared.data(for: req)
struct TokenResponse: Decodable { let access_token: String }
let token = try JSONDecoder().decode(TokenResponse.self, from: data).access_token

Entornos

Envía el header x-comunidesk-environment para enrutar la petición al backend del entorno (dev, rnd, stg, uat, qa, prod).

• dev Desarrollo — Pruebas locales / sandbox del integrador
• rnd I+D — Experimentos y spikes
• stg Staging — Pre-producción integrada
• uat UAT — Aceptación de usuario
• qa QA — Validación de calidad
• prod Producción — Datos reales de la cuenta

x-comunidesk-environment: stg

En entornos no-prod, prefija nombres de datos de prueba (p. ej. [STG] Mi edificio).

Protocolos

Elige el estilo de integración de tu stack. La taxonomía de entidades es la misma en REST, SOAP, GraphQL y OData.

• REST · /v1/rest/{EntitySet} · ?$stream=true (Streaming)
• SOAP · POST /v1/soap
• GraphQL · POST /v1/graphql
• OData v4 · /odata/v4/{EntitySet}?$filter=&$select=&$top=

Streaming de datos

Consume colecciones grandes en chunks sin esperar el JSON completo (ideal para apps móviles).

Por defecto GET /v1/rest/{EntitySet} devuelve un JSON con todo el array data. En módulos con muchos registros la app queda bloqueada hasta recibir la respuesta entera. Con modo stream el gateway pagina CouchDB en lotes de 50 y emite cada fila en cuanto la obtiene.

Activar streaming

Cualquiera de estas opciones en GET /v1/rest/{EntitySet} o GET /odata/v4/{EntitySet}:
• Query ?$stream=true o ?stream=true
• Header Accept: application/x-ndjson
• Header X-Comunidesk-Stream: ndjson

Formato NDJSON (CouchDB)

Content-Type: application/x-ndjson. Cada línea es un objeto JSON: • {"type":"meta",...} — metadatos iniciales • {"type":"item","data":{...}} — un registro • {"type":"done"} — fin del stream • {"type":"error","error":"..."} — error durante el stream

import Foundation

let oauthToken = "OAUTH_TOKEN"
let userJwt = "USER_JWT"
var req = URLRequest(url: URL(string: "https://gateway.comunidesk.com/v1/rest/Edificios?$stream=true&edificioId=EDIFICIO_ID")!)
req.httpMethod = "GET"
req.setValue("Bearer \(oauthToken)", forHTTPHeaderField: "Authorization")
req.setValue("Bearer \(userJwt)", forHTTPHeaderField: "x-comunidesk-user-authorization")
req.setValue("application/x-ndjson", forHTTPHeaderField: "Accept")
req.setValue("ndjson", forHTTPHeaderField: "X-Comunidesk-Stream")

struct StreamEvent: Decodable {
  let type: String
  let error: String?
}

let (bytes, response) = try await URLSession.shared.bytes(for: req)
for try await line in bytes.lines {
  guard !line.isEmpty, let row = line.data(using: .utf8) else { continue }
  let event = try JSONDecoder().decode(StreamEvent.self, from: row)
  switch event.type {
  case "item": /* parse event.data JSON y añadir a la lista */ break
  case "done": break
  case "error": throw URLError(.badServerResponse)
  default: break
  }
}

Passthrough sin buffer

GET/POST /v1/comunidesk/{ruta-backend} reenvía la respuesta upstream sin leer todo el body (chunked, SSE, descargas grandes). Útil cuando necesitas el endpoint tal cual existe en api.comunidesk.com.

GET https://gateway.comunidesk.com/v1/comunidesk/{ruta-backend}

Apps nativas (iOS / Android)

Después del login, consulta /v1/me/capabilities y muestra solo los módulos disponibles para ese usuario.

import Foundation

let oauthToken = "OAUTH_TOKEN"
let userJwt = "USER_JWT"
var req = URLRequest(url: URL(string: "https://gateway.comunidesk.com/v1/me/capabilities")!)
req.httpMethod = "GET"
req.setValue("Bearer \(oauthToken)", forHTTPHeaderField: "Authorization")
req.setValue("Bearer \(userJwt)", forHTTPHeaderField: "x-comunidesk-user-authorization")

struct CapName: Decodable { let es: String; let en: String }
struct CapModule: Decodable {
  let id: String
  let entitySet: String
  let canRead: Bool
  let canWrite: Bool
  let name: CapName
}
struct Capabilities: Decodable { let modules: [CapModule] }

let (data, _) = try await URLSession.shared.data(for: req)
let caps = try JSONDecoder().decode(Capabilities.self, from: data)
let menu = caps.modules.filter { $0.canRead }
// menu.forEach { print($0.name.es, $0.entitySet) }

Google Sign-In móvil

Intercambia el id_token de Google Sign-In por JWT Comunidesk.

Host: gateway.comunidesk.com (no comunidesk.com). Body JSON con id_token. Si el usuario ya tiene cuenta Comunidesk con el mismo email, se vincula Google y se conservan edificios y permisos (isNewUser: false).

POST https://gateway.comunidesk.com/api/oauth/google/mobile

import Foundation

// id_token from Google Sign-In (iOS)
let idToken = googleUser.idToken?.tokenString ?? ""
var req = URLRequest(url: URL(string: "https://gateway.comunidesk.com/api/oauth/google/mobile")!)
req.httpMethod = "POST"
req.setValue("application/json", forHTTPHeaderField: "Content-Type")
req.httpBody = try JSONEncoder().encode(["id_token": idToken])

struct AuthResponse: Decodable {
  let success: Bool
  let isNewUser: Bool?
  let access_token: String?
}

let (data, response) = try await URLSession.shared.data(for: req)
let auth = try JSONDecoder().decode(AuthResponse.self, from: data)
// auth.access_token → JWT users_app; auth.isNewUser == false si ya tenía cuenta

Paridad web ↔ API

GET /v1/me/capabilities incluye webParity

Cada módulo REST expone webParity.status (full|partial|missing|web_only). El objeto webParity resume brechas, rutas IA mapeadas y rutas Flex Pro. OpenAPI completo en /v1/openapi/full.json; catálogo de paridad en /v1/openapi/parity.json.

GET https://gateway.comunidesk.com/v1/me/capabilities
GET https://gateway.comunidesk.com/v1/openapi/full.json
GET https://gateway.comunidesk.com/v1/openapi/parity.json

Flex Pro

Runtime y marketplace vía /v1/flex-pro/*

Los flujos Flex Pro no tienen EntitySet REST único. El gateway proxea /api/flex-pro/* de comunidesk.com. Scopes: flex-pro:manage (módulos, sources, install), flex-pro:runtime (active, bundle), flex-pro:marketplace (publish, install, installs).

GET https://gateway.comunidesk.com/v1/flex-pro/runtime/active
POST https://gateway.comunidesk.com/v1/flex-pro/marketplace/install

Catálogo de specs

OpenAPI completo y por módulo (JSON/YAML). WSDL SOAP completo y por módulo (XML).

• OpenAPI JSON
• OpenAPI YAML
• Índice OpenAPI
• SOAP WSDL
• /v1/soap?wsdl

Módulos

Módulos y productos del gateway.

Lab y Shell

El Lab y el Comunidesk Shell permiten probar el gateway contra entornos controlados.

• Lab — colecciones, variables y entornos.
• Abre el Shell con el icono Terminal del header: help, env, whoami, get.