Saltearse al contenido
Celestín

Tenants (Multi-sociedad)

Celestín está diseñado para gestionar múltiples organizaciones desde una única integración. El modelo es partner → tenants: tú eres el partner, cada una de tus sociedades o clientes es un tenant.

Relación partner / tenant

Un partner es la cuenta raíz que posee las API keys. Un tenant representa una organización independiente: una sociedad mercantil, una delegación, un cliente final si desarrollas un SaaS sobre Celestín.

Todos los recursos de Celestín (conciliaciones, memoria de matching, configuración BYOK, cuotas) están aislados por tenant. Una conciliación de sociedad-a-sl nunca mezcla ni accede a datos de sociedad-b-sa.

La relación es 1:N — un partner puede tener decenas o miles de tenants.

Identificación del tenant en cada petición

Incluye el header X-Celestin-Tenant en todas las peticiones que operan sobre datos de un tenant específico:

POST /v1/reconciliations
Authorization: Bearer sk_live_xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx
X-Celestin-Tenant: sociedad-a-sl
Content-Type: application/json

Si el header falta en un endpoint que lo requiere, la API devuelve 400 con código missing_tenant_header.

El SDK lo gestiona automáticamente cuando inicializas el cliente con tenantId:

const client = new CelestinClient({
  apiKey: process.env.CELESTIN_API_KEY!,
  tenantId: "sociedad-a-sl",   // aplicado a todas las peticiones
});

external_id — tu referencia interna

Cada tenant tiene un campo external_id libre que puedes usar para mapear el tenant de Celestín a tu propio sistema (ERP, CRM, base de datos):

{
  "id": "ten_01HXYZ456DEF",
  "external_id": "ERP-EMPRESA-4712",
  "name": "Sociedad A, S.L.",
  "status": "active",
  "created_at": "2026-01-15T08:00:00Z"
}

El external_id es único dentro del partner y puede usarse como selector alternativo en algunos endpoints: GET /v1/tenants/by-external-id/{external_id}.

Recursos con alcance por tenant

RecursoAlcance
Conciliacionestenant
Memoria de matching (L5)tenant
Configuración BYOK / clave maestratenant
Cuota mensual de jobstenant
Webhookspartner (pueden filtrarse por tenant)
API keyspartner

El aislamiento es estricto a nivel de base de datos: no existe ninguna consulta cross-tenant.

Ciclo de vida del tenant

active → suspended → soft_deleted → purged

active

Estado normal de operación. Acepta peticiones, consume cuota, puede crear conciliaciones.

suspended

El partner ha pausado el tenant (por ejemplo, impago o revisión de cuenta). La API devuelve 403 con código tenant_suspended en todos los endpoints que crean recursos. Los endpoints de lectura (GET) siguen funcionando.

soft_deleted

El tenant ha sido marcado para borrado. Los datos se conservan durante 30 días para cumplir con el derecho de rectificación del RGPD. Durante este período la cuenta no acepta nuevas operaciones pero los datos son recuperables por soporte.

purged

Pasados los 30 días de soft-delete, todos los datos del tenant se eliminan de forma permanente e irrecuperable. Este es el estado final — no existe transición inversa.

Crear un tenant

POST /v1/tenants
Authorization: Bearer sk_live_...
Content-Type: application/json


{
  "external_id": "ERP-EMPRESA-4712",
  "name": "Sociedad A, S.L.",
  "metadata": {
    "country": "ES",
    "vat_id": "B12345678"
  }
}

La respuesta incluye el id del tenant (prefijo ten_) que usarás en el header X-Celestin-Tenant.

Cuotas y límites

Cada tenant tiene una cuota mensual de jobs de conciliación independiente. Si un tenant supera su cuota, las nuevas peticiones devuelven 429 con código monthly_job_cap_exceeded. El conteo se reinicia el primer día de cada mes UTC.

Los límites por plan están documentados en la página de precios. Para aumentar la cuota de un tenant específico, usa PATCH /v1/tenants/{id} con quota_override o contacta con soporte.