Overview

The order (order) is the unit of sale of Insurance-as-a-Service: a submission carrying one or more products, the insured person, the acceptance you collected from them and the payment method. The order is born awaiting the payment of the first installment. Once payment is confirmed, the order is emitted — and each sold product becomes a policy.

Acceptance travels inside the order

There is no QI Tech-hosted signature step in this version. You run the acceptance ceremony in your own flow and attest the outcome in each product's acceptance block on the submission. That is why the order is born already in awaiting_payment, and not in a state waiting for a signature.

Order lifecycle

How to read the diagram: blue = intermediate status · green = emitted (successful outcome) · red = outcome without issuance. Every status transition emits a webhook.

Status	Meaning
awaiting_payment	Order created and priced; awaiting confirmation of the first installment payment through the Pix payment_artifact returned on submission.
emitted	Payment confirmed; the order's policies were dispatched for issuance. Terminal status of the order — from here on tracking happens through the policies.
rejected	The order was born rejected at submission because pricing refused at least one line. The reasons come in decline_reasons, inside the 201 itself.
expired	The 7-day payment deadline (expires_at) elapsed without confirmation.
cancelled	The order was cancelled by your integration before issuance.

Reserved statuses

The enumerators below exist in the data model but do not occur in this version. They are the reason you must not map the status field as a closed set — treat an unknown value as "in progress" and read the order back.

Status	Reserved for
awaiting_acceptance	The policy flow (contract_instrument_type: policy), which requires a rendered proposal and a signature over it.
under_analysis	Asynchronous registry (KYC) analysis.
declined	Refusal by the insured person in a signature ceremony run by QI Tech.

Payment always beats the clock

Expiry never undoes a valid payment: if payment is confirmed while expiry is being processed, the order is emitted normally. A payment that arrives after a cancellation is automatically returned to the payer.

What freezes at submission

At submission, the order freezes everything that was priced: products, coverages, premiums, insured amounts, terms, risk objects and the attested acceptance. This data is immutable and is exactly what the policies inherit at issuance — a later catalog re-pricing never affects an already-submitted order.

Order × policy

• One order sells N products; issuance generates one policy per product, correlated by order_product_key.
• The order does not return policies on its reads: discover an emitted order's policies with GET /v1/insurance/policies?order_key=.
• Cancelling an order before issuance undoes the whole sale; cancelling after issuance triggers the cancellation of each policy individually (Cancel order).

Endpoints

Endpoint	Description
POST /v1/insurance/order	Creates and submits the order.
GET /v1/insurance/order	Lists your integration's orders.
GET /v1/insurance/orders/{order_key}	Reads one order in detail.
POST /v1/insurance/orders/{order_key}/cancel	Cancels an order (pre- or post-issuance).

Singular collection route

The collection route is /v1/insurance/order (singular) and carries both the creation (POST) and the listing (GET). The key-addressed routes use the plural: /v1/insurance/orders/{order_key}.