Consultar apólice

Retorna o detalhe de uma apólice: identidade e chaves de correlação, status, número da apólice na seguradora, a classificação do produto, a decomposição do prêmio (bruto, IOF e líquido), a vigência, as coberturas efetivas e a trilha de eventos.

Request

ENDPOINT

/v1/insurance/policies/{policy_key}

MÉTODO

GET

Path params

Parâmetro	Tipo	Obrigatoriedade	Descrição
policy_key	string	obrigatório	Chave da apólice, obtida na listagem por pedido ou nos webhooks de apólice.

Response

STATUS

200

Response Body

{
  "policy_key": "0b6e7c1a-9a4e-4c1e-b1d4-2f5a8c9e0d31",
  "order_key": "5e2b3f60-7c4b-4c8e-9f1a-6d2e8b4a7c90",
  "provider_product_key": "9d1f8c7a-3b21-4e60-8a2f-1c5d7e9b0a44",
  "provider_key": "c4a2e8b0-1f6d-4e3a-9c7b-5d0a2e8f4b61",
  "status": "issued",
  "external_policy_number": "APL-2026-000123",
  "customer_document_number": "96969879003",
  "product_category": "insurance",
  "insurance_class": {
    "name": "credit_life",
    "class_number": "0977",
    "group_number": "09"
  },
  "regulator_registration": "15414.900388/2015-21",
  "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"
  },
  "effective_services": [
    {
      "effective_service_key": "7f3a9c2e-0b5d-4e8a-a1c6-9d4b2e7f0a53",
      "provider_service_key": "0a3c5e7f-2b4d-4a6c-8e0f-1a3b5c7d9e2f",
      "service_type": {
        "code": "credit_life",
        "name": "Prestamista (Credit Life)"
      },
      "service_category": "insurance",
      "regulator_registration": null,
      "insured_amount": 150000.00,
      "gross_premium_amount": 617.28,
      "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"
      }
    }
  ],
  "events": [
    {
      "new_status": "issuance_requested",
      "agent_type": "system",
      "created_at": "2026-07-16T14:03:25.481Z"
    },
    {
      "new_status": "issued",
      "agent_type": "provider",
      "created_at": "2026-07-16T15:00:00.000Z"
    }
  ]
}

Atributos da resposta

Campo	Tipo	Descrição
policy_key	string	Chave única da apólice.
order_key	string	Chave do pedido que originou a apólice.
provider_product_key	string	Chave do produto no catálogo.
provider_key	string	Chave da seguradora emissora.
status	string	Status atual. Veja o ciclo de vida.
external_policy_number	string	Número da apólice na seguradora. null até a emissão ser confirmada (issued).
customer_document_number	string	Documento do segurado.
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. class_number e group_number são strings — os zeros à esquerda são significativos.
regulator_registration	string	Registro do produto no regulador (ex.: processo SUSEP).
gross_premium_amount	number	Prêmio bruto (o valor pago pelo segurado), com IOF.
iof_amount	number	Componente de IOF do prêmio.
net_premium_amount	number	Prêmio líquido (bruto menos IOF).
term	object	Vigência da apólice: { start_date, end_date }.
effective_services	array	Coberturas efetivas da apólice.
events	array	Trilha de transições de status, em ordem cronológica — é dela que se derivam os instantes do ciclo de vida (emissão, solicitação de cancelamento, cancelamento).

Objeto em effective_services

Campo	Tipo	Descrição
effective_service_key	string	Chave única da cobertura efetiva.
provider_service_key	string	Chave da cobertura no catálogo.
service_type	object	Tipo da cobertura: { code, name }.
service_category	string	Categoria da cobertura: insurance, capitalization ou benefit.
regulator_registration	string	Registro próprio da cobertura no regulador. null quando herda o do produto.
insured_amount	number	Importância segurada contratada.
gross_premium_amount	number	Prêmio bruto da cobertura.
deductible_data	object	Franquia contratada: { deductible_type, value }.
waiting_period_days	integer	Carência em dias.
service_attributes	object	Atributos fixos da cobertura.
term	object	Vigência da cobertura: { start_date, end_date }.

Objeto em events

Campo	Tipo	Descrição
new_status	string	O status assumido na transição.
agent_type	string	Quem causou a transição: requester (sua integração), provider (seguradora), system (automático) ou operator (operação QI Tech).
created_at	string	Instante da transiçã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
401 / 403	—	Falha de autenticação ou autorização.
404	POL000001	Apólice inexistente ou pertencente a outra integração — os casos são indistinguíveis.
429	—	Limite de requisições excedido — repita com backoff.
500	QIT000500	Erro interno — seguro repetir a chamada.
503	POL000030	Serviço indisponível — seguro repetir a chamada.