Início
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.
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
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.
| 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. |
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. |
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=. - 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).
Endpoints
| Endpoint | Descrição |
|---|---|
POST /v1/insurance/order | Cria e submete o pedido. |
GET /v1/insurance/order | Lista os pedidos da sua integração. |
GET /v1/insurance/orders/{order_key} | Detalha um pedido. |
POST /v1/insurance/orders/{order_key}/cancel | Cancela um pedido (pré ou pós-emissão). |
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}.