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

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.

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, então você descobre o instrumento antes de coletar o aceite.

Request

ENDPOINT

/v1/insurance/order

MÉTODO

POST

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

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

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

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)

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

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

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.