# QI Tech — Insurance-as-a-Service › Pedidos

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

Índice:
- Cancelar pedido (/documentation/seguros/pedidos/cancelar_pedido)
- Consultar pedido (/documentation/seguros/pedidos/consultar_pedido)
- Criar pedido (/documentation/seguros/pedidos/criar_pedido)
- Início (/documentation/seguros/pedidos/inicio)
- Listar pedidos (/documentation/seguros/pedidos/listar_pedidos)
- Webhooks do Pedido (/documentation/seguros/pedidos/webhooks)

---

# Cancelar pedido

URL: /documentation/seguros/pedidos/cancelar_pedido

Cancela um pedido. O comportamento depende do momento:

- **Antes da emissão** (`awaiting_payment`): a venda é desfeita e o pedido vai para `cancelled`.
- **Depois da emissão** (`emitted`): o pedido em si não muda de status. A chamada dispara **um pedido de cancelamento por apólice** do pedido; cada apólice segue o seu próprio [fluxo de cancelamento](/documentation/seguros/apolices/cancelar_apolice), incluindo o cálculo da devolução de prêmio.

## Request

ENDPOINT /v1/insurance/orders/{order_key}/cancel
MÉTODO POST

### Path params

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

```json title="Request Body"
{
  "reason": "Cliente desistiu da compra"
}
```

| Campo | Tipo | Obrigatoriedade | Descrição |
|---|---|---|---|
| `reason` | string | opcional | Motivo do cancelamento, registrado na trilha de eventos e propagado aos cancelamentos de apólice no caso pós-emissão. |

## Response

:::caution O QR Pix não é revogado no cancelamento pré-emissão
Nesta versão o cancelamento pré-emissão é uma transação local: o mandato Pix **não** é cancelado na cobrança, e o QR simplesmente expira junto com a janela de pagamento. Um segurado que autorize o pagamento mesmo assim paga em um pedido já `cancelled` — o pagamento é barrado antes da emissão e devolvido ao pagador. Trate o cancelamento como definitivo e pare de exibir o QR ao segurado.
:::

### Pré-emissão

STATUS 200

```json title="Response Body"
{
  "order_key": "5e2b3f60-7c4b-4c8e-9f1a-6d2e8b4a7c90",
  "status": "cancelled"
}
```

### Pós-emissão

STATUS 202

```json title="Response Body"
{
  "order_key": "5e2b3f60-7c4b-4c8e-9f1a-6d2e8b4a7c90",
  "status": "emitted",
  "policies_cancellation_requested": 2
}
```

| Campo | Tipo | Descrição |
|---|---|---|
| `policies_cancellation_requested` | integer | Quantidade de apólices cujo cancelamento foi solicitado — uma por produto do pedido. Acompanhe cada uma pelos [webhooks de apólice](/documentation/seguros/apolices/webhooks) ou pela [consulta de apólice](/documentation/seguros/apolices/consultar_apolice). |

### Semântica por status

| Status atual do pedido | Resultado |
|---|---|
| `awaiting_payment` | `200` — venda desfeita, pedido vai para `cancelled`. |
| `emitted` | `202` — cancelamento solicitado para cada apólice; o pedido permanece `emitted`. |
| `cancelled` | `200` — idempotente, nada muda. |
| `rejected` / `declined` / `expired` | `409` — status terminal, nada a cancelar. |

:::info Corrida entre pagamento e cancelamento
Se um pagamento for confirmado praticamente ao mesmo tempo do cancelamento pré-emissão, o pedido ainda é cancelado: o pagamento é barrado antes da emissão e devolvido ao pagador. Se o pagamento tiver sido confirmado **antes** e o pedido já estiver `emitted`, a mesma chamada passa a valer como cancelamento pós-emissão (`202`) — nunca há `409` nessa corrida.
:::

## 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` | `ORD000001` | Pedido inexistente ou pertencente a outra integração. |
| `409` | `ORD000010` | O pedido está em um status terminal sem nada a cancelar (`rejected`, `declined`, `expired`). |
| `502` / `504` | `ORD000031` | Falha em uma integração síncrona do cancelamento. Nenhum estado foi alterado — repita a chamada, ela é idempotente. |

---

# Consultar pedido

URL: /documentation/seguros/pedidos/consultar_pedido

Retorna o detalhe completo de um pedido: identidade, status, prazo de pagamento, os produtos congelados na submissão (com seus objetos de risco), a cobrança, o segurado e a trilha de eventos.

:::info O pedido não retorna apólices
O pedido é a visão da **venda**. Após a emissão (`emitted`), as apólices vivem em um recurso próprio — consulte-as com [`GET /v1/insurance/policies?order_key=`](/documentation/seguros/apolices/listar_apolices).
:::

## Request

ENDPOINT /v1/insurance/orders/{order_key}
MÉTODO GET

### Path params

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

## Response

STATUS 200

```json title="Response Body"
{
  "order_key": "5e2b3f60-7c4b-4c8e-9f1a-6d2e8b4a7c90",
  "status": "emitted",
  "distribution_type": "direct",
  "quote_data": {
    "total_order_amount": 617.28,
    "products": [
      {
        "order_product_key": "7f3a9c2e-0b5d-4e8a-a1c6-9d4b2e7f0a53",
        "product_key": "9d1f8c7a-3b21-4e60-8a2f-1c5d7e9b0a44",
        "product_category": "insurance",
        "insurance_class": {
          "name": "credit_life",
          "class_number": "0977",
          "group_number": "09"
        },
        "regulator_registration": "15414.900388/2015-21",
        "contract_instrument_type": "ticket",
        "gross_premium_amount": 617.28,
        "iof_amount": 2.35,
        "net_premium_amount": 614.93,
        "term": {
          "start_date": "2026-07-15",
          "end_date": "2027-07-14"
        },
        "risk_object": {
          "type": "credit_operation",
          "insurable_value": 50000.00,
          "attributes": {
            "installment_amount": 1050.00,
            "number_of_installments": 48
          }
        },
        "services": [
          {
            "service_key": "0a3c5e7f-2b4d-4a6c-8e0f-1a3b5c7d9e2f",
            "service_type": {
              "code": "credit_life",
              "name": "Prestamista (Credit Life)"
            },
            "service_category": "insurance",
            "regulator_registration": null,
            "gross_premium_amount": 617.28,
            "insured_amount": 50000.00,
            "unit_amount": null,
            "unit_count": null,
            "deductible_data": {
              "deductible_type": "monetary_amount",
              "value": 1500.00
            },
            "waiting_period_days": 30,
            "service_attributes": {},
            "term": {
              "start_date": "2026-07-15",
              "end_date": "2027-07-14"
            }
          }
        ]
      }
    ]
  },
  "payment_data": {
    "payment_method": "pix_automatic",
    "installment_count": 12,
    "installment_amount": 51.44,
    "first_installment_amount": 51.44,
    "first_due_date": "2026-07-23"
  },
  "customer": {
    "document_number": "96969879003",
    "name": "Maria Souza",
    "email": "maria@example.com",
    "phone_number": "+5511999990000",
    "date_of_birth": "1987-03-22",
    "occupation_code": "211205"
  },
  "events": [
    {
      "new_status": "emitted",
      "at": "2026-07-16T14:03:22Z"
    }
  ]
}
```

### Atributos da resposta

| Campo | Tipo | Descrição |
|---|---|---|
| `order_key` | string | Chave única do pedido. |
| `status` | string | Status atual. Veja o [ciclo de vida](/documentation/seguros/pedidos/inicio). |
| `expires_at` | string | Prazo para o pagamento da primeira parcela (7 dias a partir da submissão). `null` em um pedido `rejected`. |
| `distribution_type` | string | Modelo de distribuição da venda. Hoje sempre `direct`. |
| `payment_data` | object | A cobrança do pedido — mesmo bloco retornado na [criação](/documentation/seguros/pedidos/criar_pedido#objeto-payment_data-resposta). O sub-objeto `payment_artifact` (o QR Pix) só é reexposto enquanto o pedido está `awaiting_payment`; em um pedido emitido ou terminal ele é omitido. `null` em um pedido `rejected`. |
| `quote_data` | object | Os produtos congelados na submissão — mesmo bloco, com a mesma forma, retornado na [criação do pedido](/documentation/seguros/pedidos/criar_pedido). |
| `quote_data.total_order_amount` | number | Valor total do pedido (soma dos prêmios brutos dos produtos). |
| `customer` | object | O segurado do pedido, em objeto plano: `document_number`, `name`, `email`, `phone_number`, `date_of_birth`, `occupation_code`. Devolvido exatamente como foi submetido — a data de nascimento é o dado congelado; a idade usada na precificação foi derivada dela na submissão e não é armazenada. Os campos opcionais (`occupation_code`, `address`) **só aparecem se tiverem sido enviados**: nada é preenchido por padrão, e a chave é omitida em vez de vir `null`. |
| `events` | array | Trilha de mudanças de status do pedido, em ordem cronológica. Cada entrada é `{ "new_status", "at" }`. |

#### Objeto em `quote_data.products`

| Campo | Tipo | Descrição |
|---|---|---|
| `order_product_key` | string | Chave do produto dentro do pedido — a correlação com a apólice gerada na emissão. |
| `product_key` | string | Chave do produto no catálogo. |
| `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. |
| `regulator_registration` | string | Registro do produto no regulador (ex.: processo SUSEP). |
| `contract_instrument_type` | string | Instrumento contratual congelado do produto: `ticket` (bilhete) ou `policy` (apólice). `null` para produtos não securitários. |
| `gross_premium_amount` | number | Prêmio bruto do produto (com IOF). |
| `iof_amount` | number | IOF do produto. |
| `net_premium_amount` | number | Prêmio líquido do produto (sem IOF). |
| `term` | object | Vigência do produto, congelada na submissão: `{ start_date, end_date }`. Produtos do mesmo pedido podem ter vigências diferentes. |
| `risk_object` | object | O objeto de risco congelado deste produto (`type`, `insurable_value`, `attributes`). |
| `services` | array | Coberturas congeladas — cada uma com `service_type` (`{ code, name }`), `service_category`, `regulator_registration`, prêmio bruto, importância segurada, o par por unidade (`unit_amount` / `unit_count`, `null` quando a cobertura não é precificada por unidade), franquia (`deductible_data`), carência (`waiting_period_days`), atributos e vigência (`term`). |

:::caution Pedido `rejected` na consulta
Um pedido nascido `rejected` não persiste produtos nem cobrança: a consulta devolve `quote_data.products` vazio e `payment_data` nulo, e **não** repete os `decline_reasons`. Os motivos da recusa são entregues uma única vez, no `201` da [submissão](/documentation/seguros/pedidos/criar_pedido#pedido-recusado-rejected) — registre-os no seu lado.
:::

## 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` | `ORD000001` | Pedido inexistente ou pertencente a outra integração — os casos são indistinguíveis. |
| `500` / `503` | `QIT000500` | Erro interno ou serviço indisponível — seguro repetir a chamada. |

---

# Criar pedido

URL: /documentation/seguros/pedidos/criar_pedido

Cria e submete um pedido em uma única chamada. A submissão reprecifica a seleção no servidor (preços enviados pelo cliente nunca são confiados), valida o **aceite** que você coletou do segurado, cria a cobrança do prêmio e devolve o pedido em `awaiting_payment`, com o artefato Pix que o segurado deve pagar.

A lista `products[]` é **a mesma da [cotação](/documentation/seguros/cotacao/criar_cotacao)** — cotação e pedido usam a mesma gramática de seleção, acrescida do bloco `acceptance` por produto. A cotação é **indicativa**: a submissão reprecifica contra a configuração vigente e o preço do submit é o que vale.

:::info O aceite é coletado por você
A QI Tech não renderiza documento de proposta nem hospeda tela de assinatura nesta versão. Você conduz a cerimônia de aceite no seu próprio fluxo e **atesta** o resultado no campo `acceptance` de cada produto. Não existe `acceptance_url`.
:::

:::caution Apenas bilhete (`ticket`) nesta versão
O produto informa em `contract_instrument_type` se é vendido como **bilhete** (`ticket`) ou como **apólice** (`policy`). O bilhete dispensa proposta — o contrato se forma pelo ato da compra, e é por isso que o aceite atestado por você basta. Produtos `policy` ainda **não são vendáveis** e são recusados com `ORD000033`. O campo é ecoado na [cotação](/documentation/seguros/cotacao/criar_cotacao), então você descobre o instrumento **antes** de coletar o aceite.
:::

## Request

ENDPOINT /v1/insurance/order
MÉTODO POST

```json title="Request Body"
{
  "request_control_key": "5e2b3f60-7c4b-4c8e-9f1a-6d2e8b4a7c90",
  "products": [
    {
      "product_key": "9d1f8c7a-3b21-4e60-8a2f-1c5d7e9b0a44",
      "commission_data": {
        "commission_type": "percentage_of_gross_premium",
        "value": 0.1000
      },
      "term": {
        "start_date": "2026-07-16",
        "end_date": "2027-07-15"
      },
      "services": [
        {
          "service_key": "0a3c5e7f-2b4d-4a6c-8e0f-1a3b5c7d9e2f",
          "insured_amount_basis": "monetary_amount",
          "insured_amount": 50000.00
        }
      ],
      "risk_object": {
        "type": "credit_operation",
        "insurable_value": 50000.00,
        "attributes": {
          "installment_amount": 1050.00,
          "number_of_installments": 48
        }
      },
      "acceptance": {
        "acceptance_method": "click_wrap",
        "accepted_at": "2026-07-16T13:58:04Z",
        "ip_address": "200.150.10.24",
        "document_number_hash": "f7c3bc1d808e04732adf679965ccc34ca7ae3441ef0d5e6ba2c1d0f0d5f1e2a3",
        "terms": {
          "version": "2026-05-v3",
          "hash": "9b74c9897bac770ffc029102a200c5de"
        },
        "user_agent": "Mozilla/5.0 (iPhone; CPU iPhone OS 17_5 like Mac OS X)",
        "evidence_reference": "ceremony-8842197"
      }
    }
  ],
  "customer": {
    "document_number": "96969879003",
    "name": "Maria Souza",
    "email": "maria@example.com",
    "phone_number": "+5511999990000",
    "date_of_birth": "1987-03-22",
    "occupation_code": "211205",
    "address": {
      "street": "Avenida Paulista",
      "number": "1000",
      "complement": "Conjunto 42",
      "neighborhood": "Bela Vista",
      "city": "São Paulo",
      "state": "SP",
      "postal_code": "01310100"
    }
  },
  "payment_data": {
    "payment_method": "pix_automatic",
    "installment_count": 12
  }
}
```

### Atributos do request

| Campo | Tipo | Obrigatoriedade | Descrição |
|---|---|---|---|
| `request_control_key` | string (UUID) | opcional | Chave de controle definida por você. Veja [Controle de duplicidade](#controle-de-duplicidade) — **não é uma chave de retentativa**. |
| `products` | array | obrigatório | A seleção de produtos, de 1 a 20 itens, no mesmo formato da [cotação](/documentation/seguros/cotacao/criar_cotacao#atributos-do-request) mais o bloco `acceptance`. |
| `customer` | object | obrigatório | O comprador/segurado do pedido (um por pedido). |
| `payment_data` | object | obrigatório | Forma de pagamento do prêmio. |

#### Objeto em `products[]`

| Campo | Tipo | Obrigatoriedade | Descrição |
|---|---|---|---|
| `product_key` | string | obrigatório | Chave do produto no [catálogo](/documentation/seguros/catalogo/inicio). Não pode se repetir no mesmo pedido. |
| `commission_data` | object | opcional | A forma de comissão desejada para o produto. Omitido, aplica-se a taxa padrão (`default_rate`) do produto. Veja abaixo. |
| `term` | object | obrigatório | Vigência do produto, em datas absolutas: `{ "start_date": "AAAA-MM-DD", "end_date": "AAAA-MM-DD" }`. Não há forma por duração nem vigência padrão no nível do pedido. `end_date` deve ser posterior a `start_date`. |
| `services` | array | opcional | Coberturas selecionadas. Omitido, aplica-se a configuração padrão do produto. Mesmo formato da [cotação](/documentation/seguros/cotacao/criar_cotacao#objeto-em-services). |
| `risk_object` | object | obrigatório | Objeto de risco do produto (`type`, `insurable_value`, `attributes`). `insurable_value` é obrigatório para `type` `credit_operation` e `vehicle`. Um produto cujo objeto de risco é a própria pessoa informa `{"type": "person"}` — o bloco nunca é omitido. |
| `acceptance` | object | obrigatório | O aceite do segurado para **este** produto. Veja abaixo. |

#### Objeto `commission_data`

| Campo | Tipo | Obrigatoriedade | Descrição |
|---|---|---|---|
| `commission_type` | string | obrigatório | Uma de três formas, mutuamente exclusivas: `percentage_of_gross_premium` (taxa sobre o prêmio bruto), `monetary_amount` (comissão em R$ fixo) ou `total_gross_premium_amount` (preço final desejado ao cliente). |
| `value` | number | obrigatório | O valor da forma escolhida: taxa com 4 casas decimais (ex.: `0.1000`), valor em R$ (ex.: `61.73`) ou preço total (ex.: `650.00`). |

A comissão efetiva é sempre validada contra a faixa (`commission_bounds`) do produto. Um valor fora da faixa **rejeita a linha na precificação**: o pedido nasce `rejected`, com `OUT_OF_BOUNDS_COMMISSION` em `decline_reasons`. Um `commission_type` desconhecido ou `value` mal tipado é `400`.

#### Objeto `acceptance`

O aceite é atestado **por produto**, nunca herdado de um produto vizinho: cada `OrderProduct` vira exatamente uma apólice, e a evidência precisa sobreviver ao lado do contrato que ela justifica. Quando uma única cerimônia cobriu vários produtos, repita o bloco em cada item.

| Campo | Tipo | Obrigatoriedade | Descrição |
|---|---|---|---|
| `acceptance_method` | string | obrigatório | Como o aceite foi coletado: `click_wrap`, `checkbox`, `otp_sms`, `otp_email` ou `voice`. |
| `accepted_at` | string | obrigatório | Data e hora do aceite, em RFC 3339 (ex.: `2026-07-16T13:58:04Z`). Deve estar dentro das últimas **24 horas** e não pode estar no futuro além de 5 minutos de tolerância de relógio — caso contrário, `ORD000027`. |
| `ip_address` | string | obrigatório | Endereço IP (v4 ou v6) de onde o aceite foi dado. |
| `document_number_hash` | string | obrigatório | SHA-256 (hex, 64 caracteres) do `customer.document_number`, sem salt. É recalculado e conferido no servidor: divergência é `ORD000026`. |
| `terms` | object | obrigatório | Identificação das condições aceitas: `{ "version", "hash" }`. |
| `user_agent` | string | opcional | User agent do dispositivo do segurado (até 512 caracteres). |
| `evidence_reference` | string | opcional | Referência da evidência no seu sistema (até 128 caracteres). |

:::caution O hash é um token de integridade, não anonimização
`document_number_hash` é SHA-256 **sem salt** sobre um CPF — o espaço é exaustivamente pesquisável. A escolha é deliberada, para que qualquer detentor do documento possa reverificar o vínculo. Não o trate como dado pseudonimizado.
:::

#### Objeto `customer`

O objeto é plano — não há wrapper `data`. Diferente da cotação, onde tudo é opcional, aqui o comprador é o **segurado de registro** e também o pagador da cobrança — por isso a maioria dos campos passa a ser obrigatória.

| Campo | Tipo | Obrigatoriedade | Descrição |
|---|---|---|---|
| `document_number` | string | obrigatório | CPF (11 dígitos) ou CNPJ (14 dígitos) do segurado, somente dígitos. |
| `name` | string | obrigatório | Nome completo. |
| `email` | string | obrigatório | E-mail do segurado. |
| `phone_number` | string | obrigatório | Telefone, 10 a 15 dígitos, opcionalmente prefixado por `+`. |
| `date_of_birth` | string | obrigatório | Data de nascimento do segurado, no formato `YYYY-MM-DD`. A **idade** lida pelas regras de precificação e elegibilidade é derivada dela no momento da cotação — não envie idade. |
| `occupation_code` | string | opcional | Código de ocupação (CBO). Se o produto precifica ou avalia elegibilidade por ocupação, a ausência do código **rejeita a linha** — o pedido nasce `rejected` com o motivo em `decline_reasons`, não `400`. Consulte o produto no [catálogo](/documentation/seguros/catalogo/inicio) para saber se ele lê esse campo. |
| `address` | object | obrigatório | Endereço do segurado. |

#### Objeto `customer.address`

| Campo | Tipo | Obrigatoriedade | Descrição |
|---|---|---|---|
| `street` | string | obrigatório | Logradouro. |
| `number` | string | obrigatório | Número. |
| `complement` | string | opcional | Complemento. |
| `neighborhood` | string | obrigatório | Bairro. |
| `city` | string | obrigatório | Município. |
| `state` | string | obrigatório | Unidade federativa. |
| `postal_code` | string | obrigatório | CEP, 8 dígitos, sem separadores. |

#### Objeto `payment_data`

| Campo | Tipo | Obrigatoriedade | Descrição |
|---|---|---|---|
| `payment_method` | string | obrigatório | Meio de pagamento do prêmio. Único valor aceito nesta versão: `pix_automatic` (Pix Automático). |
| `installment_count` | integer | obrigatório | Quantidade de parcelas do prêmio, de `1` a `24`. |

### Controle de duplicidade

`request_control_key` é uma **asserção de unicidade**, não um handle de retentativa. **Qualquer** segundo uso do mesmo par (sua integração, `request_control_key`) responde `409` / `ORD000011` — inclusive com corpo idêntico. Nada compara corpos.

:::danger Obrigação de integração
Um submit que estourar timeout pode ter sido **efetivado**. Repetir a chamada com a mesma `request_control_key` responde `409`, e não devolve o pedido. O caminho de recuperação é `GET /v1/insurance/order?request_control_key={sua_chave}`. Repetir com uma **chave nova** vende a mesma coisa duas vezes.
:::

## Response

STATUS 201

:::info O `POST` responde `201` **sempre**
Uma recusa de negócio é um recurso criado, não uma falha da chamada: o pedido nasce com `status: "rejected"` e os motivos em `decline_reasons`, ainda em `201`. **Ramifique pelo `status`, nunca pela classe HTTP.** O envelope de erro fica reservado para chamadas que não chegaram a uma decisão.
:::

### Pedido criado (`awaiting_payment`)

```json title="Response Body — pedido criado"
{
  "order_key": "5e2b3f60-7c4b-4c8e-9f1a-6d2e8b4a7c90",
  "status": "awaiting_payment",
  "distribution_type": "direct",
  "expires_at": "2026-07-23T13:58:04Z",
  "quote_data": {
    "total_order_amount": 617.28,
    "products": [
      {
        "order_product_key": "7f3a9c2e-0b5d-4e8a-a1c6-9d4b2e7f0a53",
        "product_key": "9d1f8c7a-3b21-4e60-8a2f-1c5d7e9b0a44",
        "product_category": "insurance",
        "insurance_class": {
          "name": "credit_life",
          "class_number": "0977",
          "group_number": "09"
        },
        "regulator_registration": "15414.900388/2015-21",
        "contract_instrument_type": "ticket",
        "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"
        },
        "risk_object": {
          "type": "credit_operation",
          "insurable_value": 50000.00,
          "attributes": {
            "installment_amount": 1050.00,
            "number_of_installments": 48
          }
        },
        "services": [
          {
            "service_key": "0a3c5e7f-2b4d-4a6c-8e0f-1a3b5c7d9e2f",
            "service_type": {
              "code": "credit_life",
              "name": "Prestamista (Credit Life)"
            },
            "service_category": "insurance",
            "regulator_registration": null,
            "gross_premium_amount": 617.28,
            "insured_amount": 50000.00,
            "unit_amount": null,
            "unit_count": null,
            "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"
            }
          }
        ]
      }
    ]
  },
  "payment_data": {
    "payment_method": "pix_automatic",
    "installment_count": 12,
    "installment_amount": 51.44,
    "first_installment_amount": 51.44,
    "first_due_date": "2026-07-23",
    "payment_artifact": {
      "type": "pix_automatic",
      "qr_code_payload": "https://pix.example.qitech.app/r/9f2c1b0e",
      "qr_code_key": "9f2c1b0e-5d47-4a11-9c3e-0b8a7d61f402"
    }
  },
  "customer_document_number": "96969879003"
}
```

| Campo | Tipo | Descrição |
|---|---|---|
| `order_key` | string | Chave única do pedido. |
| `status` | string | `awaiting_payment` no pedido criado. Veja o [ciclo de vida](/documentation/seguros/pedidos/inicio). |
| `distribution_type` | string | Modelo de distribuição da venda. Hoje sempre `direct`. |
| `expires_at` | string | Prazo para o pagamento da primeira parcela: 7 dias a partir da submissão. Vencido o prazo, o pedido expira. |
| `quote_data` | object | O que foi vendido e congelado na submissão: `total_order_amount` e produtos com suas coberturas. É o mesmo bloco, com a mesma forma, retornado na [consulta do pedido](/documentation/seguros/pedidos/consultar_pedido). |
| `quote_data.products[].order_product_key` | string | Chave do produto **dentro do pedido**. É a chave de correlação com a apólice gerada na emissão. |
| `payment_data` | object | A cobrança criada para o pedido. Veja abaixo. |
| `customer_document_number` | string | Documento do segurado. |

#### Objeto `payment_data` (resposta)

| Campo | Tipo | Descrição |
|---|---|---|
| `payment_method` | string | Meio de pagamento congelado — `pix_automatic`. |
| `installment_count` | integer | Quantidade de parcelas. |
| `installment_amount` | number | Valor de cada parcela. |
| `first_installment_amount` | number | Valor da primeira parcela — absorve o resíduo de arredondamento, de modo que `first_installment_amount + (installment_count - 1) × installment_amount` reconcilia exatamente com `total_order_amount`. |
| `first_due_date` | string | Vencimento da primeira parcela (`AAAA-MM-DD`). |
| `payment_artifact` | object | O artefato Pix a ser entregue ao segurado: `type`, `qr_code_payload` (a **URL** do Pix, não o copia-e-cola EMV) e `qr_code_key`. **Retornado apenas enquanto o pedido está `awaiting_payment`** — em um pedido emitido ou terminal o QR está gasto e não é reexposto. |

### Pedido recusado (`rejected`)

Quando a precificação recusa qualquer linha, o pedido nasce `rejected`. A submissão é **tudo-ou-nada**: uma linha recusada recusa o pedido inteiro, nenhuma cobrança é criada e nenhum produto é persistido. Mesmo assim o recurso existe e é consultável pelo `order_key`.

```json title="Response Body — pedido recusado (201)"
{
  "order_key": "b41d90a7-8c22-4f3e-9a10-2d6e4b7c5f81",
  "status": "rejected",
  "decline_reasons": [
    {
      "product_key": "9d1f8c7a-3b21-4e60-8a2f-1c5d7e9b0a44",
      "code": "INELIGIBLE",
      "detail": "age_at_maturity 76 exceeds the maximum 75 for coverage credit_life"
    }
  ]
}
```

| Campo | Tipo | Descrição |
|---|---|---|
| `order_key` | string | Chave do pedido recusado. |
| `status` | string | Sempre `rejected` neste ramo. |
| `decline_reasons` | array | Lista plana de `{ product_key, code, detail }`, uma entrada por falha subjacente — duas coberturas de um mesmo produto violando o espaço de opções geram duas entradas sob o mesmo `code`. Os códigos são os [mesmos da cotação](/documentation/seguros/cotacao/criar_cotacao#motivos-de-rejeicao). `product_key` pode ser `null` para um motivo não atribuível a um produto específico. |

Um pedido `rejected` **não** traz `quote_data` nem `payment_data`: nada foi vendido e não há o que pagar.

## Possíveis erros

Todo erro (`non-2xx`) retorna o corpo padrão `{ "title", "description", "translation", "code" }` — trate programaticamente **apenas** o campo `code`. Recusa de negócio **não** vem por aqui: ela é o `201` com `status: rejected` descrito acima.

| Status | Código | Descrição |
|---|---|---|
| `400` | `QIT000001` | Requisição malformada (schema inválido) — inclusive `customer.date_of_birth` fora do calendário ou no futuro. |
| `401` / `403` | — | Falha de autenticação ou autorização. |
| `409` | `ORD000011` | `request_control_key` já utilizada pela sua integração. Recupere o pedido com `GET /v1/insurance/order?request_control_key=`. |
| `422` | `ORD000020` | Objeto de risco ausente, ou sem `insurable_value` quando o tipo o exige (`credit_operation`/`vehicle`). |
| `422` | `ORD000021` | Produto sem `term`. |
| `422` | `ORD000022` | `term.end_date` anterior ou igual a `term.start_date`. |
| `422` | `ORD000023` | `product_key` repetido no mesmo pedido. |
| `422` | `ORD000024` | Integração inativa — não pode transacionar. |
| `422` | `ORD000025` | Produto sem o bloco `acceptance`. |
| `422` | `ORD000026` | `acceptance.document_number_hash` não corresponde ao `customer.document_number` do pedido. |
| `422` | `ORD000027` | `acceptance.accepted_at` inválido, no futuro ou fora da janela de 24 horas. |
| `422` | `ORD000028` | A sua integração não tem configuração de pagamento e não pode ser cobrada. Contate o time de Integração. |
| `422` | `ORD000029` | O meio de pagamento solicitado não está habilitado para a sua integração. |
| `422` | `ORD000032` | O pedido mistura instrumentos contratuais diferentes — bilhete e apólice não podem ser vendidos no mesmo pedido. |
| `422` | `ORD000033` | O instrumento contratual do produto não está disponível para venda (apenas `ticket` nesta versão). |
| `502` / `504` | `ORD000031` | Falha em uma integração síncrona da submissão (cobrança). Nenhum pedido foi criado. |
| `503` | `ORD000030` | Motor de precificação indisponível — as vendas ficam pausadas. Repita a chamada. |

:::caution Retentativa após `502` / `504` / `503`
Repetir o submit exige **a mesma** `request_control_key` — ou nenhuma. Uma chave nova cria um segundo pedido para a mesma venda.
:::

---

# Início

URL: /documentation/seguros/pedidos/inicio

O **pedido** (`order`) é a unidade de venda do Insurance-as-a-Service: uma submissão que carrega um ou mais produtos, o segurado, o **aceite** que você coletou dele e a forma de pagamento. O pedido nasce aguardando o **pagamento** da primeira parcela. Confirmado o pagamento, o pedido é **emitido** — e cada produto vendido vira uma [apólice](/documentation/seguros/apolices/inicio).

:::info O aceite viaja no próprio pedido
Não há etapa de assinatura hospedada pela QI Tech nesta versão. Você conduz a cerimônia de aceite no seu fluxo e atesta o resultado no bloco `acceptance` de cada produto da submissão. Por isso o pedido nasce já em `awaiting_payment`, e não em um estado de espera por assinatura.
:::

## Ciclo de vida do pedido

![Fluxo de status do pedido, da submissão à emissão, com os desfechos possíveis](/img/diagrams/seguros-pedidos-inicio.svg)

_Como ler o diagrama: **azul** = status intermediário · **verde** = emitido (desfecho de sucesso) · **vermelho** = desfecho sem emissão. Toda transição de status gera um [webhook](/documentation/seguros/pedidos/webhooks)._

| Status | Significado |
|---|---|
| `awaiting_payment` | Pedido criado e precificado; aguardando a confirmação do pagamento da primeira parcela via o `payment_artifact` Pix retornado na submissão. |
| `emitted` | Pagamento confirmado; as apólices do pedido foram disparadas para emissão. Status terminal do pedido — daqui em diante o acompanhamento é pelas [apólices](/documentation/seguros/apolices/inicio). |
| `rejected` | O pedido nasceu rejeitado na submissão porque a precificação recusou ao menos uma linha. Os motivos vêm em `decline_reasons`, no próprio `201`. |
| `expired` | O prazo de 7 dias para pagamento (`expires_at`) venceu sem confirmação. |
| `cancelled` | O pedido foi cancelado pela sua integração antes da emissão. |

### Status reservados

Os enumeradores abaixo existem no modelo de dados mas **não ocorrem nesta versão**. Eles são a razão pela qual você não deve mapear o campo `status` de forma fechada — trate um valor desconhecido como "em andamento" e consulte o pedido.

| Status | Reservado para |
|---|---|
| `awaiting_acceptance` | O fluxo de **apólice** (`contract_instrument_type: policy`), que exige proposta renderizada e assinatura sobre ela. |
| `under_analysis` | Análise cadastral assíncrona (KYC). |
| `declined` | Recusa do segurado em uma cerimônia de assinatura conduzida pela QI Tech. |

:::info O pagamento sempre vence o relógio
A expiração nunca desfaz um pagamento válido: se o pagamento for confirmado enquanto a expiração está sendo processada, o pedido é emitido normalmente. Um pagamento que chegue **depois** de um cancelamento é devolvido ao pagador automaticamente.
:::

## O que congela na submissão

No momento da submissão, o pedido congela tudo o que foi precificado: produtos, coberturas, prêmios, importâncias seguradas, vigências, objetos de risco e o aceite atestado. Esses dados são imutáveis e são exatamente o que as apólices herdarão na emissão — uma reprecificação posterior do catálogo nunca afeta um pedido já submetido.

## Pedido × apólice

- Um pedido vende **N produtos**; a emissão gera **uma apólice por produto**, correlacionada pelo `order_product_key`.
- O pedido **não** retorna apólices nas consultas: descubra as apólices de um pedido emitido com [`GET /v1/insurance/policies?order_key=`](/documentation/seguros/apolices/listar_apolices).
- Cancelar um pedido **antes** da emissão desfaz a venda inteira; cancelar **depois** da emissão dispara o cancelamento de cada apólice individualmente ([Cancelar pedido](/documentation/seguros/pedidos/cancelar_pedido)).

## Endpoints

| Endpoint | Descrição |
|---|---|
| [`POST /v1/insurance/order`](/documentation/seguros/pedidos/criar_pedido) | Cria e submete o pedido. |
| [`GET /v1/insurance/order`](/documentation/seguros/pedidos/listar_pedidos) | Lista os pedidos da sua integração. |
| [`GET /v1/insurance/orders/{order_key}`](/documentation/seguros/pedidos/consultar_pedido) | Detalha um pedido. |
| [`POST /v1/insurance/orders/{order_key}/cancel`](/documentation/seguros/pedidos/cancelar_pedido) | Cancela um pedido (pré ou pós-emissão). |

:::caution Rota de coleção no singular
A rota de coleção é `/v1/insurance/order` (singular) e carrega tanto a criação (`POST`) quanto a listagem (`GET`). As rotas endereçadas por chave usam o plural: `/v1/insurance/orders/{order_key}`.
:::

---

# Listar pedidos

URL: /documentation/seguros/pedidos/listar_pedidos

Retorna a lista paginada dos pedidos da sua integração, do mais recente para o mais antigo.

## Request

ENDPOINT /v1/insurance/order
MÉTODO GET

### Query params

| Parâmetro | Tipo | Obrigatoriedade | Descrição |
|---|---|---|---|
| `page` | integer | opcional | Número da página. Padrão: `1`. |
| `page_size` | integer | opcional | Registros por página. Padrão: `50`. Máximo: `200`. |
| `status` | string | opcional | Filtra pelo status do pedido (ex.: `awaiting_payment`). |
| `customer_document_number` | string | opcional | Filtra pelo documento do segurado. |
| `request_control_key` | string | opcional | Filtra pela sua chave de idempotência. |
| `distribution_type` | string | opcional | Filtra pelo modelo de distribuição (ex.: `direct`). |
| `created_from` | string | opcional | Data/hora mínima de criação (ISO 8601). |
| `created_to` | string | opcional | Data/hora máxima de criação (ISO 8601). |

```python title="Exemplo de chamada"
GET /v1/insurance/order?page=1&page_size=50&status=awaiting_payment&created_from=2026-07-01T00:00:00Z
```

## Response

STATUS 200

```json title="Response Body"
{
  "items": [
    {
      "order_key": "5e2b3f60-7c4b-4c8e-9f1a-6d2e8b4a7c90",
      "status": "awaiting_payment",
      "product_keys": ["9d1f8c7a-3b21-4e60-8a2f-1c5d7e9b0a44"],
      "customer_document_number": "96969879003",
      "total_order_amount": 617.28,
      "created_at": "2026-07-14T12:00:00Z"
    }
  ],
  "page": 1,
  "page_size": 50,
  "total": 137
}
```

### Atributos da resposta

| Campo | Tipo | Descrição |
|---|---|---|
| `items` | array | Lista de resumos de pedido. |
| `page` | integer | Página atual. |
| `page_size` | integer | Tamanho da página solicitado. |
| `total` | integer | Total de pedidos que atendem aos filtros. |

#### Objeto em `items`

| Campo | Tipo | Descrição |
|---|---|---|
| `order_key` | string | Chave única do pedido. |
| `status` | string | Status atual. Veja o [ciclo de vida](/documentation/seguros/pedidos/inicio). |
| `product_keys` | array | Chaves dos produtos vendidos no pedido. |
| `customer_document_number` | string | Documento do segurado. |
| `total_order_amount` | number | Valor total do pedido (soma dos prêmios brutos dos produtos). |
| `created_at` | string | Data/hora da submissã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 |
|---|---|---|
| `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` / `503` | `QIT000500` | Erro interno ou serviço indisponível — seguro repetir a chamada. |

---

# Webhooks do Pedido

URL: /documentation/seguros/pedidos/webhooks

A cada transição de status do pedido, a QI Tech envia um webhook do tipo `insurance.order.status_changed` para a URL de callback configurada. O evento identifica o pedido pelo `order_key` e carrega o novo status.

:::info Webhooks são notificações, não a fonte da verdade
A entrega dos webhooks é do tipo *best-effort*. Não dependa exclusivamente deles: um evento perdido é sempre recuperável consultando o pedido em [`GET /v1/insurance/order`](/documentation/seguros/pedidos/listar_pedidos).
:::

:::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.order.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 |
|---|---|---|
| `order_key` | string | Chave do pedido. |
| `status` | string | Novo status do pedido. |
| `customer_document_number` | string | Documento do segurado. |
| `reason` | array / string | Motivo, quando aplicável: a lista de `decline_reasons` em `rejected`, o motivo informado em `cancelled`. `null` nos demais casos — a chave está sempre presente. |
| `product_count` | integer | Quantidade de produtos do pedido. No evento de `emitted`, é o número de apólices que serão emitidas. |

```json title="Estrutura padrão do webhook"
{
  "webhook_type": "insurance.order.status_changed",
  "webhook_datetime": "2026-07-16T14:03:22Z",
  "data": {
    "order_key": "5e2b3f60-7c4b-4c8e-9f1a-6d2e8b4a7c90",
    "status": "status",
    "customer_document_number": "96969879003",
    "reason": null
  }
}
```

## Eventos por status

### Pedido criado

STATUS awaiting_payment

Enviado quando a submissão é concluída com sucesso. O pedido aguarda o pagamento da primeira parcela pelo `payment_artifact` Pix retornado na [criação do pedido](/documentation/seguros/pedidos/criar_pedido).

---

### Pedido recusado

STATUS rejected

Enviado quando o pedido nasce recusado na submissão porque a precificação recusou ao menos uma linha. O campo `reason` traz a lista de `decline_reasons`.

---

### Pedido emitido

STATUS emitted

Enviado quando o pagamento é confirmado e a emissão das apólices é disparada. O campo `product_count` indica quantas apólices serão criadas — **o evento não carrega as chaves das apólices**, porque elas são emitidas de forma assíncrona logo em seguida. Descubra-as com [`GET /v1/insurance/policies?order_key=`](/documentation/seguros/apolices/listar_apolices) ou aguarde os [webhooks de apólice](/documentation/seguros/apolices/webhooks).

```json title="Webhook Body"
{
  "webhook_type": "insurance.order.status_changed",
  "webhook_datetime": "2026-07-16T14:03:22Z",
  "data": {
    "order_key": "5e2b3f60-7c4b-4c8e-9f1a-6d2e8b4a7c90",
    "status": "emitted",
    "customer_document_number": "96969879003",
    "reason": null,
    "product_count": 2
  }
}
```

---

### Pedido expirado

STATUS expired

Enviado quando o prazo de pagamento (`expires_at`) vence sem confirmação. A expiração nunca desfaz um pagamento válido: se o pagamento for confirmado antes do processamento da expiração, o pedido é emitido normalmente e este evento não ocorre.

---

### Pedido cancelado

STATUS cancelled

Enviado quando o [cancelamento pré-emissão](/documentation/seguros/pedidos/cancelar_pedido) é concluído. O campo `reason` traz o motivo informado no cancelamento, quando houver. O cancelamento **pós-emissão** não gera este evento — o pedido permanece `emitted` e o acompanhamento é pelos [webhooks de apólice](/documentation/seguros/apolices/webhooks).

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