Criar cotação

Precifica uma seleção de produtos e coberturas para um cliente. A cotação é uma calculadora: nada é persistido e nenhum recurso é criado. O pedido usa exatamente a mesma lista products[] e é reprecificado com o mesmo motor no momento da submissão.

A cotação é indicativa

Cotação e pedido rodam contra a configuração vigente — não há token de cotação, snapshot de tarifa nem prazo de validade. Se a tarifa ou a configuração do produto mudar entre a cotação e a submissão, o preço muda: o preço calculado na submissão do pedido é o que vale.

Uma cotação pode combinar vários produtos, cada um segurando o seu próprio objeto de risco. O caso típico: um carro vendido com financiamento gera um pedido com o produto prestamista (objeto de risco = a operação de crédito) e o produto auto (objeto de risco = o veículo).

Request

ENDPOINT

/v1/insurance/quote

MÉTODO

POST

Para produtos de prateleira — vendidos como estão, com as coberturas padrão e a comissão padrão da sua integração — a linha do produto precisa apenas de product_key, term e risk_object. É o cenário ideal para quem vende produtos fixos, sem personalização:

Request Body — produto de prateleira

{
  "products": [
    {
      "product_key": "9d1f8c7a-3b21-4e60-8a2f-1c5d7e9b0a44",
      "term": {
        "start_date": "2026-07-16",
        "end_date": "2028-07-15"
      },
      "risk_object": {
        "type": "credit_operation",
        "insurable_value": 50000.00,
        "attributes": {
          "installment_amount": 1050.00,
          "number_of_installments": 48
        }
      }
    }
  ],
  "customer": {
    "date_of_birth": "1987-03-22",
    "occupation_code": "211205"
  }
}

Com services omitido, todas as coberturas com configuração padrão da sua integração são preenchidas automaticamente; com commission_data omitido, vale o default_rate da faixa commission_bounds do produto.

Para personalizar a seleção — escolher coberturas, importância segurada, franquia, carência ou a comissão — envie services e commission_data explicitamente:

Request Body — seleção personalizada

{
  "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": "2028-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
        }
      }
    }
  ],
  "customer": {
    "date_of_birth": "1987-03-22",
    "occupation_code": "211205"
  }
}

Atributos do request

Campo	Tipo	Obrigatoriedade	Descrição
products	array	obrigatório	A seleção de produtos a precificar, campo de topo do request — o mesmo formato usado no pedido. Um item por produto.
customer	object	opcional	Dados do segurado usados na precificação e na avaliação de elegibilidade, em objeto plano (sem wrapper). Quando omitido, a elegibilidade não é avaliada (eligibility retorna not_evaluated) — e produtos cuja tarifa depende de dados do cliente são rejeitados com NOT_PRICEABLE.

Objeto em products

Campo	Tipo	Obrigatoriedade	Descrição
product_key	string	obrigatório	Chave do produto no catálogo.
commission_data	object	opcional	A forma de comissão desejada (veja abaixo). Quando omitida, vale o default_rate da faixa commission_bounds do produto.
term	object	obrigatório	Vigência do produto, em datas absolutas: { "start_date": "AAAA-MM-DD", "end_date": "AAAA-MM-DD" }. Obrigatório em todo item — não há forma por duração nem vigência padrão da seleção. Produtos do mesmo pedido podem ter vigências diferentes.
services	array	opcional	Coberturas explícitas. Quando omitido ou vazio, todas as coberturas com configuração padrão da sua integração são preenchidas automaticamente.
risk_object	object	condicional	O objeto que este produto segura. Obrigatório para produtos de risco valorado (credit_operation, vehicle); omitido quando o objeto do seguro é a própria pessoa (person).

Objeto commission_data

Campo	Tipo	Obrigatoriedade	Descrição
commission_type	string	obrigatório	percentage_of_gross_premium (taxa sobre o prêmio bruto), monetary_amount (comissão em R$ fixo, valor-alvo) ou total_gross_premium_amount (preço final desejado ao cliente, valor-alvo). As três formas são mutuamente exclusivas.
value	number	obrigatório	O valor da forma escolhida: taxa com 4 casas (ex.: 0.1000), valor em R$ (ex.: 61.73) ou preço total (ex.: 650.00).

Em qualquer forma, a taxa efetiva resultante é validada contra a faixa commission_bounds do produto — violação rejeita a linha com OUT_OF_BOUNDS_COMMISSION. Nas formas por valor (monetary_amount, total_gross_premium_amount), o valor é um alvo: o realizado pode variar centavos por arredondamento.

Objeto em services

Campo	Tipo	Obrigatoriedade	Descrição
service_key	string	obrigatório	Chave da cobertura no catálogo. É o único campo obrigatório do item: omitindo os demais, vale a sua configuração padrão para a cobertura.
insured_amount_basis	string	condicional	Base da importância segurada: monetary_amount, percentage_of_risk_value ou unit_amount_times_count. Informar a base torna obrigatório o campo de valor correspondente.
insured_amount	number	condicional	Importância segurada em reais. Obrigatório quando a base é monetary_amount.
insured_amount_percentage	number	condicional	Percentual do valor do objeto de risco, em (0, 1] (1.0000 = 100%). Obrigatório quando a base é percentage_of_risk_value; resolvido contra o insurable_value do objeto de risco da linha.
unit_amount	number	condicional	Valor por unidade de indenização (ex.: R$ 100 por diária). Obrigatório, junto com unit_count, quando a base é unit_amount_times_count. Deve pertencer ao envelope indemnity_unit_options da cobertura.
unit_count	integer	condicional	Quantidade de unidades de indenização (ex.: 60 diárias). Obrigatório, junto com unit_amount, quando a base é unit_amount_times_count.
deductible_data	object	opcional	Franquia, na forma tipada { "deductible_type": "monetary_amount", "value": 1500.00 }. O deductible_type deve ser o mesmo do envelope deductible_options da cobertura, e o valor deve pertencer ao espaço de opções.
waiting_period_days	integer	opcional	Carência em dias, dentro das waiting_period_options da cobertura.

Objeto risk_object

Campo	Tipo	Obrigatoriedade	Descrição
type	string	obrigatório	Tipo do objeto de risco: credit_operation, vehicle ou person.
insurable_value	number	condicional	Valor do objeto de risco. Obrigatório para credit_operation e vehicle; não se aplica a person. Limita a importância segurada das coberturas atreladas ao valor do risco — coberturas de limite estipulado respeitam apenas o próprio maximum_insured_amount.
attributes	object	opcional	Atributos do objeto de risco usados na tarifação, específicos por ramo (ex.: para uma operação de crédito, installment_amount e number_of_installments).

Objeto customer

O objeto é plano — não há wrapper data.

Campo	Tipo	Obrigatoriedade	Descrição
document_number	string	opcional	CPF ou CNPJ do segurado.
name	string	opcional	Nome completo.
email	string	opcional	E-mail.
phone_number	string	opcional	Telefone no formato E.164.
date_of_birth	string	opcional	Data de nascimento do segurado, no formato YYYY-MM-DD. A idade usada na precificação e nas regras de elegibilidade (ex.: idade máxima no fim da vigência) é derivada dela a cada chamada — não existe campo de idade.
occupation_code	string	opcional	Código de ocupação do segurado (CBO).
address	object	opcional	Endereço do segurado, na mesma forma usada no pedido.

Response

STATUS

200

Response Body

{
  "total_order_amount": 617.28,
  "products": [
    {
      "product_key": "9d1f8c7a-3b21-4e60-8a2f-1c5d7e9b0a44",
      "name": "Prestamista Master",
      "provider_name": "QI Seguradora",
      "product_category": "insurance",
      "insurance_class": {
        "name": "credit_life",
        "class_number": "0977",
        "group_number": "09"
      },
      "contract_instrument_type": "ticket",
      "regulator_registration": "15414.900388/2015-21",
      "result": "priced",
      "term": {
        "start_date": "2026-07-16",
        "end_date": "2028-07-15"
      },
      "gross_premium_amount": 617.28,
      "iof_amount": 2.35,
      "net_premium_amount": 614.93,
      "services": [
        {
          "service_key": "0a3c5e7f-2b4d-4a6c-8e0f-1a3b5c7d9e2f",
          "service_type": {
            "code": "credit_life",
            "name": "Prestamista (Credit Life)"
          },
          "service_category": "insurance",
          "regulator_registration": null,
          "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": {},
          "gross_premium_amount": 617.28
        }
      ]
    }
  ],
  "eligibility": "eligible"
}

Atributos da resposta

Campo	Tipo	Descrição
total_order_amount	number	Soma dos prêmios brutos dos produtos precificados (priced), com IOF.
products	array	Resultado por produto. Cada linha é avaliada de forma independente: um produto rejeitado nunca contamina os demais na cotação (no pedido, qualquer linha rejeitada recusa a submissão inteira, que retorna erro 422).
eligibility	string	Veredito de elegibilidade da cotação: eligible, declined (alguma regra de elegibilidade reprovou) ou not_evaluated (o customer não foi enviado — não é uma aprovação).

Objeto em products

Campo	Tipo	Descrição
product_key	string	Chave do produto avaliado.
name / provider_name	string	Nome comercial do produto e da seguradora.
product_category	string	Categoria do produto: insurance, capitalization ou benefit.
insurance_class	object	Ramo do seguro: { name, class_number, group_number }. null para produtos não securitários.
contract_instrument_type	string	Instrumento contratual do produto: ticket (bilhete) ou policy (apólice). Ecoado aqui para que você conheça o instrumento — e portanto quais métodos de aceite são válidos — antes de coletar o aceite no pedido.
regulator_registration	string	Registro do produto no regulador.
result	string	priced (precificado) ou rejected (rejeitado). Presente em toda linha.
term	object	A vigência que você enviou, ecoada. Presente quando priced.
gross_premium_amount	number	Prêmio bruto do produto, com IOF — soma exata dos prêmios das coberturas. Presente quando priced.
iof_amount	number	IOF do produto. Presente quando priced.
net_premium_amount	number	Prêmio líquido do produto, sem IOF. Presente quando priced.
services	array	Coberturas precificadas, com o prêmio de cada uma. Presente quando priced.
decline_reasons	array	Motivos da rejeição, um item { code, detail } por falha subjacente — duas coberturas da mesma linha violando o espaço de opções geram duas entradas sob o mesmo code. Presente apenas quando rejected.

Objeto em services

Campo	Tipo	Descrição
service_key	string	Chave da cobertura.
service_type	object	Tipo da cobertura: { code, name }.
service_category	string	Categoria da cobertura: insurance, capitalization ou benefit.
regulator_registration	string	Registro SUSEP próprio da cobertura. null quando a cobertura herda o registro do produto.
insured_amount	number	Importância segurada resolvida — o percentual já aplicado sobre o valor do objeto de risco, o par por unidade já multiplicado. Você nunca a recalcula.
unit_amount	number	Valor por unidade de indenização. null quando a cobertura não é precificada por unidade.
unit_count	integer	Quantidade de unidades de indenização. null quando a cobertura não é precificada por unidade.
deductible_data	object	Franquia aplicada: { deductible_type, value }. null quando a cobertura não tem franquia.
waiting_period_days	integer	Carência aplicada, em dias. null quando a cobertura não tem carência — que é diferente de uma carência de 0 dias.
service_attributes	object	Atributos fixos da cobertura, ecoados do catálogo.
gross_premium_amount	number	Prêmio bruto da cobertura, arredondado em 2 casas.

Motivos de rejeição

Quando result é rejected, a linha traz apenas product_key, result e decline_reasons — nada é oferecido, então nada é descrito: sem name, sem classificação, sem term, sem prêmios e sem services. Ramifique sempre pelo result, nunca pela presença de um campo.

A avaliação é por estágios (estrutura → precificação → elegibilidade): os motivos retornados são sempre do mesmo estágio — o primeiro que reprovar — coletados por completo.

Linha rejeitada

{
  "product_key": "9d1f8c7a-3b21-4e60-8a2f-1c5d7e9b0a44",
  "result": "rejected",
  "decline_reasons": [
    {
      "code": "OUT_OF_OPTION_SPACE",
      "detail": "deductible 2000.00 is not in the option list for coverage credit_life"
    }
  ]
}

Código	Significado
NOT_ENTITLED	A sua integração não está habilitada para vender este produto.
INACTIVE_PRODUCT	O produto está inativo (ou a chave é desconhecida).
INACTIVE_SERVICE	Uma cobertura selecionada está inativa.
UNKNOWN_SERVICE	Uma service_key não pertence a este produto.
MISSING_MANDATORY_SERVICE	A seleção omite uma cobertura obrigatória do produto.
DEPENDENCY_VIOLATION	A seleção viola as dependências entre coberturas (include/exclude).
OUT_OF_OPTION_SPACE	Importância segurada, franquia ou carência fora do espaço de opções da cobertura — inclusive tipo divergente do envelope, valor fora da list/range/step, ou valor enviado para uma cobertura sem franquia/carência (envelope null).
INVALID_INSURED_AMOUNT_BASIS	A base de importância segurada não é compatível com a linha — ex.: cobertura atrelada ao valor do risco em uma linha sem insurable_value. Vale para qualquer base.
NOT_PRICEABLE	O motor não conseguiu produzir um preço: um insumo da tarifa não é resolvível (ex.: a tarifa depende de dados do customer e ele não foi enviado).
ZERO_PREMIUM	A linha inteira precificou a custo zero. Uma única cobertura gratuita é válida (sai com gross_premium_amount: 0.00); a linha toda a zero é rejeitada.
INELIGIBLE	Uma regra de elegibilidade reprovou (ex.: idade máxima no fim da vigência). O detail do item nomeia a regra e os valores que a reprovaram.
OUT_OF_BOUNDS_COMMISSION	A comissão efetiva derivada de commission_data está fora da faixa commission_bounds do produto.
DELEGATED_UNSUPPORTED	Produto com precificação delegada à seguradora — reservado, ainda não suportado.
STALE_DEFAULT	Uma configuração padrão da sua integração aponta para uma cobertura que não está mais ativa — contate o suporte para atualizar o padrão.

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
400	QIT000001	Requisição malformada: schema inválido, products vazio, produto sem term, base de importância segurada sem o campo de valor correspondente, insurable_value ausente para credit_operation/vehicle, deductible_data estruturalmente malformado, customer.date_of_birth fora do calendário ou no futuro.
401 / 403	—	Falha de autenticação ou autorização.
429	—	Limite de requisições excedido — repita com backoff.
503	—	Motor de precificação indisponível — a cotação falha rápido, sem preço em cache. Repita a chamada.