# QI Tech — Insurance-as-a-Service › Catálogo de Produtos

Documentação da QI Tech em texto corrido, para colar em um LLM.
Fonte: https://docs.qitech.com.br
3 página(s).

Índice:
- Consultar produto (/documentation/seguros/catalogo/consultar_produto)
- Início (/documentation/seguros/catalogo/inicio)
- Listar produtos (/documentation/seguros/catalogo/listar_produtos)

---

# Consultar produto

URL: /documentation/seguros/catalogo/consultar_produto

Retorna o **envelope de venda** de um produto habilitado para a sua integração: as coberturas ativas com seus espaços de opções, as dependências entre coberturas, os seus valores padrão e a sua faixa de comissão. Com essa resposta você tem tudo o que precisa para montar uma [cotação](/documentation/seguros/cotacao/criar_cotacao) válida.

## Request

ENDPOINT /v1/product_catalog/products/{product_key}
MÉTODO GET

### Path params

| Parâmetro | Tipo | Obrigatoriedade | Descrição |
|---|---|---|---|
| `product_key` | string | obrigatório | Chave do produto, obtida na [listagem de produtos](/documentation/seguros/catalogo/listar_produtos). |

## Response

STATUS 200

```json title="Response Body"
{
  "product_key": "9d1f8c7a-3b21-4e60-8a2f-1c5d7e9b0a44",
  "name": "Prestamista Master",
  "product_category": "insurance",
  "insurance_class": "credit_life",
  "contract_instrument_type": "ticket",
  "regulator_registration": "15414.900123/2025-77",
  "provider_name": "QI Seguradora",
  "commission_bounds": {
    "minimum_rate": 0.05,
    "maximum_rate": 0.20,
    "default_rate": 0.15
  },
  "services": [
    {
      "service_key": "0a3c5e7f-2b4d-4a6c-8e0f-1a3b5c7d9e2f",
      "service_type": "credit_life",
      "service_category": "insurance",
      "mandatory": true,
      "maximum_insured_amount": 500000.00,
      "deductible_options": {
        "deductible_type": "monetary_amount",
        "options_type": "list",
        "options": [0.00, 1500.00, 3000.00]
      },
      "waiting_period_options": {
        "waiting_period_type": "days",
        "options_type": "range",
        "options": {
          "minimum": 0,
          "maximum": 90,
          "step": 30
        }
      },
      "indemnity_unit_options": null,
      "regulator_registration": null,
      "dependencies": {
        "include": [],
        "exclude": []
      },
      "service_attributes": null,
      "default_configuration": {
        "insured_amount_basis": "percentage_of_risk_value",
        "insured_amount": null,
        "insured_amount_percentage": 0.8000,
        "unit_amount": null,
        "unit_count": null,
        "deductible_data": {
          "deductible_type": "monetary_amount",
          "value": 1500.00
        },
        "waiting_period_days": 30
      }
    }
  ]
}
```

### Atributos da resposta

| Campo | Tipo | Descrição |
|---|---|---|
| `product_key` | string | Chave única do produto. |
| `name` | string | Nome comercial do produto. |
| `product_category` | string | Categoria do produto: `insurance`, `capitalization` ou `benefit`. |
| `insurance_class` | string | Ramo SUSEP do produto. `null` para produtos não-seguro. |
| `contract_instrument_type` | string | Instrumento contratual do produto: `ticket` (bilhete) ou `policy` (apólice). Determina o fluxo de contratação e quais métodos de aceite são válidos — veja [Criar pedido](/documentation/seguros/pedidos/criar_pedido). `null` para produtos não securitários. |
| `regulator_registration` | string | Registro do produto na SUSEP (Código SUSEP). |
| `provider_name` | string | Nome da seguradora parceira. |
| `commission_bounds` | object | A **sua** faixa de comissão para este produto: `minimum_rate`, `maximum_rate` e `default_rate` (taxas decimais com 4 casas). A comissão da cotação/pedido é validada contra `[minimum_rate, maximum_rate]`; se omitida, vale `default_rate`. |
| `services` | array | Coberturas **ativas** do produto. |

#### Objeto em `services`

| Campo | Tipo | Descrição |
|---|---|---|
| `service_key` | string | Chave única da cobertura. Use-a na lista `services` da cotação e do pedido. |
| `service_type` | string | Tipo da cobertura (ex.: `credit_life`). |
| `service_category` | string | Categoria da cobertura: `insurance`, `capitalization` ou `benefit`. |
| `mandatory` | boolean | Cobertura obrigatória em toda venda do produto. Uma seleção que a omita é rejeitada com `MISSING_MANDATORY_SERVICE`. |
| `maximum_insured_amount` | number | Importância segurada máxima aceita. `null` para coberturas sem importância segurada (benefícios). |
| `deductible_options` | object | Envelope tipado das franquias aceitas (veja abaixo). `null` indica que a cobertura **não tem franquia** — enviar `deductible_data` para ela é rejeitado. |
| `waiting_period_options` | object | Envelope tipado das carências aceitas (veja abaixo). `null` indica que a cobertura **não tem carência**. |
| `indemnity_unit_options` | object | Envelope tipado das unidades de indenização aceitas, para coberturas precificadas por unidade (ex.: "R$ 100 por diária, até 60 diárias"). `null` indica que a cobertura **não é precificada por unidade** — enviar `unit_amount`/`unit_count` para ela é rejeitado com `OUT_OF_OPTION_SPACE`. |
| `regulator_registration` | string | Registro SUSEP próprio da cobertura. `null` indica que a cobertura herda o registro do produto. |
| `dependencies` | object | Regras estruturais entre coberturas deste produto: `include` (chaves de coberturas pré-requisito — toda cobertura listada precisa estar na seleção) e `exclude` (chaves mutuamente exclusivas — não podem coexistir na seleção). |
| `service_attributes` | object | Atributos fixos da cobertura definidos pela seguradora (ex.: quantidades de um benefício). Ecoados na cotação. |
| `default_configuration` | object | O **seu** padrão configurado para esta cobertura — o que a cotação preenche automaticamente quando a seleção omite `services`. Todos os campos de valor são emitidos, com `null` nos que não se aplicam; `insured_amount_basis` diz qual está ativo. Os valores vêm na **mesma forma** que você enviaria na seleção, prontos para reuso. `null` quando não há padrão configurado. |

#### Envelopes de opções (`deductible_options` / `waiting_period_options` / `indemnity_unit_options`)

| Campo | Tipo | Descrição |
|---|---|---|
| `deductible_type` | string | Tipo da franquia: `monetary_amount`, `days` ou `percentage_of_insured_amount`. Presente em `deductible_options`. |
| `waiting_period_type` | string | Tipo da carência: `days`. Presente em `waiting_period_options`. |
| `indemnity_unit_type` | string | Tipo da unidade de indenização (ex.: `daily`). Presente em `indemnity_unit_options`. |
| `options_type` | string | Forma do espaço de opções: `list` (lista de valores aceitos) ou `range` (intervalo `{minimum, maximum, step}`; `step` `null` indica intervalo contínuo). |
| `options` | array / object | Os valores aceitos, na forma indicada por `options_type`. |

#### Objeto `default_configuration`

| Campo | Tipo | Descrição |
|---|---|---|
| `insured_amount_basis` | string | Base da importância segurada: `monetary_amount` (valor absoluto), `percentage_of_risk_value` (percentual do valor do objeto de risco) ou `unit_amount_times_count` (valor por unidade × quantidade de unidades). Diz qual dos campos de valor abaixo está ativo. |
| `insured_amount` | number | Importância segurada em reais. Presente quando a base é `monetary_amount`; `null` nas demais. |
| `insured_amount_percentage` | number | Percentual do valor do objeto de risco, em `(0, 1]` (`1.0000` = 100%). Presente quando a base é `percentage_of_risk_value`; `null` nas demais. |
| `unit_amount` | number | Valor por unidade de indenização. Presente quando a base é `unit_amount_times_count`; `null` nas demais. |
| `unit_count` | integer | Quantidade de unidades de indenização. Presente quando a base é `unit_amount_times_count`; `null` nas demais. |
| `deductible_data` | object | Franquia padrão, na mesma forma tipada enviada na seleção: `{ deductible_type, value }`. |
| `waiting_period_days` | integer | Carência padrão, em dias. |

## Possíveis erros

Todo erro (`non-2xx`) retorna o corpo padrão `{ "title", "description", "translation", "code" }` — trate programaticamente **apenas** o campo `code`.

| Status | Código | Descrição |
|---|---|---|
| `401` / `403` | — | Falha de autenticação ou autorização. |
| `404` | `CAT000040` | O produto não existe, está inativo ou não está habilitado para a sua integração — os três casos são indistinguíveis. |
| `429` | — | Limite de requisições excedido — repita com backoff. |
| `500` | `QIT000500` | Erro interno — seguro repetir a chamada. |
| `503` | `CAT000033` | Serviço indisponível — seguro repetir a chamada. |

---

# Início

URL: /documentation/seguros/catalogo/inicio

O **Catálogo de Produtos** é a superfície de descoberta do Insurance-as-a-Service: ele responde "o que a minha integração pode vender?" e "como monto uma seleção válida para cotar?". São dois endpoints somente de leitura, escopados aos produtos habilitados para a sua integração.

## Conceitos

| Conceito | Descrição |
|---|---|
| **Produto** (`product`) | Um produto de seguro de uma seguradora parceira (ex.: um prestamista, um seguro de vida em grupo). É a unidade de venda: cada produto vendido em um pedido gera uma apólice. Endereçado por `product_key`. |
| **Cobertura** (`service`) | Uma cobertura ou benefício que compõe o produto (ex.: morte, invalidez por acidente, assistência funeral). Pode ser obrigatória (`mandatory`) ou opcional. Endereçada por `service_key`. |
| **Espaço de opções** | Os limites configuráveis de cada cobertura: importância segurada máxima (`maximum_insured_amount`) e os envelopes tipados de franquia (`deductible_options`) e carência (`waiting_period_options`) aceitos. Uma seleção fora do espaço de opções é rejeitada na cotação. |
| **Dependências** | Regras estruturais entre coberturas do mesmo produto: `include` (coberturas pré-requisito) e `exclude` (coberturas mutuamente exclusivas). |
| **Faixa de comissão** (`commission_bounds`) | A banda `{minimum_rate, maximum_rate, default_rate}` da **sua** comissão por venda daquele produto. A comissão enviada na cotação e no pedido (`commission_data`) é validada contra essa faixa; se omitida, vale o `default_rate`. |
| **Configuração padrão** (`default_configuration`) | Valores padrão de cobertura configurados para a sua integração. Quando a seleção omite a lista `services`, a cotação preenche automaticamente todas as coberturas padrão configuradas. |

## Classificação dos produtos

Cada produto carrega uma classificação regulatória e comercial:

| Campo | Descrição |
|---|---|
| `product_category` | `insurance`, `capitalization` ou `benefit`. Um produto pode combinar coberturas de categorias diferentes (ex.: seguro + assistência). |
| `insurance_class` | O ramo SUSEP do produto (ex.: `credit_life`). Ausente para produtos não-seguro. Na cotação e no pedido, o ramo é retornado como objeto `{ name, class_number, group_number }`. |
| `regulator_registration` | O registro do produto na SUSEP (Código SUSEP). |

## Visibilidade e confidencialidade

- Somente produtos **ativos** habilitados para a sua integração são visíveis; um produto de outro parceiro (ou inexistente) retorna `404`.
- A faixa de comissão retornada é sempre a **sua** — nunca a de outro parceiro.
- As regras internas de tarifação e elegibilidade da seguradora não são expostas: você recebe os limites estruturais (espaço de opções e dependências) e o resultado da avaliação na [cotação](/documentation/seguros/cotacao/criar_cotacao).

## Endpoints

| Endpoint | Descrição |
|---|---|
| [`GET /v1/product_catalog/products`](/documentation/seguros/catalogo/listar_produtos) | Lista os produtos que a sua integração pode vender. |
| [`GET /v1/product_catalog/products/{product_key}`](/documentation/seguros/catalogo/consultar_produto) | Detalha um produto: coberturas, espaço de opções, dependências, seus padrões e sua faixa de comissão. |

---

# Listar produtos

URL: /documentation/seguros/catalogo/listar_produtos

Retorna a lista paginada de produtos de seguro **ativos e habilitados para a sua integração** — a resposta à pergunta "o que posso vender?". Cada item traz um resumo do produto e de suas coberturas; para o envelope completo de venda, use a [consulta de produto](/documentation/seguros/catalogo/consultar_produto).

## Request

ENDPOINT /v1/product_catalog/products
MÉTODO GET

### Query params

| Parâmetro | Tipo | Obrigatoriedade | Descrição |
|---|---|---|---|
| `page` | integer | opcional | Número da página. Padrão: `1`. |
| `rows_per_page` | integer | opcional | Registros por página. Padrão: `50`. |
| `name` | string | opcional | Filtra pelo nome do produto. |
| `product_category` | string | opcional | Filtra pela categoria: `insurance`, `capitalization` ou `benefit`. |
| `insurance_class` | string | opcional | Filtra pelo ramo do produto (ex.: `credit_life`). |
| `service_category` | string | opcional | Filtra por produtos que contenham cobertura da categoria informada. |

```python title="Exemplo de chamada"
GET /v1/product_catalog/products?page=1&rows_per_page=50&product_category=insurance
```

## Response

STATUS 200

```json title="Response Body"
{
  "data": [
    {
      "product_key": "9d1f8c7a-3b21-4e60-8a2f-1c5d7e9b0a44",
      "name": "Prestamista Master",
      "product_category": "insurance",
      "insurance_class": "credit_life",
      "contract_instrument_type": "ticket",
      "provider_name": "QI Seguradora",
      "services": [
        {
          "service_type": "credit_life",
          "service_category": "insurance",
          "mandatory": true
        },
        {
          "service_type": "funeral_assistance",
          "service_category": "benefit",
          "mandatory": false
        }
      ]
    }
  ],
  "pagination": {
    "current_page": 1,
    "next_page": null,
    "rows_per_page": 50
  }
}
```

### Atributos da resposta

| Campo | Tipo | Descrição |
|---|---|---|
| `data` | array | Lista de produtos habilitados. |
| `pagination` | object | Estado da paginação: `current_page` (página atual), `next_page` (número da próxima página, ou `null` quando esta é a última) e `rows_per_page` (tamanho da página solicitado). |

:::caution Esta listagem não retorna `total`
A paginação do catálogo é **por cursor de página**, não por contagem: pare de paginar quando `pagination.next_page` vier `null`. A [listagem de pedidos](/documentation/seguros/pedidos/listar_pedidos) usa uma convenção diferente (`page_size` + `total`) — as duas superfícies não são intercambiáveis.
:::

#### Objeto em `data`

| Campo | Tipo | Descrição |
|---|---|---|
| `product_key` | string | Chave única do produto. Use-a na consulta de produto, na cotação e no pedido. |
| `name` | string | Nome comercial do produto. |
| `product_category` | string | Categoria do produto: `insurance`, `capitalization` ou `benefit`. |
| `insurance_class` | string | Ramo SUSEP do produto (ex.: `credit_life`). `null` para produtos não-seguro. |
| `contract_instrument_type` | string | Instrumento contratual do produto: `ticket` (bilhete) ou `policy` (apólice). Determina o fluxo de contratação — veja [Criar pedido](/documentation/seguros/pedidos/criar_pedido). `null` para produtos não securitários. |
| `provider_name` | string | Nome da seguradora parceira. |
| `services` | array | Resumo das coberturas do produto. |

#### Objeto em `services`

| Campo | Tipo | Descrição |
|---|---|---|
| `service_type` | string | Tipo da cobertura (ex.: `credit_life`, `life_death`, `funeral_assistance`). |
| `service_category` | string | Categoria da cobertura: `insurance`, `capitalization` ou `benefit`. |
| `mandatory` | boolean | Indica se a cobertura é obrigatória em toda venda do produto. |

## Possíveis erros

Todo erro (`non-2xx`) retorna o corpo padrão `{ "title", "description", "translation", "code" }` — trate programaticamente **apenas** o campo `code`.

| Status | Código | Descrição |
|---|---|---|
| `400` | `QIT000010` | Parâmetro de paginação inválido. |
| `400` | `QIT000001` | Parâmetro de filtro malformado. |
| `401` / `403` | — | Falha de autenticação ou autorização. |
| `429` | — | Limite de requisições excedido — repita com backoff. |
| `500` | `QIT000500` | Erro interno — seguro repetir a chamada. |
| `503` | `CAT000033` | Serviço indisponível — seguro repetir a chamada. |