# 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:
- Cancel policy (/en/documentation/seguros/apolices/cancelar_apolice)
- Retrieve policy (/en/documentation/seguros/apolices/consultar_apolice)
- Overview (/en/documentation/seguros/apolices/inicio)
- List policies of an order (/en/documentation/seguros/apolices/listar_apolices)
- Policy Webhooks (/en/documentation/seguros/apolices/webhooks)

---

# Cancel policy

URL: /en/documentation/seguros/apolices/cancelar_apolice

Cancels a **single** policy; the other policies of the same order are not affected. Cancellation is always **asynchronous and two-phase**: the request puts the policy in `cancellation_requested` and the effective cancellation (`canceled`) only happens when the insurer confirms — until then, coverage remains in force.

To cancel **all** policies of an order at once, use the [order cancellation](/documentation/seguros/pedidos/cancelar_pedido) on an emitted order.

## Premium refund

At cancellation confirmation, QI Tech determines the basis and computes the refund amount automatically, over the gross premium (`gross_premium_amount`):

| Cancellation moment | Refund basis |
|---|---|
| Within 7 calendar days of the issuance confirmation (`issued`) — cooling-off right | **Full** premium refund. |
| After 7 days | Refund **proportional** to the unelapsed coverage period (pro rata). |

The cancellation confirmation arrives through the [cancellation webhook](/documentation/seguros/apolices/webhooks#policy-canceled) and the refund to the payer is executed by QI Tech.

## Request

ENDPOINT /v1/insurance/policies/{policy_key}/cancel
METHOD POST

### Path params

| Parameter | Type | Required | Description |
|---|---|---|---|
| `policy_key` | string | required | Policy key. |

```json title="Request Body"
{
  "reason": "Customer requested cancellation"
}
```

| Field | Type | Required | Description |
|---|---|---|---|
| `reason` | string | optional | Cancellation reason, recorded in the event trail and echoed in the cancellation webhook. |

## Response

STATUS 202

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

Completion arrives through the [policy webhook](/documentation/seguros/apolices/webhooks) with status `canceled`, and can be tracked through the [policy retrieval](/documentation/seguros/apolices/consultar_apolice).

### Semantics per status

| Current policy status | Result |
|---|---|
| `issued` | `202` — cancellation requested from the insurer. |
| `cancellation_requested` | `202` — idempotent: no second request is produced and the same body is returned. |
| `issuance_requested` | `409` — the policy is not in force yet. To undo the whole sale at this stage, cancel the **order** (the request is retained and cancels the policy automatically as soon as the issuance confirms); to cancel only this policy, wait for the issuance to confirm. |
| `canceled` | `409` — already canceled. |
| `finished` | `409` — the term has already ended. |
| another integration / nonexistent | `404` |

## Possible errors

Every error (`non-2xx`) returns the standard body `{ "title", "description", "translation", "code" }` — programmatically handle **only** the `code` field.

| Status | Code | Description |
|---|---|---|
| `401` / `403` | — | Authentication or authorization failure. |
| `404` | `POL000001` | Policy nonexistent or belonging to another integration. |
| `409` | `POL000010` | The policy has already been canceled. |
| `409` | `POL000011` | The coverage term has already ended. |
| `409` | `POL000012` | The policy is not in force yet. |
| `429` | — | Request limit exceeded — retry with backoff. |
| `500` | `QIT000500` | Internal error — the request is idempotent, retry the call. |
| `503` | `POL000030` | Service unavailable — the request is idempotent, retry the call. |

---

# Retrieve policy

URL: /en/documentation/seguros/apolices/consultar_apolice

Returns a policy's detail: identity and correlation keys, status, the insurer's policy number, the product classification, the premium decomposition (gross, IOF and net), the term, the effective coverages and the event trail.

## Request

ENDPOINT /v1/insurance/policies/{policy_key}
METHOD GET

### Path params

| Parameter | Type | Required | Description |
|---|---|---|---|
| `policy_key` | string | required | Policy key, obtained from the [listing by order](/documentation/seguros/apolices/listar_apolices) or from the [policy webhooks](/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"
    }
  ]
}
```

### Response attributes

| Field | Type | Description |
|---|---|---|
| `policy_key` | string | Unique policy key. |
| `order_key` | string | Key of the order that originated the policy. |
| `provider_product_key` | string | Catalog key of the product. |
| `provider_key` | string | Key of the issuing insurer. |
| `status` | string | Current status. See the [lifecycle](/documentation/seguros/apolices/inicio). |
| `external_policy_number` | string | Policy number at the insurer. `null` until issuance is confirmed (`issued`). |
| `customer_document_number` | string | Insured person's document. |
| `product_category` | string | Product category: `insurance`, `capitalization` or `benefit`. |
| `insurance_class` | object | Insurance class: `{ name, class_number, group_number }`. `null` for non-insurance products. `class_number` and `group_number` are strings — leading zeros are significant. |
| `regulator_registration` | string | Product registration at the regulator (e.g. SUSEP process). |
| `gross_premium_amount` | number | Gross premium (the amount paid by the insured person), IOF-inclusive. |
| `iof_amount` | number | IOF component of the premium. |
| `net_premium_amount` | number | Net premium (gross minus IOF). |
| `term` | object | Policy term: `{ start_date, end_date }`. |
| `effective_services` | array | Effective coverages of the policy. |
| `events` | array | Trail of status transitions, in chronological order — the lifecycle instants (issuance, cancellation request, cancellation) derive from it. |

#### Object in `effective_services`

| Field | Type | Description |
|---|---|---|
| `effective_service_key` | string | Unique key of the effective coverage. |
| `provider_service_key` | string | Catalog key of the coverage. |
| `service_type` | object | Coverage type: `{ code, name }`. |
| `service_category` | string | Coverage category: `insurance`, `capitalization` or `benefit`. |
| `regulator_registration` | string | Coverage's own registration at the regulator. `null` when it inherits the product's. |
| `insured_amount` | number | Contracted insured amount. |
| `gross_premium_amount` | number | Gross premium of the coverage. |
| `deductible_data` | object | Contracted deductible: `{ deductible_type, value }`. |
| `waiting_period_days` | integer | Waiting period in days. |
| `service_attributes` | object | Fixed coverage attributes. |
| `term` | object | Coverage term: `{ start_date, end_date }`. |

#### Object in `events`

| Field | Type | Description |
|---|---|---|
| `new_status` | string | The status assumed in the transition. |
| `agent_type` | string | Who caused the transition: `requester` (your integration), `provider` (insurer), `system` (automatic) or `operator` (QI Tech operations). |
| `created_at` | string | Instant of the transition. |

## Possible errors

Every error (`non-2xx`) returns the standard body `{ "title", "description", "translation", "code" }` — programmatically handle **only** the `code` field.

| Status | Code | Description |
|---|---|---|
| `401` / `403` | — | Authentication or authorization failure. |
| `404` | `POL000001` | Policy nonexistent or belonging to another integration — the cases are indistinguishable. |
| `429` | — | Request limit exceeded — retry with backoff. |
| `500` | `QIT000500` | Internal error — safe to retry the call. |
| `503` | `POL000030` | Service unavailable — safe to retry the call. |

---

# Overview

URL: /en/documentation/seguros/apolices/inicio

The **policy** is the individual insurance contract — one per product sold in an emitted order. It is born at the order's emission, registered with the insurer and becomes the source of truth about the coverage: the insurer's policy number, the term, the effective coverages, the decomposed premium and the event trail.

## Policy lifecycle

![Policy status flow, from issuance request to closure](/img/diagrams/seguros-apolices-inicio-en.svg)

_How to read the diagram: **dashed outline** = transient status that emits no webhook · **blue** = issuance confirmed (emits a webhook) · **green** = natural end of term (no webhook) · **red** = canceled (emits a webhook)._

| Status | Meaning |
|---|---|
| `issuance_requested` | Policy created at the order's emission; issuance was requested from the insurer and awaits confirmation. |
| `issued` | The insurer confirmed the issuance. The `external_policy_number` (policy number at the insurer) becomes available. Coverage is in force. |
| `cancellation_requested` | A cancellation was requested and awaits the insurer's confirmation. **Coverage remains in force** until the cancellation is confirmed. |
| `canceled` | The insurer confirmed the cancellation. The premium refund, when due, is computed and processed automatically. |
| `finished` | The policy term ended naturally (`term.end_date`). Terminal status, without an event — the end of term is known since issuance. |

## Premium refund on cancellation

When a cancellation is confirmed, QI Tech determines the refund basis and computes the amount automatically, over the gross premium (`gross_premium_amount`):

- **Within 7 calendar days** of the issuance confirmation (`issued`) — cooling-off right: **full** premium refund.
- **After 7 days**: refund **proportional** to the unelapsed coverage period (pro rata).

The refund is computed at the cancellation confirmation and executed to the payer by QI Tech itself.

## Endpoints

| Endpoint | Description |
|---|---|
| [`GET /v1/insurance/policies/{policy_key}`](/documentation/seguros/apolices/consultar_apolice) | Retrieves one policy. |
| [`GET /v1/insurance/policies?order_key=`](/documentation/seguros/apolices/listar_apolices) | Lists the policies of an emitted order. |
| [`POST /v1/insurance/policies/{policy_key}/cancel`](/documentation/seguros/apolices/cancelar_apolice) | Cancels a policy individually. |

---

# List policies of an order

URL: /en/documentation/seguros/apolices/listar_apolices

Lists the policies produced by an emitted order — **the** way to discover the `policy_key`s of an order, since the order retrieval does not return policies. Returns summaries; for the full detail, use the [policy retrieval](/documentation/seguros/apolices/consultar_apolice).

## Request

ENDPOINT /v1/insurance/policies
METHOD GET

### Query params

| Parameter | Type | Required | Description |
|---|---|---|---|
| `order_key` | string | required | Key of the order whose policies will be listed. |

```python title="Example call"
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"
    }
  ]
}
```

### Response attributes

| Field | Type | Description |
|---|---|---|
| `order_key` | string | Key of the queried order. |
| `policies` | array | Summary of each policy of the order. Fields are a subset of the [policy retrieval](/documentation/seguros/apolices/consultar_apolice). |

:::info Eventual consistency after emission
Policies are created **asynchronously** right after the order's `emitted` webhook. Immediately after emission, this list may come back empty or shorter than the webhook's `product_count` while the policies are being materialized. Wait for the [policy webhooks](/documentation/seguros/apolices/webhooks) or query again shortly.
:::

An `order_key` that is unknown, not yet processed or belonging to another integration returns `200` with an empty list — the cases are indistinguishable.

## Possible errors

Every error (`non-2xx`) returns the standard body `{ "title", "description", "translation", "code" }` — programmatically handle **only** the `code` field.

| Status | Code | Description |
|---|---|---|
| `400` | `QIT000001` | Missing `order_key` parameter. |
| `401` / `403` | — | Authentication or authorization failure. |
| `429` | — | Request limit exceeded — retry with backoff. |
| `500` | `QIT000500` | Internal error — safe to retry the call. |
| `503` | `POL000030` | Service unavailable — safe to retry the call. |

---

# Policy Webhooks

URL: /en/documentation/seguros/apolices/webhooks

The milestones of the policy lifecycle are notified through webhooks of type `insurance.policy.status_changed`. Two statuses produce an event: `issued` (issuance confirmed by the insurer) and `canceled` (cancellation confirmed). The transient statuses (`issuance_requested`, `cancellation_requested`) and the natural end of term (`finished`) do **not** produce webhooks — the transient ones are the result of your own calls, and the end of term is known since issuance through `term.end_date`.

:::info Webhook configuration
Receiving webhooks requires a configured callback URL. See [Authentication — Receiving webhooks](/documentation/seguros/introducao/autenticacao#receiving-webhooks).
:::

## Webhook structure

| Field | Type | Description |
|---|---|---|
| `webhook_type` | string | Always `insurance.policy.status_changed`. |
| `webhook_datetime` | string | Date and time of the event in ISO 8601. |
| `data` | object | Event data. See table below. |

#### Attributes of `data`

| Field | Type | Description |
|---|---|---|
| `policy_key` | string | Policy key. |
| `order_key` | string | Key of the order that originated the policy — the correlation with your sale. |
| `status` | string | New status: `issued` or `canceled`. |
| `external_policy_number` | string | Policy number at the insurer. Present in the `issued` event. |
| `reason` | string | Cancellation reason. Present in the `canceled` event, when informed. |

```json title="Standard webhook structure"
{
  "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
  }
}
```

## Events per status

### Policy issued

STATUS issued

Sent when the insurer confirms the issuance. From this event on, the `external_policy_number` is available and coverage is formally in force. Since each policy is issued independently, an order with N products produces N events of this type — possibly at different moments.

```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
  }
}
```

---

### Policy canceled

STATUS canceled

Sent when the insurer confirms the cancellation — requested through the [policy cancellation](/documentation/seguros/apolices/cancelar_apolice) or through the [post-emission order cancellation](/documentation/seguros/pedidos/cancelar_pedido). The premium refund due (full within the cooling-off right, pro rata afterwards) is computed at this moment and executed by 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": "Customer requested cancellation"
  }
}
```

:::danger Attention!
QI Tech webhooks must not be mapped strictly.
Additional fields may be added to the webhook payloads returned by our APIs.
:::