Skip to main content

Especificación OpenAPI Core (estado actual)

2026-08 — cierre Core+CMS. Backend canónico Go :3001 / api.saascol.localhost.
Auth: Authorization: Bearer <JWT Keycloak> o test key fuera de producción.

Envelopes:

  • BFF dominio: { "status", "data", "message", "error" }
  • UAP data: JSend { "status", "data": { "items", "pagination" } }

Health​

  • GET /api/v1/health
  • GET /api/v1/ready

Admin / Tenants​

  • POST /api/v1/admin/tenants
  • GET /api/v1/admin/tenants/{id}
  • POST /api/v1/admin/tenants/provision — wizard (domains, nav, branding, seed Healthcare)

Metadata & Data (UAP)​

  • POST /api/v1/metadata/schemas
  • GET /api/v1/metadata/schemas
  • POST /api/v1/data/{namespace}/{schema}
  • GET /api/v1/data/{namespace}/{schema}

Namespaces tipados: cms.*, crm.deal, erp.invoice, …

Headless CMS (auth)​

  • GET /api/v1/tenant/{tenantId}/content/{contentType}
  • POST /api/v1/tenant/{tenantId}/content/{contentType}

Site config / branding / features​

  • GET|PATCH /api/v1/tenants/{id}/site-config
  • PUT /api/v1/tenants/{id}/domains
  • GET|PATCH /api/v1/tenants/{id}/branding
  • GET|PATCH /api/v1/tenants/{id}/licensed-modules
  • GET|PATCH /api/v1/tenants/{id}/features — custom_domain → 402 si falta; PATCH solo superadmin
  • GET /api/v1/tenants/{id}/members — miembros (Keycloak o memoria local)
  • POST /api/v1/tenants/{id}/invitations — { email, role } + mail SMTP plataforma

Platform settings (solo superadmin)​

  • GET|PATCH /api/v1/platform/settings — SMTP_*, FRONTEND_URL, INVITE_LOGIN_URL (password enmascarado en GET)
  • POST /api/v1/platform/settings/smtp/test — { to? }

Eventos: platform.settings.updated, tenant.modules.updated, tenant.member.invited.

Public Site Runtime (sin auth)​

  • GET /api/v1/public/resolve-host?host=
  • GET /api/v1/public/tenant/{tenantId}/content/{contentType}
  • POST /api/v1/public/tenant/{tenantId}/forms/{formId}/submit
  • GET /api/v1/public/tenant/{tenantId}/knowledge
  • GET /api/v1/public/assets/{tenantId}/{path…}

CMS pages & import​

  • GET /api/v1/cms/pages
  • GET|PATCH /api/v1/cms/pages/{pageId}
  • POST /api/v1/cms/import-url — flags: depth, use_ai, dry_run, apply_suggestions, apply_navigation, apply_branding, publish
  • POST /api/v1/ai/ingest-web — HTML → knowledge (sin LLM obligatorio)
  • POST /api/v1/migration/competitor-import — sourcePlatform=website + url

Storage (mediador)​

  • GET /api/v1/storage/presigned-upload
  • GET /api/v1/storage/signed-url
  • POST /api/v1/storage/objects — headers X-SaaSCol-Product, X-SaaSCol-Collection, X-SaaSCol-Filename

Keys: tenants/{tenant}/products/{product}/{collection}/…

CRM (handoff)​

  • GET /api/v1/crm/deals
  • POST /api/v1/crm/deals
  • PATCH /api/v1/crm/deals/{dealId}

ERP (parcial)​

  • GET /api/v1/erp/invoices

Eventos​

  • POST /api/v1/events/publish — body { "event", "payload", "product?" }

Firma outbound: X-SaaSCol-Signature (HMAC-SHA256). Envelope incluye product.

Orgs​

  • GET /api/v1/organizations