API: Tenants¶

Visão Geral¶

Gerenciamento de tenants (empresas/organizações). Apenas SuperAdmins têm acesso a estes endpoints.

Endpoints¶

GET /api/tenants¶

Lista todos os tenants.

Autorização: SuperAdmin

Response (200 OK):

[
  {
    "id": "550e8400-e29b-41d4-a716-446655440000",
    "name": "Empresa XYZ",
    "isActive": true,
    "userCount": 3,
    "agentCount": 2,
    "createdAt": "2024-01-15T10:00:00Z",
    "subscriptionStatus": "Active",
    "creditBalance": 450,
    "instances": 1,
    "currentPeriodStart": "2024-01-01T00:00:00Z",
    "currentPeriodEnd": "2024-02-01T00:00:00Z",
    "pastDueAt": null,
    "suspendedAt": null,
    "cancelledAt": null
  }
]

GET /api/tenants/{id}¶

Retorna detalhes de um tenant.

Autorização: SuperAdmin

Response (200 OK):

{
  "id": "550e8400-e29b-41d4-a716-446655440000",
  "name": "Empresa XYZ",
  "isActive": true,
  "createdAt": "2024-01-15T10:00:00Z",
  "updatedAt": "2024-01-15T10:00:00Z",
  "subscriptionStatus": "Active",
  "creditBalance": 450,
  "currentPeriodStart": "2024-01-01T00:00:00Z",
  "currentPeriodEnd": "2024-02-01T00:00:00Z",
  "pastDueAt": null,
  "suspendedAt": null,
  "cancelledAt": null
}

POST /api/tenants¶

Cria um novo tenant.

Autorização: SuperAdmin

Request:

{
  "name": "Empresa XYZ"
}

Response (201 Created):

{
  "id": "550e8400-e29b-41d4-a716-446655440000",
  "name": "Empresa XYZ"
}

PUT /api/tenants/{id}¶

Atualiza um tenant.

Autorização: SuperAdmin

Request:

{
  "name": "Empresa XYZ Ltda",
  "isActive": true
}

GET /api/tenants/{tenantId}/subscription-history¶

Retorna o histórico de eventos da assinatura de um tenant.

Autorização: SuperAdmin

Response (200 OK):

{
  "events": [
    {
      "type": "Created",
      "fromStatus": null,
      "toStatus": "Active",
      "description": "Assinatura criada",
      "createdAt": "2024-01-15T10:00:00Z"
    },
    {
      "type": "CreditsAdded",
      "fromStatus": null,
      "toStatus": null,
      "description": "Franquia mensal: +500 créditos",
      "createdAt": "2024-02-01T00:00:00Z"
    }
  ]
}

Tipos de evento:

Tipo	Descrição
Created	Assinatura criada
ConfigurationUpdated	Limites ou pacote alterados
CreditsAdded	Créditos adicionados (renovação ou compra)
AiQuotaExhausted	Créditos esgotados
MarkedPastDue	Marcado como inadimplente
Suspended	Assinatura suspensa
Cancelled	Assinatura cancelada
Reactivated	Assinatura reativada
PeriodRenewed	Período renovado

GET /api/tenants/{tenantId}/subscription-details¶

Retorna detalhes completos da assinatura de um tenant, incluindo uso atual de recursos e limites.

Autorização: SuperAdmin

Response (200 OK):

{
  "status": "Active",
  "currentPeriodStart": "2024-01-01T00:00:00Z",
  "currentPeriodEnd": "2024-02-01T00:00:00Z",
  "creditBalance": 450,
  "monthlyCreditPackage": 500,
  "monthlyPriceBrl": 199.90,
  "instances": 1,
  "freeAgentCount": 1,
  "extraAgents": 0,
  "extraUsers": 0,
  "extraKbBlocks": 0,
  "extraStepBlocks": 0,
  "extraAttachmentBlocks": 0,
  "extraFaqBlocks": 0,
  "agents": { "current": 2, "max": 3 },
  "users": { "current": 3, "max": 5 },
  "instanceUsage": { "current": 1, "max": 1 },
  "knowledgeDocs": { "current": 8, "max": 20 },
  "steps": { "current": 5, "max": 15 },
  "faqs": { "current": 12, "max": 50 },
  "storage": { "usedBytes": 1048576, "maxBytes": 104857600 }
}

GET /api/admin/tenants/search¶

Busca tenants por nome. Endpoint separado do CRUD de tenants, sob o grupo de administração.

Autorização: SuperAdmin

Rate Limiting: SuperAdmin (20 req/60s)

Query Parameters:

Parâmetro	Tipo	Obrigatório	Descrição
q	string	Sim	Termo de busca (nome do tenant)

Response (200 OK):

[
  {
    "id": "550e8400-e29b-41d4-a716-446655440000",
    "name": "Empresa XYZ"
  }
]

Validações¶

Campo	Regra
Name	Obrigatório, máx 100 caracteres

Multi-tenancy¶

O sistema implementa isolamento de dados por tenant:

Query Filters: Todas as entidades com TenantId são filtradas automaticamente
JWT: Token contém tenant_id claim
TenantProvider: Extrai TenantId do token para cada request

SuperAdmin¶

TenantId = null no JWT
Acesso a todos os tenants
Pode gerenciar tenants, usuários globais, configurações do sistema

Erros Comuns¶

Status	Código	Descrição
404	TENANT_NOT_FOUND	Tenant não encontrado
403	FORBIDDEN	Usuário não é SuperAdmin