Pular para o conteúdo principal

Introdução

O Insurance-as-a-Service da QI Tech permite que parceiros distribuam produtos de seguro por API: consulta do catálogo de produtos habilitados, cotação, venda (pedido com aceite e pagamento do segurado), acompanhamento das apólices emitidas e do repasse financeiro das comissões.

Essa documentação descreve os fluxos, endpoints e estruturas de dados da jornada completa de distribuição de seguros.

Obs.: Em caso de dúvidas em qualquer etapa do processo, favor entrar em contato com api@qitech.com.br detalhando seu problema/dúvida que te auxiliaremos.

Visão geral da jornada​

  1. Catálogo — consulte os produtos de seguro que a sua integração está habilitada a distribuir, com as coberturas, limites e a sua faixa de comissão (Catálogo de Produtos).
  2. Cotação — precifique uma seleção de produtos e coberturas para um cliente, sem criar nenhum recurso (Criar cotação), e descubra a faixa de preço vendável de cada produto (Simular faixa de preço).
  3. Pedido — submeta a venda, já com o aceite que você coletou do segurado. O pedido nasce aguardando o pagamento da primeira parcela; confirmado o pagamento, o pedido é emitido (Pedidos).
  4. Apólices — a emissão do pedido gera uma apólice por produto vendido, emitida junto à seguradora. Consulte e cancele apólices individualmente (Apólices). Superfície ainda não publicada.
  5. Financeiro — acompanhe o seu saldo de comissão, o extrato de movimentações e os repasses realizados (Financeiro). Superfície ainda não publicada.

Cada etapa relevante notifica a sua URL de callback por webhooks de pedido e webhooks de apólice.

Ambientes (Hosts)​

O Insurance-as-a-Service possui dois ambientes, SANDBOX e PRODUÇÃO. Ambos possuem comportamento idêntico, porém o ambiente de SANDBOX opera com valores e emissões totalmente fictícios, enquanto o de Produção realiza transações e emissões válidas.

AmbienteHost
Sandboxhttps://api.sandbox.insurance.qitech.app
Produçãohttps://api.insurance.qitech.app
Aviso Importante!

Não devem ser usados dados reais de pessoas físicas e/ou jurídicas nos ambientes de Sandbox da QI Tech.

Convenções da API​

  • Os paths são versionados com o segmento de versão liderando o caminho (ex.: /v1/insurance/order, /v1/product_catalog/products).
  • Todos os recursos são endereçados por chaves públicas UUID (order_key, policy_key, product_key), nunca por identificadores numéricos internos.
  • Os paths de coleção nem sempre são plurais: a criação e a listagem de pedidos vivem em /v1/insurance/order (singular), enquanto as rotas por chave usam /v1/insurance/orders/{order_key}. Siga o path indicado na página de cada endpoint.
  • Valores monetários trafegam como número JSON com 2 casas decimais (ex.: 312.48, nunca string), sempre em BRL e sempre brutos (com IOF). Taxas e percentuais são números com 4 casas em (0, 1] (ex.: 0.1000). Identificadores numéricos com zeros à esquerda significativos (documentos, códigos de ramo) permanecem strings.
  • Status são strings de enumerador em caixa baixa (ex.: awaiting_payment, emitted). Não mapeie o conjunto de forma fechada — veja os status reservados.
  • Vigências são objetos aninhados term: { "start_date", "end_date" } — por produto e por cobertura.
  • Datas seguem AAAA-MM-DD e data-hora segue ISO 8601 (2026-07-16T14:03:22Z).
  • Listagens usam paginação por offset, mas a forma varia por superfície — confira sempre a página do endpoint. Pedidos usam page / page_size (padrão 50, máximo 200) e devolvem { items, page, page_size, total }; o catálogo de produtos usa page / rows_per_page (padrão 50) e devolve { data, pagination { current_page, next_page, rows_per_page } }, sem total.
  • Todo erro (non-2xx) retorna o corpo padrão { "title", "description", "translation", "code" }. O code é o único campo para tratamento programático — title/description/translation podem mudar sem aviso.
  • O escopo de acesso é sempre o da sua integração: uma chave de outro parceiro é indistinguível de uma chave inexistente e retorna 404.

Para começar​

A autenticação segue o padrão QI Tech de requisições assinadas, o mesmo utilizado nas demais linhas de produto. Veja Autenticação.

Antes de consumir os endpoints desta documentação, complete os passos abaixo em ambiente de sandbox:

  1. Entrar em contato com o time de Integração (api@qitech.com.br) para iniciar o onboarding da sua integração.
  2. Gerar o par de chaves e enviar a sua chave pública por meio seguro para receber as credenciais de integração.
  3. Realizar o teste de autenticação.
  4. Configurar a URL de recebimento de webhooks.