Risk Bands

Gerenciamento de faixas de risco baseadas em score de credito.

Endpoints

Método	Endpoint	Descrição	Permissão
POST	`/api/v1/risk-bands`	Criar risk band	`PRICING_RISK_BANDS_CREATE`
GET	`/api/v1/risk-bands`	Listar risk bands	`PRICING_RISK_BANDS_READ`
GET	`/api/v1/risk-bands/:id`	Obter risk band	`PRICING_RISK_BANDS_READ`
PATCH	`/api/v1/risk-bands/:id`	Atualizar risk band	`PRICING_RISK_BANDS_UPDATE`
DELETE	`/api/v1/risk-bands/:id`	Excluir risk band	`PRICING_RISK_BANDS_DELETE`

Atributos

Campo	Tipo	Obrigatório	Descrição
`productId`	string (UUID)	Sim	ID do produto associado
`name`	string	Sim	Nome da faixa (ex: LOW_RISK, HIGH_RISK)
`displayLabel`	string	Não	Label para exibicao
`minScore`	integer	Sim	Score mínimo (0-1000)
`maxScore`	integer	Sim	Score máximo (0-1000)
`baseRate`	number	Sim	Taxa base mensal (0-1, ex: 0.0199 = 1.99%)
`maxRate`	number	Não	Taxa maxima
`rateSpread`	number	Não	Spread sobre a taxa base (-1 a 1)
`priority`	integer	Não	Prioridade para ordenacao
`isActive`	boolean	Não	Se a faixa esta ativa

Criar Risk Band

POST /api/v1/risk-bands

Cria uma nova faixa de risco.

Request

cURL
JavaScript

curl -X POST 'https://pricing.stg.catalisa.app/api/v1/risk-bands' \
  -H 'Authorization: Bearer SEU_TOKEN' \
  -H 'Content-Type: application/json' \
  -d '{
    "data": {
      "type": "risk-bands",
      "attributes": {
        "productId": "550e8400-e29b-41d4-a716-446655440000",
        "name": "LOW_RISK",
        "displayLabel": "Baixo Risco",
        "minScore": 700,
        "maxScore": 850,
        "baseRate": 0.0199,
        "rateSpread": 0.005,
        "priority": 1,
        "isActive": true
      }
    }
  }'

const response = await fetch('https://pricing.stg.catalisa.app/api/v1/risk-bands', {
  method: 'POST',
  headers: {
    'Authorization': `Bearer ${token}`,
    'Content-Type': 'application/json',
  },
  body: JSON.stringify({
    data: {
      type: 'risk-bands',
      attributes: {
        productId: '550e8400-e29b-41d4-a716-446655440000',
        name: 'LOW_RISK',
        displayLabel: 'Baixo Risco',
        minScore: 700,
        maxScore: 850,
        baseRate: 0.0199,
        rateSpread: 0.005,
        priority: 1,
        isActive: true,
      },
    },
  }),
});

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

Response (201 Created)

{
  "data": {
    "type": "risk-bands",
    "id": "550e8400-e29b-41d4-a716-446655440001",
    "attributes": {
      "productId": "550e8400-e29b-41d4-a716-446655440000",
      "name": "LOW_RISK",
      "displayLabel": "Baixo Risco",
      "minScore": 700,
      "maxScore": 850,
      "baseRate": 0.0199,
      "rateSpread": 0.005,
      "priority": 1,
      "isActive": true,
      "createdAt": "2024-01-15T10:30:00Z",
      "updatedAt": "2024-01-15T10:30:00Z"
    },
    "links": {
      "self": "/api/v1/risk-bands/550e8400-e29b-41d4-a716-446655440001"
    }
  }
}

Listar Risk Bands

GET /api/v1/risk-bands

Lista risk bands 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
`productId`	string	Filtrar por produto
`isActive`	boolean	Filtrar por status ativo

cURL
JavaScript

curl 'https://pricing.stg.catalisa.app/api/v1/risk-bands?productId=550e8400-e29b-41d4-a716-446655440000&isActive=true' \
  -H 'Authorization: Bearer SEU_TOKEN'

const params = new URLSearchParams({
  productId: '550e8400-e29b-41d4-a716-446655440000',
  isActive: 'true',
});

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

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

Response (200 OK)

{
  "data": [
    {
      "type": "risk-bands",
      "id": "550e8400-e29b-41d4-a716-446655440001",
      "attributes": {
        "productId": "550e8400-e29b-41d4-a716-446655440000",
        "name": "LOW_RISK",
        "minScore": 700,
        "maxScore": 850,
        "baseRate": 0.0199,
        "isActive": true
      }
    },
    {
      "type": "risk-bands",
      "id": "550e8400-e29b-41d4-a716-446655440002",
      "attributes": {
        "productId": "550e8400-e29b-41d4-a716-446655440000",
        "name": "MEDIUM_RISK",
        "minScore": 500,
        "maxScore": 699,
        "baseRate": 0.0299,
        "isActive": true
      }
    }
  ],
  "meta": {
    "totalItems": 3,
    "totalPages": 1,
    "currentPage": 1
  },
  "links": {
    "self": "/api/v1/risk-bands?page[number]=1&page[size]=20"
  }
}

Obter Risk Band

GET /api/v1/risk-bands/:id

Obtém detalhes de uma risk band específica.

cURL
JavaScript

curl 'https://pricing.stg.catalisa.app/api/v1/risk-bands/550e8400-e29b-41d4-a716-446655440001' \
  -H 'Authorization: Bearer SEU_TOKEN'

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

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

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

Response (200 OK)

{
  "data": {
    "type": "risk-bands",
    "id": "550e8400-e29b-41d4-a716-446655440001",
    "attributes": {
      "productId": "550e8400-e29b-41d4-a716-446655440000",
      "name": "LOW_RISK",
      "displayLabel": "Baixo Risco",
      "minScore": 700,
      "maxScore": 850,
      "baseRate": 0.0199,
      "rateSpread": 0.005,
      "priority": 1,
      "isActive": true,
      "createdAt": "2024-01-15T10:30:00Z",
      "updatedAt": "2024-01-15T10:30:00Z"
    },
    "links": {
      "self": "/api/v1/risk-bands/550e8400-e29b-41d4-a716-446655440001"
    }
  }
}

Atualizar Risk Band

PATCH /api/v1/risk-bands/:id

Atualiza uma risk band existente.

cURL
JavaScript

curl -X PATCH 'https://pricing.stg.catalisa.app/api/v1/risk-bands/550e8400-e29b-41d4-a716-446655440001' \
  -H 'Authorization: Bearer SEU_TOKEN' \
  -H 'Content-Type: application/json' \
  -d '{
    "data": {
      "type": "risk-bands",
      "id": "550e8400-e29b-41d4-a716-446655440001",
      "attributes": {
        "baseRate": 0.0179,
        "isActive": false
      }
    }
  }'

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

const response = await fetch(`https://pricing.stg.catalisa.app/api/v1/risk-bands/${id}`, {
  method: 'PATCH',
  headers: {
    'Authorization': `Bearer ${token}`,
    'Content-Type': 'application/json',
  },
  body: JSON.stringify({
    data: {
      type: 'risk-bands',
      id,
      attributes: {
        baseRate: 0.0179,
        isActive: false,
      },
    },
  }),
});

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

Response (200 OK)

{
  "data": {
    "type": "risk-bands",
    "id": "550e8400-e29b-41d4-a716-446655440001",
    "attributes": {
      "productId": "550e8400-e29b-41d4-a716-446655440000",
      "name": "LOW_RISK",
      "baseRate": 0.0179,
      "isActive": false,
      "updatedAt": "2024-01-15T11:00:00Z"
    }
  }
}

Excluir Risk Band

DELETE /api/v1/risk-bands/:id

Remove uma risk band.

cURL
JavaScript

curl -X DELETE 'https://pricing.stg.catalisa.app/api/v1/risk-bands/550e8400-e29b-41d4-a716-446655440001' \
  -H 'Authorization: Bearer SEU_TOKEN'

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

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

// Status 204 No Content = sucesso

Response (204 No Content)

Sem corpo de resposta.

Exemplo de Configuração de Faixas

// Configurar 3 faixas de risco para um produto
const riskBands = [
  { name: 'EXCELLENT', minScore: 800, maxScore: 1000, baseRate: 0.0149 },
  { name: 'GOOD', minScore: 650, maxScore: 799, baseRate: 0.0199 },
  { name: 'FAIR', minScore: 500, maxScore: 649, baseRate: 0.0299 },
];

for (const band of riskBands) {
  await fetch('https://pricing.stg.catalisa.app/api/v1/risk-bands', {
    method: 'POST',
    headers: {
      'Authorization': `Bearer ${token}`,
      'Content-Type': 'application/json',
    },
    body: JSON.stringify({
      data: {
        type: 'risk-bands',
        attributes: {
          productId: 'product-uuid',
          ...band,
          isActive: true,
        },
      },
    }),
  });
}

Erros Comuns

Código	Erro	Descrição
400	`VALIDATION`	Campos obrigatorios ausentes ou inválidos
404	`NOT_FOUND`	Risk band nao encontrada
409	`CONFLICT`	Faixas de score sobrepostas para o mesmo produto

Endpoints​

Atributos​

Criar Risk Band​

Request​

Response (201 Created)​

Listar Risk Bands​

Query Parameters​

Response (200 OK)​

Obter Risk Band​

Response (200 OK)​

Atualizar Risk Band​

Response (200 OK)​

Excluir Risk Band​

Response (204 No Content)​

Exemplo de Configuração de Faixas​

Erros Comuns​

Endpoints

Atributos

Criar Risk Band

Request

Response (201 Created)

Listar Risk Bands

Query Parameters

Response (200 OK)

Obter Risk Band

Response (200 OK)

Atualizar Risk Band

Response (200 OK)

Excluir Risk Band

Response (204 No Content)

Exemplo de Configuração de Faixas

Erros Comuns