# QI Tech — Insurance-as-a-Service › Apólices

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

Índice:
- Cancelar apólice (/documentation/seguros/apolices/cancelar_apolice)
- Consultar apólice (/documentation/seguros/apolices/consultar_apolice)
- Início (/documentation/seguros/apolices/inicio)
- Listar apólices de um pedido (/documentation/seguros/apolices/listar_apolices)
- Webhooks da apólice (/documentation/seguros/apolices/webhooks)

---

# Cancelar apólice

URL: /documentation/seguros/apolices/cancelar_apolice

Cancela uma **única** apólice; as demais apólices do mesmo pedido não são afetadas. Para cancelar **todas** as apólices de um pedido de uma vez, use o [cancelamento do pedido](/documentation/seguros/pedidos/cancelar_pedido) em um pedido emitido.

O cancelamento vale **no momento da chamada**: a resposta já traz a apólice como `canceled`, a cobrança das parcelas seguintes é interrompida e o [webhook de apólice cancelada](/documentation/seguros/apolices/webhooks#apolice-cancelada) é enviado. A comunicação com a seguradora acontece em seguida, de forma assíncrona, e não desfaz o cancelamento.

## Devolução de prêmio

A devolução, quando devida, é calculada sobre o que já foi pago, a partir do momento da solicitação:

| Momento do cancelamento | Devolução |
|---|---|
| Até 7 dias corridos da contratação — direito de arrependimento | **Integral** do que foi pago. |
| Após 7 dias | **Proporcional**: a parte do que foi pago que excede o período de cobertura já decorrido. |

## Request

ENDPOINT /v1/insurance/policies/{policy_key}/cancel
MÉTODO POST

### Path params

| Parâmetro | Tipo | Obrigatoriedade | Descrição |
|---|---|---|---|
| `policy_key` | string | obrigatório | Chave da apólice. |

```json title="Request Body"
{
  "reason": "Cliente solicitou o cancelamento"
}
```

| Campo | Tipo | Obrigatoriedade | Descrição |
|---|---|---|---|
| `reason` | string | opcional | Motivo do cancelamento, de 1 a 255 caracteres, registrado na trilha de eventos e enviado no webhook de cancelamento. Sem motivo informado, é registrado `requester_requested`. O corpo inteiro é opcional. |

## Response

STATUS 200

```json title="Response Body"
{
  "policy_key": "0b6e7c1a-9a4e-4c1e-b1d4-2f5a8c9e0d31",
  "order_key": "5e2b3f60-7c4b-4c8e-9f1a-6d2e8b4a7c90",
  "status": "canceled"
}
```

### Semântica por status

| Status atual da apólice | Resultado |
|---|---|
| `active` | `200` — a apólice é cancelada. |
| `active`, com a vigência já encerrada | `409` `POL000011` — a cobertura já terminou. |
| `canceled` | `409` `POL000012` — a apólice já foi cancelada. |
| `finished` | `409` `POL000011` — a vigência já terminou. |
| outra integração / inexistente | `404` `POL000001` |

## 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` | `POL000001` | Apólice inexistente ou pertencente a outra integração. |
| `409` | `POL000011` | A vigência da cobertura já terminou. |
| `409` | `POL000012` | A apólice já foi cancelada. |

---

# Consultar apólice

URL: /documentation/seguros/apolices/consultar_apolice

Retorna o detalhe de uma apólice: identidade e chaves de correlação, status, número da apólice na seguradora, a classificação do produto, a decomposição do prêmio (bruto, IOF e líquido), a vigência, as coberturas efetivas e a trilha de eventos.

## Request

ENDPOINT /v1/insurance/policies/{policy_key}
MÉTODO GET

### Path params

| Parâmetro | Tipo | Obrigatoriedade | Descrição |
|---|---|---|---|
| `policy_key` | string | obrigatório | Chave da apólice, obtida na [listagem por pedido](/documentation/seguros/apolices/listar_apolices) ou nos [webhooks de apólice](/documentation/seguros/apolices/webhooks). |

## Response

STATUS 200

```json title="Response Body"
{
  "policy_key": "0b6e7c1a-9a4e-4c1e-b1d4-2f5a8c9e0d31",
  "order_key": "5e2b3f60-7c4b-4c8e-9f1a-6d2e8b4a7c90",
  "provider_product_key": "9d1f8c7a-3b21-4e60-8a2f-1c5d7e9b0a44",
  "provider_key": "c4a2e8b0-1f6d-4e3a-9c7b-5d0a2e8f4b61",
  "status": "issued",
  "external_policy_number": "APL-2026-000123",
  "customer_document_number": "96969879003",
  "product_category": "insurance",
  "insurance_class": {
    "name": "credit_life",
    "class_number": "0977",
    "group_number": "09"
  },
  "regulator_registration": "15414.900388/2015-21",
  "gross_premium_amount": 617.28,
  "iof_amount": 2.35,
  "net_premium_amount": 614.93,
  "term": {
    "start_date": "2026-07-16",
    "end_date": "2027-07-15"
  },
  "effective_services": [
    {
      "effective_service_key": "7f3a9c2e-0b5d-4e8a-a1c6-9d4b2e7f0a53",
      "provider_service_key": "0a3c5e7f-2b4d-4a6c-8e0f-1a3b5c7d9e2f",
      "service_type": {
        "code": "credit_life",
        "name": "Prestamista (Credit Life)"
      },
      "service_category": "insurance",
      "regulator_registration": null,
      "insured_amount": 150000.00,
      "gross_premium_amount": 617.28,
      "deductible_data": {
        "deductible_type": "monetary_amount",
        "value": 1500.00
      },
      "waiting_period_days": 30,
      "service_attributes": {},
      "term": {
        "start_date": "2026-07-16",
        "end_date": "2027-07-15"
      }
    }
  ],
  "events": [
    {
      "new_status": "issuance_requested",
      "agent_type": "system",
      "created_at": "2026-07-16T14:03:25.481Z"
    },
    {
      "new_status": "issued",
      "agent_type": "provider",
      "created_at": "2026-07-16T15:00:00.000Z"
    }
  ]
}
```

### Atributos da resposta

| Campo | Tipo | Descrição |
|---|---|---|
| `policy_key` | string | Chave única da apólice. |
| `order_key` | string | Chave do pedido que originou a apólice. |
| `provider_product_key` | string | Chave do produto no catálogo. |
| `provider_key` | string | Chave da seguradora emissora. |
| `status` | string | Status atual. Veja o [ciclo de vida](/documentation/seguros/apolices/inicio). |
| `external_policy_number` | string | Número da apólice na seguradora. `null` até a emissão ser confirmada (`issued`). |
| `customer_document_number` | string | Documento do segurado. |
| `product_category` | string | Categoria do produto: `insurance`, `capitalization` ou `benefit`. |
| `insurance_class` | object | Ramo do seguro: `{ name, class_number, group_number }`. `null` para produtos não securitários. `class_number` e `group_number` são strings — os zeros à esquerda são significativos. |
| `regulator_registration` | string | Registro do produto no regulador (ex.: processo SUSEP). |
| `gross_premium_amount` | number | Prêmio bruto (o valor pago pelo segurado), com IOF. |
| `iof_amount` | number | Componente de IOF do prêmio. |
| `net_premium_amount` | number | Prêmio líquido (bruto menos IOF). |
| `term` | object | Vigência da apólice: `{ start_date, end_date }`. |
| `effective_services` | array | Coberturas efetivas da apólice. |
| `events` | array | Trilha de transições de status, em ordem cronológica — é dela que se derivam os instantes do ciclo de vida (emissão, solicitação de cancelamento, cancelamento). |

#### Objeto em `effective_services`

| Campo | Tipo | Descrição |
|---|---|---|
| `effective_service_key` | string | Chave única da cobertura efetiva. |
| `provider_service_key` | string | Chave da cobertura no catálogo. |
| `service_type` | object | Tipo da cobertura: `{ code, name }`. |
| `service_category` | string | Categoria da cobertura: `insurance`, `capitalization` ou `benefit`. |
| `regulator_registration` | string | Registro próprio da cobertura no regulador. `null` quando herda o do produto. |
| `insured_amount` | number | Importância segurada contratada. |
| `gross_premium_amount` | number | Prêmio bruto da cobertura. |
| `deductible_data` | object | Franquia contratada: `{ deductible_type, value }`. |
| `waiting_period_days` | integer | Carência em dias. |
| `service_attributes` | object | Atributos fixos da cobertura. |
| `term` | object | Vigência da cobertura: `{ start_date, end_date }`. |

#### Objeto em `events`

| Campo | Tipo | Descrição |
|---|---|---|
| `new_status` | string | O status assumido na transição. |
| `agent_type` | string | Quem causou a transição: `requester` (sua integração), `provider` (seguradora), `system` (automático) ou `operator` (operação QI Tech). |
| `created_at` | string | Instante da transição. |

## 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` | `POL000001` | Apólice inexistente ou pertencente a outra integração — os casos são indistinguíveis. |
| `429` | — | Limite de requisições excedido — repita com backoff. |
| `500` | `QIT000500` | Erro interno — seguro repetir a chamada. |
| `503` | `POL000030` | Serviço indisponível — seguro repetir a chamada. |

---

# Início

URL: /documentation/seguros/apolices/inicio

A **apólice** (`policy`) é o contrato de seguro individual — uma por produto vendido em um pedido emitido. Ela nasce logo após a emissão do pedido e passa a ser a fonte da verdade sobre a cobertura: número da apólice, vigência, coberturas efetivas, prêmio decomposto e trilha de eventos.

## Ciclo de vida da apólice

![Fluxo de status da apólice, da criação ao cancelamento ou ao fim da vigência](/img/diagrams/seguros-apolices-inicio.svg)

_Como ler o diagrama: **azul** = apólice em vigor · **vermelho** = cancelada (gera webhook) · **verde** = encerramento natural (não gera webhook)._

| Status | Significado |
|---|---|
| `active` | A apólice está em vigor desde a criação. A confirmação da emissão pela seguradora não muda o status: ela aparece como o `external_policy_number` preenchido e gera o [webhook](/documentation/seguros/apolices/webhooks) `issued`. Até lá, o `external_policy_number` é `null`. |
| `canceled` | A apólice foi cancelada — pelo [cancelamento da apólice](/documentation/seguros/apolices/cancelar_apolice), pelo [cancelamento do pedido](/documentation/seguros/pedidos/cancelar_pedido) depois da emissão ou pela seguradora. O status muda no momento do cancelamento e gera o webhook `canceled`. |
| `finished` | A vigência chegou ao fim (`term.end_date`). Status terminal, sem webhook — o fim de vigência é conhecido desde a emissão. |

## Devolução de prêmio no cancelamento

A devolução, quando devida, é calculada sobre o que já foi pago, a partir do momento da solicitação do cancelamento:

- **Até 7 dias corridos da contratação** — direito de arrependimento: devolução **integral** do que foi pago.
- **Após 7 dias**: devolução **proporcional** — a parte do que foi pago que excede o período de cobertura já decorrido.

## Endpoints

| Endpoint | Descrição |
|---|---|
| [`GET /v1/insurance/policies/{policy_key}`](/documentation/seguros/apolices/consultar_apolice) | Detalha uma apólice. |
| [`GET /v1/insurance/policies?order_key=`](/documentation/seguros/apolices/listar_apolices) | Lista as apólices de um pedido emitido. |
| [`POST /v1/insurance/policies/{policy_key}/cancel`](/documentation/seguros/apolices/cancelar_apolice) | Cancela uma apólice individualmente. |

---

# Listar apólices de um pedido

URL: /documentation/seguros/apolices/listar_apolices

Lista as apólices geradas por um pedido emitido — **a** forma de descobrir as `policy_key` de um pedido, já que a consulta de pedido não retorna apólices. Retorna resumos; para o detalhe completo, use a [consulta de apólice](/documentation/seguros/apolices/consultar_apolice).

## Request

ENDPOINT /v1/insurance/policies
MÉTODO GET

### Query params

| Parâmetro | Tipo | Obrigatoriedade | Descrição |
|---|---|---|---|
| `order_key` | string | obrigatório | Chave do pedido cujas apólices serão listadas. |

```python title="Exemplo de chamada"
GET /v1/insurance/policies?order_key=5e2b3f60-7c4b-4c8e-9f1a-6d2e8b4a7c90
```

## Response

STATUS 200

```json title="Response Body"
{
  "order_key": "5e2b3f60-7c4b-4c8e-9f1a-6d2e8b4a7c90",
  "policies": [
    {
      "policy_key": "0b6e7c1a-9a4e-4c1e-b1d4-2f5a8c9e0d31",
      "provider_product_key": "9d1f8c7a-3b21-4e60-8a2f-1c5d7e9b0a44",
      "provider_key": "c4a2e8b0-1f6d-4e3a-9c7b-5d0a2e8f4b61",
      "status": "issued",
      "external_policy_number": "APL-2026-000123",
      "gross_premium_amount": 617.28,
      "term": {
        "start_date": "2026-07-16",
        "end_date": "2027-07-15"
      },
      "created_at": "2026-07-16T14:03:25.481Z"
    }
  ]
}
```

### Atributos da resposta

| Campo | Tipo | Descrição |
|---|---|---|
| `order_key` | string | Chave do pedido consultado. |
| `policies` | array | Resumo de cada apólice do pedido. Os campos são um subconjunto da [consulta de apólice](/documentation/seguros/apolices/consultar_apolice). |

:::info Consistência eventual após a emissão
As apólices são criadas de forma **assíncrona** logo após o webhook de `emitted` do pedido. Imediatamente após a emissão, esta lista pode vir vazia ou menor que o `product_count` do webhook enquanto as apólices são materializadas. Aguarde os [webhooks de apólice](/documentation/seguros/apolices/webhooks) ou consulte novamente em instantes.
:::

Um `order_key` desconhecido, ainda não processado ou pertencente a outra integração retorna `200` com a lista vazia — os casos são indistinguíveis.

## 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` | `QIT000001` | Parâmetro `order_key` ausente. |
| `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` | `POL000030` | Serviço indisponível — seguro repetir a chamada. |

---

# Webhooks da apólice

URL: /documentation/seguros/apolices/webhooks

Os marcos do ciclo de vida da apólice são notificados por webhooks do tipo `insurance.policy.status_changed`. Dois status geram evento: `issued` (emissão confirmada pela seguradora) e `canceled` (apólice cancelada). O encerramento natural de vigência (`finished`) **não** gera webhook — ele é conhecido desde a emissão pelo `term.end_date`.

Cada apólice é notificada de forma independente: um pedido com N produtos gera N apólices e N eventos de cada tipo, possivelmente em momentos diferentes.

:::info Configuração e validação

Para receber webhooks é necessário ter uma URL de webhook configurada, e cada webhook deve ter a assinatura validada. Veja [Configurando webhooks](/documentation/seguros/primeiros_passos/seguros_configurando_webhooks) e [Validação de webhooks](/documentation/seguros/primeiros_passos/teste_de_autenticacao/seguros_webhook_v2).

:::

## Estrutura do webhook

| Campo | Tipo | Descrição |
|---|---|---|
| `webhook_type` | string | Sempre `insurance.policy.status_changed`. |
| `status` | string | Novo status da apólice: `issued` ou `canceled`. |
| `key` | string | Chave da apólice (`policy_key`). |
| `event_datetime` | string | Data e hora do evento, em UTC, no formato ISO 8601. |
| `data` | object | Dados do evento. Veja tabela abaixo. |

### Atributos de `data`

| Campo | Tipo | Descrição |
|---|---|---|
| `policy_key` | string | Chave da apólice. |
| `order_key` | string | Chave do pedido que originou a apólice — a correlação com a sua venda. |
| `requester_key` | string | Chave da sua integração como distribuidor. |
| `status` | string | Novo status da apólice — o mesmo do campo `status` externo. |
| `external_policy_number` | string | Número da apólice na seguradora. |
| `reason` | string / null | Motivo do cancelamento no evento de `canceled`; `null` no de `issued`. |
| `sequence` | integer | Ordem do evento dentro da apólice: um valor maior é sempre um evento posterior. A sequência não é contínua — o primeiro webhook de uma apólice pode chegar com um valor maior que `1`. |
| `schema_version` | integer | Versão da estrutura de `data`. Atualmente `1`. |

:::caution Atenção

O status de cancelamento da apólice é `canceled`, com um **l**. O do pedido é `cancelled`, com dois. Trate os dois valores separadamente.

:::

## Eventos por status

### Apólice emitida

STATUS issued

Enviado quando a seguradora confirma a emissão. A partir deste evento a cobertura está formalmente registrada na seguradora.

```json title="Webhook Body"
{
  "status": "issued",
  "webhook_type": "insurance.policy.status_changed",
  "key": "0b6e7c1a-9a4e-4c1e-b1d4-2f5a8c9e0d31",
  "event_datetime": "2026-10-05T20:41:02Z",
  "data": {
    "policy_key": "0b6e7c1a-9a4e-4c1e-b1d4-2f5a8c9e0d31",
    "order_key": "5e2b3f60-7c4b-4c8e-9f1a-6d2e8b4a7c90",
    "requester_key": "3f1c9a2e-4b7d-4e0a-9c55-2d8e7f6a1b30",
    "status": "issued",
    "external_policy_number": "QIS000000000123",
    "reason": null,
    "sequence": 1,
    "schema_version": 1
  }
}
```

---

### Apólice cancelada

STATUS canceled

Enviado quando a apólice é cancelada — pelo [cancelamento da apólice](/documentation/seguros/apolices/cancelar_apolice) ou do [pedido depois da emissão](/documentation/seguros/pedidos/cancelar_pedido), no momento do cancelamento, ou pela seguradora. O campo `reason` traz o motivo informado no cancelamento, ou `requester_requested` se nenhum foi informado; num cancelamento feito pela seguradora, ele vem como `provider_initiated`.

```json title="Webhook Body"
{
  "status": "canceled",
  "webhook_type": "insurance.policy.status_changed",
  "key": "0b6e7c1a-9a4e-4c1e-b1d4-2f5a8c9e0d31",
  "event_datetime": "2026-10-05T21:18:33Z",
  "data": {
    "policy_key": "0b6e7c1a-9a4e-4c1e-b1d4-2f5a8c9e0d31",
    "order_key": "5e2b3f60-7c4b-4c8e-9f1a-6d2e8b4a7c90",
    "requester_key": "3f1c9a2e-4b7d-4e0a-9c55-2d8e7f6a1b30",
    "status": "canceled",
    "external_policy_number": "QIS000000000123",
    "reason": "Cliente solicitou o cancelamento",
    "sequence": 3,
    "schema_version": 1
  }
}
```

:::danger Atenção!

Os webhooks da QI Tech não devem ser mapeados de forma estrita.
Campos adicionais podem ser incluídos aos payloads dos webhooks retornados em nossas APIs.

:::