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

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

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

Response Body

{
  "order_key": "5e2b3f60-7c4b-4c8e-9f1a-6d2e8b4a7c90",
  "status": "cancelled"
}

Pós-emissão

STATUS

202

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 ou pela consulta de apólice.

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.

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.