Flags

Gerenciamento de feature flags.

Endpoints

Método	Endpoint	Descrição	Permissão
POST	`/api/v1/feature-flags`	Criar flag	`FEATURE_FLAGS_CREATE`
GET	`/api/v1/feature-flags`	Listar flags	`FEATURE_FLAGS_READ`
GET	`/api/v1/feature-flags/:id`	Obter flag	`FEATURE_FLAGS_READ`
PATCH	`/api/v1/feature-flags/:id`	Atualizar flag	`FEATURE_FLAGS_UPDATE`
POST	`/api/v1/feature-flags/:id/enable`	Ativar flag	`FEATURE_FLAGS_TOGGLE`
POST	`/api/v1/feature-flags/:id/disable`	Desativar flag	`FEATURE_FLAGS_TOGGLE`
DELETE	`/api/v1/feature-flags/:id`	Excluir flag	`FEATURE_FLAGS_DELETE`

Atributos

Campo	Tipo	Obrigatório	Descrição
`key`	string	Sim	Identificador único da flag (alfanumerico, hifens, underscores)
`name`	string	Sim	Nome de exibicao da flag (max 200 caracteres)
`description`	string	Não	Descrição da flag (max 1000 caracteres)
`status`	enum	Não	Status da flag: `ENABLED` ou `DISABLED` (default: `DISABLED`)
`variations`	array	Sim	Lista de variações (mínimo 1)
`variations[].key`	string	Sim	Identificador da variação
`variations[].value`	any	Sim	Valor da variação (boolean, string, number, object, array)
`defaultVariation`	string	Sim	Key da variação padrão

Criar Flag

POST /api/v1/feature-flags

Cria uma nova feature flag.

Request

cURL
JavaScript

curl -X POST 'https://feature-flags.stg.catalisa.app/api/v1/feature-flags' \
  -H 'Authorization: Bearer SEU_TOKEN' \
  -H 'Content-Type: application/json' \
  -d '{
    "key": "new-checkout-flow",
    "name": "New Checkout Flow",
    "description": "Novo fluxo de checkout com PIX",
    "variations": [
      { "key": "on", "value": true },
      { "key": "off", "value": false }
    ],
    "defaultVariation": "off"
  }'

const response = await fetch('https://feature-flags.stg.catalisa.app/api/v1/feature-flags', {
  method: 'POST',
  headers: {
    'Authorization': `Bearer ${token}`,
    'Content-Type': 'application/json',
  },
  body: JSON.stringify({
    key: 'new-checkout-flow',
    name: 'New Checkout Flow',
    description: 'Novo fluxo de checkout com PIX',
    variations: [
      { key: 'on', value: true },
      { key: 'off', value: false },
    ],
    defaultVariation: 'off',
  }),
});

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

Response (201 Created)

{
  "data": {
    "type": "feature-flags",
    "id": "550e8400-e29b-41d4-a716-446655440000",
    "attributes": {
      "key": "new-checkout-flow",
      "name": "New Checkout Flow",
      "description": "Novo fluxo de checkout com PIX",
      "status": "DISABLED",
      "variations": [
        { "key": "on", "value": true },
        { "key": "off", "value": false }
      ],
      "defaultVariation": "off",
      "createdAt": "2024-01-15T10:30:00Z",
      "updatedAt": "2024-01-15T10:30:00Z"
    },
    "links": {
      "self": "/api/v1/feature-flags/550e8400-e29b-41d4-a716-446655440000"
    }
  }
}

Listar Flags

GET /api/v1/feature-flags

Lista feature flags com suporte a paginação e filtros.

Query Parameters

Parâmetro	Tipo	Descrição
`page[number]`	integer	Número da pagina
`page[size]`	integer	Itens por pagina (max 100)
`filter[status]`	enum	Filtrar por status (`ENABLED` ou `DISABLED`)

cURL
JavaScript

curl 'https://feature-flags.stg.catalisa.app/api/v1/feature-flags?filter[status]=ENABLED' \
  -H 'Authorization: Bearer SEU_TOKEN'

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

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

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

Response (200 OK)

{
  "data": [
    {
      "type": "feature-flags",
      "id": "550e8400-e29b-41d4-a716-446655440000",
      "attributes": {
        "key": "new-checkout-flow",
        "name": "New Checkout Flow",
        "status": "ENABLED",
        "variations": [
          { "key": "on", "value": true },
          { "key": "off", "value": false }
        ],
        "defaultVariation": "off"
      }
    }
  ],
  "meta": {
    "totalItems": 1,
    "totalPages": 1,
    "currentPage": 1
  },
  "links": {
    "self": "/api/v1/feature-flags?page[number]=1&page[size]=20"
  }
}

Obter Flag

GET /api/v1/feature-flags/:id

Obtém detalhes de uma feature flag específica.

cURL
JavaScript

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

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

const response = await fetch(`https://feature-flags.stg.catalisa.app/api/v1/feature-flags/${id}`, {
  headers: {
    'Authorization': `Bearer ${token}`,
  },
});

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

Response (200 OK)

{
  "data": {
    "type": "feature-flags",
    "id": "550e8400-e29b-41d4-a716-446655440000",
    "attributes": {
      "key": "new-checkout-flow",
      "name": "New Checkout Flow",
      "description": "Novo fluxo de checkout com PIX",
      "status": "ENABLED",
      "variations": [
        { "key": "on", "value": true },
        { "key": "off", "value": false }
      ],
      "defaultVariation": "off",
      "createdAt": "2024-01-15T10:30:00Z",
      "updatedAt": "2024-01-15T10:30:00Z"
    },
    "links": {
      "self": "/api/v1/feature-flags/550e8400-e29b-41d4-a716-446655440000"
    }
  }
}

Atualizar Flag

PATCH /api/v1/feature-flags/:id

Atualiza uma feature flag existente.

cURL
JavaScript

curl -X PATCH 'https://feature-flags.stg.catalisa.app/api/v1/feature-flags/550e8400-e29b-41d4-a716-446655440000' \
  -H 'Authorization: Bearer SEU_TOKEN' \
  -H 'Content-Type: application/json' \
  -d '{
    "name": "New Checkout Flow v2",
    "description": "Novo fluxo de checkout com PIX e cartao"
  }'

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

const response = await fetch(`https://feature-flags.stg.catalisa.app/api/v1/feature-flags/${id}`, {
  method: 'PATCH',
  headers: {
    'Authorization': `Bearer ${token}`,
    'Content-Type': 'application/json',
  },
  body: JSON.stringify({
    name: 'New Checkout Flow v2',
    description: 'Novo fluxo de checkout com PIX e cartao',
  }),
});

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

Response (200 OK)

{
  "data": {
    "type": "feature-flags",
    "id": "550e8400-e29b-41d4-a716-446655440000",
    "attributes": {
      "key": "new-checkout-flow",
      "name": "New Checkout Flow v2",
      "description": "Novo fluxo de checkout com PIX e cartao",
      "status": "ENABLED",
      "updatedAt": "2024-01-15T11:00:00Z"
    }
  }
}

Ativar Flag

POST /api/v1/feature-flags/:id/enable

Ativa uma feature flag.

cURL
JavaScript

curl -X POST 'https://feature-flags.stg.catalisa.app/api/v1/feature-flags/550e8400-e29b-41d4-a716-446655440000/enable' \
  -H 'Authorization: Bearer SEU_TOKEN'

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

const response = await fetch(`https://feature-flags.stg.catalisa.app/api/v1/feature-flags/${id}/enable`, {
  method: 'POST',
  headers: {
    'Authorization': `Bearer ${token}`,
  },
});

const { data } = await response.json();
console.log(data.attributes.status); // "ENABLED"

Response (200 OK)

{
  "data": {
    "type": "feature-flags",
    "id": "550e8400-e29b-41d4-a716-446655440000",
    "attributes": {
      "key": "new-checkout-flow",
      "status": "ENABLED",
      "updatedAt": "2024-01-15T11:00:00Z"
    }
  }
}

Desativar Flag

POST /api/v1/feature-flags/:id/disable

Desativa uma feature flag. Quando desativada, a flag sempre retorna a variação padrão.

cURL
JavaScript

curl -X POST 'https://feature-flags.stg.catalisa.app/api/v1/feature-flags/550e8400-e29b-41d4-a716-446655440000/disable' \
  -H 'Authorization: Bearer SEU_TOKEN'

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

const response = await fetch(`https://feature-flags.stg.catalisa.app/api/v1/feature-flags/${id}/disable`, {
  method: 'POST',
  headers: {
    'Authorization': `Bearer ${token}`,
  },
});

const { data } = await response.json();
console.log(data.attributes.status); // "DISABLED"

Response (200 OK)

{
  "data": {
    "type": "feature-flags",
    "id": "550e8400-e29b-41d4-a716-446655440000",
    "attributes": {
      "key": "new-checkout-flow",
      "status": "DISABLED",
      "updatedAt": "2024-01-15T11:00:00Z"
    }
  }
}

Excluir Flag

DELETE /api/v1/feature-flags/:id

Remove uma feature flag e todos os seus targeting rules e overrides.

cURL
JavaScript

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

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

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

// Status 204 No Content = sucesso

Response (204 No Content)

Sem corpo de resposta.

Exemplos de Variações

Flag Boolean

{
  "key": "dark-mode",
  "name": "Dark Mode",
  "variations": [
    { "key": "on", "value": true },
    { "key": "off", "value": false }
  ],
  "defaultVariation": "off"
}

Flag String

{
  "key": "checkout-button-color",
  "name": "Checkout Button Color",
  "variations": [
    { "key": "green", "value": "#00FF00" },
    { "key": "blue", "value": "#0000FF" },
    { "key": "red", "value": "#FF0000" }
  ],
  "defaultVariation": "green"
}

Flag JSON

{
  "key": "pricing-config",
  "name": "Pricing Configuration",
  "variations": [
    {
      "key": "standard",
      "value": {
        "discount": 0,
        "freeShipping": false
      }
    },
    {
      "key": "premium",
      "value": {
        "discount": 0.15,
        "freeShipping": true
      }
    }
  ],
  "defaultVariation": "standard"
}

Erros Comuns

Código	Erro	Descrição
400	`VALIDATION`	Campos obrigatorios ausentes ou inválidos
404	`NOT_FOUND`	Feature flag nao encontrada
409	`CONFLICT`	Flag com mesma key ja existe na organização

Endpoints​

Atributos​

Criar Flag​

Request​

Response (201 Created)​

Listar Flags​

Query Parameters​

Response (200 OK)​

Obter Flag​

Response (200 OK)​

Atualizar Flag​

Response (200 OK)​

Ativar Flag​

Response (200 OK)​

Desativar Flag​

Response (200 OK)​

Excluir Flag​

Response (204 No Content)​

Exemplos de Variações​

Flag Boolean​

Flag String​

Flag JSON​

Erros Comuns​

Endpoints

Atributos

Criar Flag

Request

Response (201 Created)

Listar Flags

Query Parameters

Response (200 OK)

Obter Flag

Response (200 OK)

Atualizar Flag

Response (200 OK)

Ativar Flag

Response (200 OK)

Desativar Flag

Response (200 OK)

Excluir Flag

Response (204 No Content)

Exemplos de Variações

Flag Boolean

Flag String

Flag JSON

Erros Comuns