# 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 (/zh-Hans/documentation/seguros/apolices/cancelar_apolice)
- Consultar apólice (/zh-Hans/documentation/seguros/apolices/consultar_apolice)
- Início (/zh-Hans/documentation/seguros/apolices/inicio)
- Listar apólices de um pedido (/zh-Hans/documentation/seguros/apolices/listar_apolices)
- Webhooks da Apólice (/zh-Hans/documentation/seguros/apolices/webhooks)

---

# Cancelar apólice

URL: /zh-Hans/documentation/seguros/apolices/cancelar_apolice

Cancela uma **única** apólice; as demais apólices do mesmo pedido não são afetadas. O cancelamento é sempre **assíncrono e em duas fases**: a solicitação coloca a apólice em `cancellation_requested` e o cancelamento efetivo (`canceled`) só ocorre quando a seguradora confirma — até lá, a cobertura permanece em vigor.

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.

## Devolução de prêmio

Na confirmação do cancelamento, a QI Tech determina a base e calcula o valor da devolução automaticamente, sobre o prêmio bruto (`gross_premium_amount`):

| Momento do cancelamento | Base de devolução |
|---|---|
| Até 7 dias corridos da confirmação da emissão (`issued`) — direito de arrependimento | Devolução **integral** do prêmio. |
| Após 7 dias | Devolução **proporcional** ao período de cobertura não decorrido (pró-rata). |

A confirmação do cancelamento chega pelo [webhook de cancelamento](/documentation/seguros/apolices/webhooks#apolice-cancelada) e a devolução ao pagador é executada pela QI Tech.

## 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, registrado na trilha de eventos e ecoado no webhook de cancelamento. |

## Response

STATUS 202

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

A conclusão do cancelamento chega pelo [webhook de apólice](/documentation/seguros/apolices/webhooks) com status `canceled`, e pode ser acompanhada pela [consulta de apólice](/documentation/seguros/apolices/consultar_apolice).

### Semântica por status

| Status atual da apólice | Resultado |
|---|---|
| `issued` | `202` — cancelamento solicitado à seguradora. |
| `cancellation_requested` | `202` — idempotente: não gera segunda solicitação e retorna o mesmo corpo. |
| `issuance_requested` | `409` — a apólice ainda não está em vigor. Para desfazer a venda inteira nesse estágio, cancele o **pedido** (a solicitação fica retida e cancela a apólice automaticamente assim que a emissão confirmar); para cancelar só esta apólice, aguarde a emissão confirmar. |
| `canceled` | `409` — já cancelada. |
| `finished` | `409` — a vigência já terminou. |
| outra integração / inexistente | `404` |

## 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. |
| `409` | `POL000010` | A apólice já foi cancelada. |
| `409` | `POL000011` | A vigência da cobertura já terminou. |
| `409` | `POL000012` | A apólice ainda não está em vigor. |
| `429` | — | Limite de requisições excedido — repita com backoff. |
| `500` | `QIT000500` | Erro interno — a solicitação é idempotente, repita a chamada. |
| `503` | `POL000030` | Serviço indisponível — a solicitação é idempotente, repita a chamada. |

---

# Consultar apólice

URL: /zh-Hans/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: /zh-Hans/documentation/seguros/apolices/inicio

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

## Ciclo de vida da apólice

![Fluxo de status da apólice, da solicitação de emissão ao encerramento](/img/diagrams/seguros-apolices-inicio.svg)

_Como ler o diagrama: **contorno tracejado** = status transitório que não gera webhook · **azul** = emissão confirmada (gera webhook) · **verde** = encerramento natural (não gera webhook) · **vermelho** = cancelada (gera webhook)._

| Status | Significado |
|---|---|
| `issuance_requested` | Apólice criada na emissão do pedido; a emissão foi solicitada à seguradora e aguarda confirmação. |
| `issued` | A seguradora confirmou a emissão. O `external_policy_number` (número da apólice na seguradora) passa a estar disponível. A cobertura está em vigor. |
| `cancellation_requested` | Um cancelamento foi solicitado e aguarda a confirmação da seguradora. **A cobertura permanece em vigor** enquanto o cancelamento não é confirmado. |
| `canceled` | A seguradora confirmou o cancelamento. A devolução de prêmio, quando devida, é calculada e processada automaticamente. |
| `finished` | A vigência da apólice chegou ao fim naturalmente (`term.end_date`). Status terminal, sem evento — o fim de vigência é conhecido desde a emissão. |

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

Quando um cancelamento é confirmado, a QI Tech determina a base de devolução e calcula o valor automaticamente, sobre o prêmio bruto (`gross_premium_amount`):

- **Dentro de 7 dias corridos** da confirmação da emissão (`issued`) — direito de arrependimento: devolução **integral** do prêmio.
- **Após 7 dias**: devolução **proporcional** ao período de cobertura não decorrido (pró-rata).

A devolução é calculada na confirmação do cancelamento e executada ao pagador pela própria QI Tech.

## 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: /zh-Hans/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: /zh-Hans/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` (cancelamento confirmado). Os status transitórios (`issuance_requested`, `cancellation_requested`) e o encerramento natural de vigência (`finished`) **não** geram webhook — os transitórios são resultado das suas próprias chamadas, e o fim de vigência é conhecido desde a emissão pelo `term.end_date`.

:::info Configuração de webhooks
Para receber webhooks é necessário ter uma URL de callback configurada. Veja [Autenticação — Recebimento de webhooks](/documentation/seguros/introducao/autenticacao#recebimento-de-webhooks).
:::

## Estrutura do webhook

| Campo | Tipo | Descrição |
|---|---|---|
| `webhook_type` | string | Sempre `insurance.policy.status_changed`. |
| `webhook_datetime` | string | Data e hora do evento 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. |
| `status` | string | Novo status: `issued` ou `canceled`. |
| `external_policy_number` | string | Número da apólice na seguradora. Presente no evento de `issued`. |
| `reason` | string | Motivo do cancelamento. Presente no evento de `canceled`, quando informado. |

```json title="Estrutura padrão do webhook"
{
  "webhook_type": "insurance.policy.status_changed",
  "webhook_datetime": "2026-07-16T15:00:00Z",
  "data": {
    "policy_key": "0b6e7c1a-9a4e-4c1e-b1d4-2f5a8c9e0d31",
    "order_key": "5e2b3f60-7c4b-4c8e-9f1a-6d2e8b4a7c90",
    "status": "status",
    "external_policy_number": "APL-2026-000123",
    "reason": null
  }
}
```

## Eventos por status

### Apólice emitida

STATUS issued

Enviado quando a seguradora confirma a emissão. A partir deste evento o `external_policy_number` está disponível e a cobertura está formalmente em vigor. Como cada apólice é emitida de forma independente, um pedido com N produtos gera N eventos deste tipo — possivelmente em momentos diferentes.

```json title="Webhook Body"
{
  "webhook_type": "insurance.policy.status_changed",
  "webhook_datetime": "2026-07-16T15:00:00Z",
  "data": {
    "policy_key": "0b6e7c1a-9a4e-4c1e-b1d4-2f5a8c9e0d31",
    "order_key": "5e2b3f60-7c4b-4c8e-9f1a-6d2e8b4a7c90",
    "status": "issued",
    "external_policy_number": "APL-2026-000123",
    "reason": null
  }
}
```

---

### Apólice cancelada

STATUS canceled

Enviado quando a seguradora confirma o cancelamento — solicitado pelo [cancelamento de apólice](/documentation/seguros/apolices/cancelar_apolice) ou pelo [cancelamento pós-emissão do pedido](/documentation/seguros/pedidos/cancelar_pedido). A devolução de prêmio devida (integral dentro do direito de arrependimento, pró-rata depois) é calculada neste momento e executada pela QI Tech.

```json title="Webhook Body"
{
  "webhook_type": "insurance.policy.status_changed",
  "webhook_datetime": "2026-08-02T09:30:00Z",
  "data": {
    "policy_key": "0b6e7c1a-9a4e-4c1e-b1d4-2f5a8c9e0d31",
    "order_key": "5e2b3f60-7c4b-4c8e-9f1a-6d2e8b4a7c90",
    "status": "canceled",
    "external_policy_number": "APL-2026-000123",
    "reason": "Cliente solicitou o cancelamento"
  }
}
```

:::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.
:::