Cancelar apólice

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

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

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 com status canceled, e pode ser acompanhada pela consulta de apólice.

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.