Organizações

Gerenciamento de organizações (tenants) na Catalisa Platform.

Endpoints

Método	Endpoint	Descrição	Permissão
POST	`/api/v1/organizations`	Criar organização	`IAM_ORGANIZATIONS_CREATE`
GET	`/api/v1/organizations`	Listar organizações	`IAM_ORGANIZATIONS_READ`
GET	`/api/v1/organizations/:id`	Obter organização	`IAM_ORGANIZATIONS_READ`
PATCH	`/api/v1/organizations/:id`	Atualizar organização	`IAM_ORGANIZATIONS_UPDATE`
DELETE	`/api/v1/organizations/:id`	Excluir organização	`IAM_ORGANIZATIONS_DELETE`
POST	`/api/v1/organizations/:id/client-secret`	Definir client secret	`IAM_ORGANIZATIONS_UPDATE`

Tipos de Organização

Tipo	Valor	Descrição
Cliente	`cliente`	Organização cliente final
Parceiro	`parceiro`	Organização parceira
Dono	`dono`	Organização proprietária da plataforma

Status de Organização

Status	Valor	Descrição
Ativo	`ativo`	Organização ativa e operacional
Inativo	`inativo`	Organização desativada
Suspensó	`suspenso`	Organização temporariamente suspensa

Criar Organização

POST /api/v1/organizations

Cria uma nova organização no sistema.

Request

Campo	Tipo	Obrigatório	Descrição
`name`	string	Sim	Nome da organização
`slug`	string	Não	Slug único (gerado automaticamente se não informado)
`type`	string	Sim	Tipo: `cliente`, `parceiro` ou `dono`
`status`	string	Não	Status inicial (default: `ativo`)
`metadata`	object	Não	Metadados adicionais

cURL
JavaScript

curl -X POST 'https://iam.stg.catalisa.app/api/v1/organizations' \
  -H 'Authorization: Bearer SEU_TOKEN' \
  -H 'Content-Type: application/json' \
  -d '{
    "name": "Empresa ABC",
    "slug": "empresa-abc",
    "type": "cliente",
    "metadata": {
      "cnpj": "12.345.678/0001-90",
      "segment": "fintech"
    }
  }'

const response = await fetch('https://iam.stg.catalisa.app/api/v1/organizations', {
  method: 'POST',
  headers: {
    'Authorization': `Bearer ${token}`,
    'Content-Type': 'application/json',
  },
  body: JSON.stringify({
    name: 'Empresa ABC',
    slug: 'empresa-abc',
    type: 'cliente',
    metadata: {
      cnpj: '12.345.678/0001-90',
      segment: 'fintech',
    },
  }),
});

const org = await response.json();

Response (201 Created)

{
  "data": {
    "type": "organizations",
    "id": "550e8400-e29b-41d4-a716-446655440000",
    "attributes": {
      "name": "Empresa ABC",
      "slug": "empresa-abc",
      "type": "cliente",
      "status": "ativo",
      "hasClientSecret": false,
      "metadata": {
        "cnpj": "12.345.678/0001-90",
        "segment": "fintech"
      },
      "createdAt": "2024-01-15T10:30:00Z",
      "updatedAt": "2024-01-15T10:30:00Z"
    },
    "links": {
      "self": "/api/v1/organizations/550e8400-e29b-41d4-a716-446655440000"
    }
  }
}

Listar Organizações

GET /api/v1/organizations

Lista organizacoes com suporte a paginação e filtros.

Query Parameters

Parâmetro	Tipo	Descrição
`page[number]`	integer	Número da página
`page[size]`	integer	Itens por página
`filter[type]`	string	Filtrar por tipo
`filter[status]`	string	Filtrar por status
`filter[name]`	string	Filtrar por nome (parcial)

cURL
JavaScript

curl 'https://iam.stg.catalisa.app/api/v1/organizations?filter[type]=cliente&filter[status]=ativo' \
  -H 'Authorization: Bearer SEU_TOKEN'

const params = new URLSearchParams({
  'filter[type]': 'cliente',
  'filter[status]': 'ativo',
});

const response = await fetch(`https://iam.stg.catalisa.app/api/v1/organizations?${params}`, {
  headers: {
    'Authorization': `Bearer ${token}`,
  },
});

const { data, meta } = await response.json();

Response (200 OK)

{
  "data": [
    {
      "type": "organizations",
      "id": "550e8400-e29b-41d4-a716-446655440000",
      "attributes": {
        "name": "Empresa ABC",
        "slug": "empresa-abc",
        "type": "cliente",
        "status": "ativo",
        "hasClientSecret": true
      }
    }
  ],
  "meta": {
    "totalItems": 25,
    "totalPages": 2,
    "currentPage": 1
  }
}

Obter Organização

GET /api/v1/organizations/:organizationId

Obtém detalhes de uma organização específica.

cURL
JavaScript

curl 'https://iam.stg.catalisa.app/api/v1/organizations/550e8400-e29b-41d4-a716-446655440000' \
  -H 'Authorization: Bearer SEU_TOKEN'

const orgId = '550e8400-e29b-41d4-a716-446655440000';

const response = await fetch(`https://iam.stg.catalisa.app/api/v1/organizations/${orgId}`, {
  headers: {
    'Authorization': `Bearer ${token}`,
  },
});

const org = await response.json();

Response (200 OK)

{
  "data": {
    "type": "organizations",
    "id": "550e8400-e29b-41d4-a716-446655440000",
    "attributes": {
      "name": "Empresa ABC",
      "slug": "empresa-abc",
      "type": "cliente",
      "status": "ativo",
      "hasClientSecret": true,
      "metadata": {
        "cnpj": "12.345.678/0001-90"
      },
      "createdAt": "2024-01-15T10:30:00Z",
      "updatedAt": "2024-01-15T10:30:00Z"
    },
    "links": {
      "self": "/api/v1/organizations/550e8400-e29b-41d4-a716-446655440000"
    }
  }
}

Atualizar Organização

PATCH /api/v1/organizations/:organizationId

Atualiza dados de uma organização.

Request

Campo	Tipo	Obrigatório	Descrição
`name`	string	Não	Novo nome
`type`	string	Não	Novo tipo
`status`	string	Não	Novo status
`metadata`	object	Não	Novos metadados

cURL
JavaScript

curl -X PATCH 'https://iam.stg.catalisa.app/api/v1/organizations/550e8400-e29b-41d4-a716-446655440000' \
  -H 'Authorization: Bearer SEU_TOKEN' \
  -H 'Content-Type: application/json' \
  -d '{
    "name": "Empresa ABC Ltda",
    "status": "suspenso"
  }'

const orgId = '550e8400-e29b-41d4-a716-446655440000';

const response = await fetch(`https://iam.stg.catalisa.app/api/v1/organizations/${orgId}`, {
  method: 'PATCH',
  headers: {
    'Authorization': `Bearer ${token}`,
    'Content-Type': 'application/json',
  },
  body: JSON.stringify({
    name: 'Empresa ABC Ltda',
    status: 'suspenso',
  }),
});

const org = await response.json();

Response (200 OK)

{
  "data": {
    "type": "organizations",
    "id": "550e8400-e29b-41d4-a716-446655440000",
    "attributes": {
      "name": "Empresa ABC Ltda",
      "slug": "empresa-abc",
      "type": "cliente",
      "status": "suspenso",
      "updatedAt": "2024-01-15T11:00:00Z"
    }
  }
}

Excluir Organização

DELETE /api/v1/organizations/:organizationId

Remove uma organização do sistema.

Atenção

Esta operação é irreversível. Todos os dados associados a organização serão removidos.

cURL
JavaScript

curl -X DELETE 'https://iam.stg.catalisa.app/api/v1/organizations/550e8400-e29b-41d4-a716-446655440000' \
  -H 'Authorization: Bearer SEU_TOKEN'

const orgId = '550e8400-e29b-41d4-a716-446655440000';

const response = await fetch(`https://iam.stg.catalisa.app/api/v1/organizations/${orgId}`, {
  method: 'DELETE',
  headers: {
    'Authorization': `Bearer ${token}`,
  },
});

// Status 204 No Content = sucesso

Response (204 No Content)

Sem corpo de resposta.

Definir Client Secret

POST /api/v1/organizations/:organizationId/client-secret

Define o client secret para autenticação via OAuth Client Credentials.

Importante

O client secret só pode ser definido uma vez
Apos definido, não pode ser recuperado
Guarde o secret em local seguro imediatamente

Request

Campo	Tipo	Obrigatório	Descrição
`clientSecret`	string	Sim	Secret a ser definido (mínimo 32 caracteres)

cURL
JavaScript

curl -X POST 'https://iam.stg.catalisa.app/api/v1/organizations/550e8400-e29b-41d4-a716-446655440000/client-secret' \
  -H 'Authorization: Bearer SEU_TOKEN' \
  -H 'Content-Type: application/json' \
  -d '{
    "clientSecret": "minha-chave-secreta-muito-segura-123456"
  }'

const orgId = '550e8400-e29b-41d4-a716-446655440000';

const response = await fetch(
  `https://iam.stg.catalisa.app/api/v1/organizations/${orgId}/client-secret`,
  {
    method: 'POST',
    headers: {
      'Authorization': `Bearer ${token}`,
      'Content-Type': 'application/json',
    },
    body: JSON.stringify({
      clientSecret: 'minha-chave-secreta-muito-segura-123456',
    }),
  }
);

const result = await response.json();

Response (200 OK)

{
  "success": true,
  "message": "Client secret set successfully"
}

Erros Comuns

Código	Erro	Descrição
400	`VALIDATION`	Campos obrigatórios ausentes ou inválidos
404	`NOT_FOUND`	Organização não encontrada
409	`CONFLICT`	Slug já existe
409	`CONFLICT`	Client secret já definido

Endpoints​

Tipos de Organização​

Status de Organização​

Criar Organização​

Request​

Response (201 Created)​

Listar Organizações​

Query Parameters​

Response (200 OK)​

Obter Organização​

Response (200 OK)​

Atualizar Organização​

Request​

Response (200 OK)​

Excluir Organização​

Response (204 No Content)​

Definir Client Secret​

Request​

Response (200 OK)​

Erros Comuns​

Endpoints

Tipos de Organização

Status de Organização

Criar Organização

Request

Response (201 Created)

Listar Organizações

Query Parameters

Response (200 OK)

Obter Organização

Response (200 OK)

Atualizar Organização

Request

Response (200 OK)

Excluir Organização

Response (204 No Content)

Definir Client Secret

Request

Response (200 OK)

Erros Comuns