Garantia Estendida
Garantia Estendida
As APIs da Pottencial permitem que sua empresa realize cotações, propostas e emissões de apólices para os produtos da Pottencial de forma integrada, rápida e segura.
O fluxo para emissão de uma apólice está descrito em passos simples abaixo:
- Passo 1 - Autenticação: Gere um token de autenticação a partir de sua chave de acesso. Esse token será necessário nas demais operações.
- Passo 2 - Solicitar cotação: Envie os dados da cotação e receba os valores do prêmio para os dados informados.
- Passo 3 - Enviar proposta: Quando a cotação estiver pronta, envie os dados para criar uma proposta.
- Passo 4 - Aceitar proposta: Aceite a proposta criada.
- Passo 5 - Emitir apólice: Com a proposta aceita, emita sua apólice.
Pré-requisitos
Antes de começar a utilizar a API, é fundamental compreender os requisitos de autenticação e obter as credenciais necessárias. Certifique-se de revisar a seção de autenticação para garantir uma integração segura e bem-sucedida.Cotações
Solicitar cotação
Permite solicitar uma nova cotação para um produto Pottencial.
Cada produto possui regras específicas de preenchimento, que estão detalhadas em cada um dos campos.
Requisição (Request)
| Url | https://api-sandbox.pottencial.com.br/insurance/v1/{product_key}/quotes | |
| Method | Post | |
| Query | product_key |
Chave de identificação do produto. garantia-estendida |
| Headers | client_id |
Client ID da App. |
| access_token |
Token de acesso gerado para a App. |
|
| Body | Quote | |
Exemplos
Cotação para o produto Garantia Estendida
Para cadastro de cotação para o produto Garantia Estendida é necessário informar um único objeto de risco do tipo ProductRisk.
{
"commissionedAgents": [
{
"documentNumber": "11111111111111",
"role": "Broker",
"commissionPercentage": 0.15,
"isPayer": false
},
{
"documentNumber": "22222222222222",
"address": {
"street": "Av. Raja Gabáglia",
"number": "1143",
"district": "Luxemburgo",
"city": "Belo Horizonte",
"state": "MG",
"zipCode": "30380403",
"complement": "20º andar"
},
"role": "InsuranceAgent",
"commissionPercentage": 0,
"isPayer": true
},
{
"documentNumber": "33333333333333",
"role": "PolicyOwner",
"commissionPercentage": 0.5,
"isPayer": false
}
],
"participants": [
{
"documentNumber": "44444444444444",
"role": "Insured",
"isPayer": false,
"address": {
"street": "Av. Raja Gabáglia",
"number": "1143",
"district": "Luxemburgo",
"city": "Belo Horizonte",
"state": "MG",
"zipCode": "30380403",
"complement": "20º andar"
},
"contact": {
"name": "nome do contato",
"email": "[email protected]",
"phoneNumber": "31999999999"
}
},
{
"documentNumber": "55555555555",
"role": "Beneficiary",
"participationPercentage": 1,
"isPayer": false
}
],
"riskObjects": [
{
"type": "Product",
"coverages": [
{
"key": "premier",
"insuredAmount": 10986.8
}
],
"budgetNumber": "1",
"preventiveMaintenance": true,
"extendedWarrantyHours": 1000,
"signedValue": 3000,
"productDetails": {
"category": 5,
"name": "nome do produto",
"manufacture": "Fabricante",
"model": "Modelo do equipamento",
"year": 2000,
"serialNumber": "Número de série do equipamento",
"chassis": "Número do chassi",
"serviceMeter": "155.55",
"invoiceNumber": "191919",
"guaranteeDateStart": "2023-04-06T00:00:00.000Z",
"guaranteeDateEnd": "2024-04-06T00:00:00.000Z"
},
"paymentConditions": {
"paymentType": "Boleto",
"installments": 6
}
}
]
}
Respostas (Response)
| Status | Descrição | Tipo |
| 200 |
Cotação cadastrada com sucesso. |
Quote |
| 400 |
Os dados da requisição estão inválidos. |
ErrorResult |
| 401 |
Parceiro não autorizado a realizar a operação. |
ErrorResult |
| 500 |
Erro interno da API. Por favor tente novamente mais tarde ou contate o suporte técnico da Pottencial. |
ErrorResult |
Exemplo de resposta da cotação para o produto Garantia Estendida
{
"quoteId": "c03ab663-3d5c-4014-aa5e-cae727103392",
"quoteNumber": 999999,
"createdAt": "2022-12-27",
"status": "Approved",
"commercialPremium": 109.98,
"grossPremium": 99.99,
"iof": 9.99,
"commissionedAgents": [
{
"documentNumber": "11111111111111",
"role": "Broker",
"commissionPercentage": 0.15,
"isPayer": false,
"commissionAmount": 9.99
},
{
"documentNumber": "22222222222222",
"address": {
"street": "Av. Raja Gabáglia",
"number": "1143",
"district": "Luxemburgo",
"city": "Belo Horizonte",
"state": "MG",
"zipCode": "30380403",
"complement": "20º andar"
},
"role": "InsuranceAgent",
"commissionPercentage": 0,
"isPayer": true
},
{
"documentNumber": "33333333333333",
"role": "PolicyOwner",
"commissionPercentage": 0.5,
"isPayer": false
}
],
"participants": [
{
"documentNumber": "44444444444444",
"role": "Insured",
"isPayer": false,
"address": {
"street": "Av. Raja Gabáglia",
"number": "1143",
"district": "Luxemburgo",
"city": "Belo Horizonte",
"state": "MG",
"zipCode": "30380403",
"complement": "20º andar"
},
"contact": {
"name": "nome do contato",
"email": "[email protected]",
"phoneNumber": "31999999999"
}
},
{
"documentNumber": "55555555555",
"role": "Beneficiary",
"participationPercentage": 1,
"isPayer": false
}
],
"riskObjects": [
{
"type": "Product",
"coverages": [
{
"key": "premier",
"insuredAmount": 10986.8
}
],
"budgetNumber": "1",
"preventiveMaintenance": true,
"extendedWarrantyHours": 1000,
"signedValue": 3000,
"productDetails": {
"category": 5,
"name": "nome do produto",
"manufacture": "Fabricante",
"model": "Modelo do equipamento",
"year": 2000,
"serialNumber": "Número de série do equipamento",
"chassis": "Número do chassi",
"serviceMeter": "155.55",
"invoiceNumber": "191919",
"guaranteeDateStart": "2023-04-06T00:00:00.000Z",
"guaranteeDateEnd": "2024-04-06T00:00:00.000Z"
},
"paymentConditions": {
"paymentType": "Boleto",
"installments": 6
}
}
]
}
Consultar cotação
Permite consultar os dados de uma cotação.
Requisição (Request)
| Url | https://api-sandbox.pottencial.com.br/insurance/v1/{product_key}/quotes/{quote_id} | |
| Method | Get | |
| Query | product_key |
Chave de identificação do produto. garantia-estendida |
| quote_id |
ID da cotação para consulta. |
|
| Headers | client_id |
Client ID da App. |
| access_token |
Token de acesso gerado para a App. |
|
Respostas (Response)
| Status | Descrição | Tipo | |
| 200 |
Cotação localizada com sucesso. |
Quote | |
| 400 |
Os dados da requisição estão inválidos. |
ErrorResult | |
| 401 |
Parceiro não autorizado a realizar a operação. |
ErrorResult | |
| 500 |
Erro interno da API. Por favor tente novamente mais tarde ou contate o suporte técnico da Pottencial. |
ErrorResult | |
Exemplo
Consulta de cotação para o produto Garantia Estendida
Para consulta da cotação do produto Garantia Estendida é necessário informar o id da cotação.
{
"quoteId": "c03ab663-3d5c-4014-aa5e-cae727103392",
"quoteNumber": 999999,
"createdAt": "2022-12-27",
"status": "Approved",
"commercialPremium": 109.98,
"grossPremium": 99.99,
"iof": 9.99,
"commissionedAgents": [
{
"documentNumber": "11111111111111",
"role": "Broker",
"commissionPercentage": 0.15,
"isPayer": false,
"commissionAmount": 9.99
},
{
"documentNumber": "22222222222222",
"address": {
"street": "Av. Raja Gabáglia",
"number": "1143",
"district": "Luxemburgo",
"city": "Belo Horizonte",
"state": "MG",
"zipCode": "30380403",
"complement": "20º andar"
},
"role": "InsuranceAgent",
"commissionPercentage": 0,
"isPayer": true
},
{
"documentNumber": "33333333333333",
"role": "PolicyOwner",
"commissionPercentage": 0.5,
"isPayer": false
}
],
"participants": [
{
"documentNumber": "44444444444444",
"role": "Insured",
"isPayer": false,
"address": {
"street": "Av. Raja Gabáglia",
"number": "1143",
"district": "Luxemburgo",
"city": "Belo Horizonte",
"state": "MG",
"zipCode": "30380403",
"complement": "20º andar"
},
"contact": {
"name": "nome do contato",
"email": "[email protected]",
"phoneNumber": "31999999999"
}
},
{
"documentNumber": "55555555555",
"role": "Beneficiary",
"participationPercentage": 1,
"isPayer": false
}
],
"riskObjects": [
{
"type": "Product",
"coverages": [
{
"key": "premier",
"insuredAmount": 10986.8
}
],
"budgetNumber": "1",
"preventiveMaintenance": true,
"extendedWarrantyHours": 1000,
"signedValue": 3000,
"productDetails": {
"category": 5,
"name": "nome do produto",
"manufacture": "Fabricante",
"model": "Modelo do equipamento",
"year": 2000,
"serialNumber": "Número de série do equipamento",
"chassis": "Número do chassi",
"serviceMeter": "155.55",
"invoiceNumber": "191919",
"guaranteeDateStart": "2023-04-06T00:00:00.000Z",
"guaranteeDateEnd": "2024-04-06T00:00:00.000Z"
},
"paymentConditions": {
"paymentType": "Boleto",
"installments": 6
}
}
]
}
Consultar documento da cotação
Essa operação permite consultar o documento a partir do ID da cotação.
Requisição (Request)
| Url | https://api-sandbox.pottencial.com.br/insurance/v1/{product_key}/quotes/{quote_id}/draft | |
| Method | Get | |
| Query | product_key |
Chave de identificação do produto. garantia-estendida |
| quote_id |
ID da cotação para consulta. |
|
| Headers | client_id |
Client ID da App. |
| access_token |
Token de acesso gerado para a App. |
|
Respostas (Response)
| Status | Descrição | Tipo |
| 200 |
Documento da cotação localizado com sucesso. |
BLOB |
| 401 |
Parceiro não autorizado a realizar a operação. |
ErrorResult |
| 404 |
Registro não encontrado. |
ErrorResult |
| 500 |
Erro interno da API. Por favor tente novamente mais tarde ou contate o suporte técnico da Pottencial. |
ErrorResult |
Propostas
Enviar proposta
Permite submeter uma nova proposta para um produto Pottencial. Para envio de uma proposta é necessário primeiramente ter realizado uma cotação a partir da API de cotação.
Requisição (Request)
| Url | https://api-sandbox.pottencial.com.br/insurance/v1/{product_key}/proposals | |
| Method | Post | |
| Query | product_key |
Chave de identificação do produto. garantia-estendida |
| Headers | client_id |
Client ID da App. |
| access_token |
Token de acesso gerado para a App. |
|
| Body | Proposal | |
Exemplos
Proposta
{ "quoteId": "ac721b29-0a5a-44b4-a205-b23288164f40", "policyPeriodStart": "2024-04-06T03:00:00Z", "policyPeriodEnd": "2025-04-06T03:00:00Z", "payment": { "firstDueDate": "2024-10-06T03:00:00Z", "paymentInstructions": "informaçoes da forma de pagamento" } }Respostas (Response)
| Status | Descrição | Tipo |
| 200 |
Proposta submetida com sucesso. |
Proposal |
| 400 |
Os dados da requisição estão inválidos. |
ErrorResult |
| 401 |
Parceiro não autorizado a realizar a operação. |
ErrorResult |
| 500 |
Erro interno da API. Por favor tente novamente mais tarde ou contate o suporte técnico da Pottencial. |
ErrorResult |
Exemplos
Resposta de proposta com boleto
Resposta de proposta com pagamento através de boleto
{
"quoteId": "e296bed4-b543-4551-b1bc-1957b18c4322",
"documentPeriodStart": "2024-04-06T03:00:00Z",
"documentPeriodEnd": "2025-04-07T02:59:00Z",
"createdAt": "2022-12-27T13:36:36.5449905Z",
"status": "Pending",
"payment": {
"paymentType": "Boleto",
"installments": 6
},
"proposalId": "9a6777ae-0bcf-4e67-acca-94ec82c04364"
}
Aceitar proposta
Permite aprovar uma proposta criada.
Requisição (Request)
| Url | https://api-sandbox.pottencial.com.br/insurance/v1/{product_key}/proposals/{proposal_id}/accept | |
| Method | Post | |
| Query | product_key |
Chave de identificação do produto. garantia-estendida |
| proposal_id |
ID da proposta. |
|
| Headers | client_id |
Client ID da App. |
| access_token |
Token de acesso gerado para a App. |
|
Respostas (Response)
| Status | Descrição | Tipo |
| 200 |
Proposta aceita com sucesso. |
|
| 400 |
Os dados da requisição estão inválidos. |
ErrorResult |
| 401 |
Parceiro não autorizado a realizar a operação. |
ErrorResult |
| 500 |
Erro interno da API. Por favor tente novamente mais tarde ou contate o suporte técnico da Pottencial. |
ErrorResult |
Consultar proposta
Essa operação permite consultar os dados de uma proposta a partir do ID. Algumas informações sensíveis de participantes e agentes comissionados são ofuscadas para atender a LGPD.
Requisição (Request)
| Url | https://api-sandbox.pottencial.com.br/insurance/v1/{product_key}/proposals/{proposal_id} | |
| Method | Get | |
| Query | product_key |
Chave de identificação do produto. garantia-estendida |
| proposal_id |
ID da proposta. |
|
| Headers | client_id |
Client ID da App. |
| access_token |
Token de acesso gerado para a App. |
|
Respostas (Response)
| Status | Descrição | Tipo |
| 200 |
Proposta localizada com sucesso. |
Proposal |
| 400 |
Os dados da requisição estão inválidos. |
ErrorResult |
| 401 |
Parceiro não autorizado a realizar a operação. |
ErrorResult |
| 500 |
Erro interno da API. Por favor tente novamente mais tarde ou contate o suporte técnico da Pottencial. |
ErrorResult |
Exemplos
Resposta de proposta com pagamento pendente
Resposta de proposta com pagamento através de boleto.
{
"quoteId": "e296bed4-b543-4551-b1bc-1957b18c4322",
"documentPeriodStart": "2024-04-06T03:00:00Z",
"documentPeriodEnd": "2025-04-07T02:59:00Z",
"createdAt": "2022-12-27T13:36:36.5449905Z",
"status": "Pending",
"payment": {
"paymentType": "Boleto",
"installments": 6
},
"proposalId": "9a6777ae-0bcf-4e67-acca-94ec82c04364"
}
Resposta de proposta com boleto
Resposta de proposta aceita.
{
"quoteId": "e296bed4-b543-4551-b1bc-1957b18c4322",
"documentPeriodStart": "2024-04-06T03:00:00Z",
"documentPeriodEnd": "2025-04-07T02:59:00Z",
"createdAt": "2022-12-27T13:36:36.543Z",
"status": "Accepted",
"payment": {
"paymentType": "Boleto",
"installments": 6
},
"proposalId": "9a6777ae-0bcf-4e67-acca-94ec82c04364"
}
Consultar documento da proposta
Essa operação permite consultar o documento de uma proposta a partir do ID.
Requisição (Request)
| Url | https://api-sandbox.pottencial.com.br/insurance/v1/{product_key}/proposals/{proposal_id}/document | |
| Method | Get | |
| Query | product_key |
Chave de identificação do produto. garantia-estendida |
| proposal_id |
ID da proposta. |
|
| Headers | client_id |
Client ID da App. |
| access_token |
Token de acesso gerado para a App. |
|
Respostas (Response)
| Status | Descrição | Tipo |
| 200 |
Documento da proposta localizado com sucesso. |
BLOB |
| 401 |
Parceiro não autorizado a realizar a operação. |
ErrorResult |
| 404 |
Registro não encontrado. |
ErrorResult |
| 500 |
Erro interno da API. Por favor tente novamente mais tarde ou contate o suporte técnico da Pottencial. |
ErrorResult |
Apólices
Emitir apólice
Permite emitir uma apólice para uma proposta existente. A proposta deve ter sido aceita previamente.
Requisição (Request)
| Url | https://api-sandbox.pottencial.com.br/insurance/v1/{product_key}/policies | |
| Method | Post | |
| Query | product_key |
Chave de identificação do produto. garantia-estendida |
| Headers | client_id |
Client ID da App. |
| access_token |
Token de acesso gerado para a App. |
|
| Body | Policy | |
Exemplos
Emissão de apólice
Emissão da apólice para uma proposta existente.
{
"proposalId": "bddbcd59-213f-4523-a055-7e28f23a4978"
}
Respostas (Response)
| Status | Descrição | Tipo |
| 200 | Apólice emitida com sucesso. | Policy |
| 400 |
Os dados da requisição estão inválidos. |
ErrorResult |
| 401 |
Parceiro não autorizado a realizar a operação. |
ErrorResult |
| 500 |
Erro interno da API. Por favor tente novamente mais tarde ou contate o suporte técnico da Pottencial. |
ErrorResult |
Exemplos
Resposta de emissão de apólice aguardando processamento
Resposta de emissão de apólice aguardando processamento.
{
"policyId": "62354f29-4029-4ba1-82f8-309e458a0170",
"proposalId": "a6ab0082-64ec-4350-81d0-281888fa638e",
"quoteId": "81e56840-adb3-404f-8ce1-0a75d5dc029c",
"policyPeriodStart": "2021-08-03T00:00:00Z",
"policyPeriodEnd": "2022-08-03T00:00:00Z",
"status": "Creating",
"createdAt": "2021-08-03T18:11:02.573Z"
}
Resposta de emissão de apólice processada com sucesso
Resposta de emissão de apólice processada com sucesso.
{
"policyId": "4b8609b4-684f-4f38-bbfb-cf00679ecc54",
"proposalId": "9a6777ae-0bcf-4e67-acca-94ec82c04364",
"quoteId": "e296bed4-b543-4551-b1bc-1957b18c4322",
"policyNumber": "0306920229901950001068000",
"policyPeriodStart": "2024-04-06T03:00:00Z",
"policyPeriodEnd": "2025-04-07T02:59:00Z",
"status": "Creating",
"createdAt": "2022-12-27T13:38:15.633Z"
}
Consultar apólice
Essa operação permite consultar os dados de uma apólice a partir do ID. Algumas informações sensíveis de participantes e agentes comissionados são ofuscadas para atender a LGPD.
Requisição (Request)
| Url | https://api-sandbox.pottencial.com.br/insurance/v1/{product_key}/policies/{policy_id} | |
| Method | Get | |
| Query | product_key |
Chave de identificação do produto. garantia-estendida |
| policy_id |
ID da apólice. |
|
| Headers | client_id |
Client ID da App. |
| access_token |
Token de acesso gerado para a App. |
|
Respostas (Response)
| Status | Descrição | Tipo |
| 200 | Apólice localizada com sucesso. | Policy |
| 400 |
Os dados da requisição estão inválidos. |
ErrorResult |
| 401 |
Parceiro não autorizado a realizar a operação. |
ErrorResult |
| 404 |
Registro não encontrado. |
ErrorResult |
| 500 |
Erro interno da API. Por favor tente novamente mais tarde ou contate o suporte técnico da Pottencial. |
ErrorResult |
Exemplos
Resposta de emissão de apólice aguardando processamento
Resposta de emissão de apólice aguardando processamento.
{
"policyId": "4b8609b4-684f-4f38-bbfb-cf00679ecc54",
"proposalId": "9a6777ae-0bcf-4e67-acca-94ec82c04364",
"quoteId": "e296bed4-b543-4551-b1bc-1957b18c4322",
"policyNumber": "0306920229901950001068000",
"policyPeriodStart": "2024-04-06T03:00:00Z",
"policyPeriodEnd": "2025-04-07T02:59:00Z",
"status": "Creating",
"createdAt": "2022-12-27T13:38:15.633Z"
}
Resposta de emissão de apólice processada com sucesso
Resposta de emissão de apólice processada com sucesso.
{
"policyId": "4b8609b4-684f-4f38-bbfb-cf00679ecc54",
"proposalId": "9a6777ae-0bcf-4e67-acca-94ec82c04364",
"quoteId": "e296bed4-b543-4551-b1bc-1957b18c4322",
"policyNumber": "0306920229901950001068000",
"policyPeriodStart": "2024-04-06T03:00:00Z",
"policyPeriodEnd": "2025-04-07T02:59:00Z",
"status": "Active",
"createdAt": "2022-12-27T13:38:15.633Z"
}
Consultar documento da apólice
Essa operação permite consultar o documento de uma apólice a partir do ID.
Requisição (Request)
| Url | https://api-sandbox.pottencial.com.br/insurance/v1/{product_key}/policies/{policy_id}/document | |
| Method | Get | |
| Query | product_key |
Chave de identificação do produto. garantia-estendida |
| policy_id |
ID da apólice. |
|
| Headers | client_id |
Client ID da App. |
| access_token |
Token de acesso gerado para a App. |
|
Respostas (Response)
| Status | Descrição | Tipo |
| 200 |
Documento da apólice localizado com sucesso. |
BLOB |
| 401 |
Parceiro não autorizado a realizar a operação. |
ErrorResult |
| 404 |
Registro não encontrado. |
ErrorResult |
| 500 |
Erro interno da API. Por favor tente novamente mais tarde ou contate o suporte técnico da Pottencial. |
ErrorResult |
Dicionario
Quote
Representa uma cotação de um produto.
| Campo | Tipo | Regras | Descrição |
| quoteId | string (uuid) | Somente leitura |
ID único da cotação que a identifica dentro da Pottencial. Esse campo é preenchido automaticamente e retornado quando uma cotação é criada com sucesso. Ele deve ser armazenado pois é utilizado nas demais operações de consulta e proposta. |
| productKey | string | Somente leitura |
key do produto. A API de produtos deve ser utilizada para recuperar a lista de produtos que estão disponíveis para cotação. garantia-estendida |
| policyType | string (PolicyType) | Obrigatório |
Tipo de contratação da apólice, que pode ser única ou item a item. Caso não seja informado, será considerada como apólice de contratação única. Os produtos podem permitir somente um tipo de contratação, ou ambas. Unique |
| quoteNumber | number | Opcional |
Numero da Cotação |
| discountPercentage | number | Opcional |
Percentual de desconto a ser aplicado no valor do prêmio. O percentual de desconto e a taxa de agravo são mutuamente exclusivos, então somente um deles pode ser informado para uma cotação. |
| commercialLoadingFee | number | Opcional |
Taxa de agravo comercial a ser aplicada no valor do prêmio. O percentual de desconto e a taxa de agravo são mutuamente exclusivos, então somente um deles pode ser informado para uma cotação. |
| createdAt | string (date-time) | Somente leitura |
Data e hora de criação da cotação. Esse campo é preenchido automaticamente e retornado quando uma cotação é criada com sucesso. |
| status | string (QuoteStatus) | Somente leitura |
Situação atual da cotação. Esse campo é preenchido automaticamente e retornado quando uma cotação é criada com sucesso. |
| commercialPremium | number | Somente leitura |
Valor de prêmio considerando-se subscrição e comercial, incluindo valores de comissão e prolabore. Esse campo é preenchido automaticamente e retornado quando uma cotação é criada com sucesso. |
| grossPremium | number | Somente leitura |
Valor de prêmio total incluindo, além do prêmio comercial, o IOF e encargos financeiros. Esse campo é preenchido automaticamente e retornado quando uma cotação é criada com sucesso. |
| iof | number | Somente leitura |
Valor do IOF da cotação. Esse campo é preenchido automaticamente e retornado quando uma cotação é criada com sucesso. |
| commissionedAgents | array de CommissionedAgent | Obrigatório |
Lista de agentes comissionados da apólice, que inclui corretoras e estipulantes. |
| participants | array de Participant | Obrigatório |
Lista de participantes da apólice, que inclui segurado, tomador e beneficiário |
| riskObjects | array de |
Obrigatório |
Lista de objetos segurados. Os objetos segurados variam conforme o produto informado. |
PolicyType
Tipo da apólice informa se é contratação única ou item a item.
- Unique: Contratação única.
- ItemByItem: Contratação item a item.
QuoteStatus
Situação da cotação define o passo do fluxo que a cotação se encontra.
- Creating: A cotação foi criada, porém ainda não foi encaminhada para a subscrição.
- UnderAnalysis: A cotação está sob análise da subscrição.
- Denied: A cotação não foi aprovada.
- Approved: A cotação foi aprovada.
Participant
Representa um participante dentro da apólice.
| Campo | Tipo | Regras | Descrição |
| documentNumber | string | Obrigatório |
CPF/CNPJ do participante. Devem ser informados somente os dígitos, incluindo zeros à esquerda. Essa informação é ofuscada no retorno da API para atender a LGPD, trazendo somente alguns dígitos vizíveis. Os demais são substituídos por asterísco (*). Exemplos de retorno: 11699534000174 -> 11699\*\*\*0001\*\* 12345678909 -> 123\*\*\*789\*\* |
| participationPercentage | number | Opcional |
Percentual do prêmio a que o beneficiário tem direito. O valor deve ter no máximo duas casas decimais e estar entre 0.01 e 1.00. Obrigatório para os beneficiários e a soma da participação de todos os beneficiários deve ser igual a 1. |
| role | string (ParticipantRole) | Obrigatório |
Papel do participante na cotação. Os participantes que são obrigatórios varia por produto. |
| address | Address | Opcional |
Endereço do participante. |
| contact | Contact | Obrigatório |
Contato do participante. |
| isPayer | boolean | Obrigatório |
Identifica o responsavel pelo pagamento. |
ParticipantRole
Lista de possíveis valores para os participantes da apólice.
- Beneficiary: O beneficiário é a pessoa da apólice que tem direito a indenização do seguro em caso de problema (sinistro). O beneficiário pode ser uma pessoa diferente do segurado (que é quem está com o risco protegido) e do estipulante (que é quem está contratando o seguro), dependendo da situação.
- Insured: O segurado é a pessoa, física ou jurídica, cujos interesses estão garantidos pela apólice de seguro. Geralmente é quem contrata o seguro.
- PolicyHolder: Devedor das obrigações por ele assumidas no contrato principal. (Circular SUSEP 232/03).
CommissionedAgent
Representa um agente comissionado dentro da apólice.
| Campo | Tipo | Regras | Descrição |
| documentNumber | string | Obrigatório |
CPF/CNPJ do agente comissionado. Devem ser informados somente os dígitos, incluindo zeros à esquerda. Essa informação é ofuscada no retorno da API para atender a LGPD, trazendo somente alguns dígitos vizíveis. Os demais são substituídos por asterísco (*). Exemplos de retorno: 11699534000174 -> 11699\*\*\*0001\*\* 12345678909 -> 123\*\*\*789\*\* |
| role | string (CommissionedAgentRole) | Obrigatório |
Papel desempenhado pelo agente comissionado. Os papéis obrigatórios variam por produto. |
| lead | boolean | Opcional |
Identifica a corretora principal na cotação. Esse campo pode ser omitido quando somente houver uma única corretora na cotação. |
| commissionPercentage | number | Opcional |
Percentual de comissão, no caso de corretora, e percentual de pró-labore, no caso de estipulante. O limite desse valor varia conforme o produto e contrato com a seguradora. O valor deve ter no máximo 3 casas decimais. |
| participationPercentage | number | Opcional |
Percentual de participação na comissão, no caso de co-corretagem. Quando informado, a soma desse valor para todas as corretoras deve ser igual a 1. O valor deve ter no máximo 3 casas decimais. |
| commissionAmount | number | Somente leitura |
Valor de comissão, no caso de corretora, e valor de pró-labore, no caso de estipulante. Esse valor é preenchido no retorno da cotação. |
| isPayer | boolean | Obrigatório |
Identifica o responsavel pelo pagamento. |
| address | Address | Opcional |
Endereço do InsuranceAgent. |
CommissionedAgentRole
Lista de possíveis valores para os agentes comissionados da apólice.
- Broker: É o profissional especializado e habilitado a intermediar contratos de seguros entre as seguradoras, empresas e os consumidores, sejam eles pessoas físicas ou jurídicas.
- PolicyOwner: O estipulante é a pessoa que contrata o seguro, independente se é ele que se beneficia do seguro ou se é ele quem vai receber a indenização. É o estipulante, ou dono da apólice, que preenche e assina a proposta de seguro, paga o prêmio, solicita eventuais modificações durante a vigência da apólice, autoriza a sua renovação, ou solicita o seu cancelamento quando for o caso.
- InsuranceAgent: responsável pelo pagamento.
Address
Representa uma localidade com endereço.
| Campo | Tipo | Regras | Descrição |
| street | string | Obrigatório | Nome da avenida, rua ou praça da localidade. |
| number | string | Obrigatório | Número da localidade. |
| district | string | Obrigatório | Bairro do localidade. |
| city | string | Obrigatório | Nome da cidade da localidade, conforme cadastrado nos Correios. |
| state | string | Obrigatório | Sigla do estado da localidade, com duas letras. |
| zipCode | string | Obrigatório | CEP da localidade. Devem ser informados somente os dígitos. |
| complement | string | Opcional | Complemento da localidade. Apartamento, andar. |
Coverage
Contém informações das coberturas para cotação.
| Campo | Tipo | Regras | Descrição |
| key | string | Obrigatório |
ID da cobertura, conforme cada produto.
|
| lmi | number | Opcional |
Limite máximo de indenização. No caso de contratação única, este valor pode ser menor ou igual à soma da importância segurada dos objetos segurados. Na contratação item a item, este valor é exatamente a soma dos itens desta cobertura. Caso não seja informado, assume-se o valor da importância segurada. |
| insuredAmount | number | Opcional |
Importância segurada, ou valor segurado, deste objeto de risco. |
Contact
Contem as informacoes para contado.
| Campo | Tipo | Regras | Descrição |
| name | string | Obrigatório |
nome de identificação do contato. |
| string | Obrigatório |
e-mail do contato. |
|
| phoneNumber | string | Obrigatório |
numero de telefone do contato. com DDD + numero |
ProductRisk
Representa os dados referentes ao objeto de risco Garantia Estendida
| Campo | Tipo | Regras | Descrição |
| type | string | Opcional |
Nome do tipo do objeto de risco. Valor fixo Product |
| coverages | array de Coverage | Opcional |
Lista de coberturas para o objeto segurado. |
| productDetails | ProductDetails | Opcional |
Detalhes do Produto segurado. |
| preventiveMaintenance | boolean | Opcional |
Manutenção preventiva |
| budgetNumber | string | Opcional |
Numero do orçamento |
| extendedWarrantyHours | number | Opcional |
Horas de garantia extendida |
| signedValue | string | Opcional |
valor assinado |
ProductDetails
Representa os dados referentes ao Produto seguradoro
| Campo | Tipo | Regras | Descrição |
| category | number | Obrigatório |
Categoria do Produto Categoria atualmente fixo 5 ( Equipamentos Móveis ) |
| name | string | Obrigatório |
Nome do Produto |
| manufacture | string | Obrigatório |
Nome do Fabricante |
| model | string | Obrigatório |
Modelo do produto |
| year | number | Obrigatório |
Ano do Produto |
| serialNumber | string | Obrigatório |
Numero série do produto |
| chassi | number | Opcional |
Numero do chassi do produto |
| serviceMeter | number | Obrigatório |
Quantidade de horas de uso do equipamento "horímetro" |
| invoiceNumber | string | Obrigatório |
Numero nota fiscal do produto |
| guaranteeDateStart | string (date-time) | Obrigatório |
Data de inicio da Garantia |
| guaranteeDateEnd | string (date-time) | Obrigatório |
Data de inicio da Garantia |
Proposal
Representa uma proposta de um produto.
| Campo | Tipo | Regras | Descrição |
| proposalId | string (uuid) | Somente leitura |
ID único da proposta. O ID será gerado automaticamente no retorno da API. |
| quoteId | string (uuid) | Obrigatório |
ID único da cotação que vai dar origem à proposta. |
| proposalNumber | number | Opcional |
Numero da Proposta |
| policyPeriodStart | string (date) | Opcional |
Data de início de vigência da apólice. Esse valor pode ser omitido caso essa informação tenha sido informada no momento de cotação. |
| policyPeriodEnd | string (date) | Opcional |
Data do fim de vigência da apólice. Esse valor pode ser omitido caso essa informação tenha sido informada no momento de cotação. |
| payment | Payment | Obrigatório |
Detalhes do pagamento da apólice. |
| createdAt | string (date-time) | Somente leitura |
Data e hora de criação da proposta. Esse campo é preenchido automaticamente e retornado quando uma proposta é criada com sucesso. |
| status | string (ProposalStatus) | Somente leitura |
Situação atual da proposta. Esse campo é preenchido automaticamente e retornado quando uma proposta é criada com sucesso. |
ProposalStatus
Situação da proposta define o passo do fluxo que a proposta se encontra.
- Pending: A proposta foi criada, porém ainda não foi definido meio de pagamento.
- Ready: O meio de pagamento da proposta foi definido.
- Issued: O documento da proposta foi emitido.
- Accepted: A proposta foi aceita.
Payment
Representa os dados referentes ao pagamento da apólice.
| Campo | Tipo | Regras | Descrição |
| paymentType | string (PaymentType) | Obrigatório |
Forma de pagamento da apólice. |
| installments | integer | Obrigatório |
Número de parcelas que será dividido o pagamento da apólice. Os produtos possuem regras específicas para a quantidade de parcelas que pode ser divido o pagamento. |
| firstDueDate | string (date) | Opcional |
Carência para a data de vencimento da primeira parcela, em dias, para pagamento em boleto. |
PaymentType
Lista as possíveis formas de pagamento da apólice.
- Invoice: Pagamento através de fatura.
- Boleto: Pagamento através de boleto.
Policy
Representa uma apólice de um produto.
| Campo | Tipo | Regras | Descrição |
| policyId | string (uuid) | Somente leitura |
ID único da apólice. O ID será gerado automaticamente no retorno da API. |
| proposalId | string (uuid) | Obrigatório |
ID único da proposta aceita anteriormente que vai dar origem à apólice. |
| quoteId | string (uuid) | Somente leitura |
ID único da cotação que deu origem à proposta. |
| policyNumber | string | Somente leitura | Número da apólice. |
| policyPeriodStart | string (date) | Somente leitura |
Data de início de vigência da apólice. |
| policyPeriodEnd | string (date) | Somente leitura |
Data do fim de vigência da apólice. |
| status | string (PolicyStatus) | Somente leitura |
Situação atual da apólice. Esse campo é preenchido automaticamente e retornado quando uma apólice é criada com sucesso. |
| createdAt | string (date-time) | Somente leitura |
Data e hora de criação da apólice. Esse campo é preenchido automaticamente e retornado quando uma apólice é criada com sucesso. |
PolicyStatus
Situação da apólice define o passo do fluxo que a apólice se encontra.
- Creating
- Modifying
- Canceling
- Active
- Cancelled
- Expired
Resolução de erros
| Código | Erro | Descrição | Solução |
| 400 | Bad Request | Invalid secret in Authorization header | O client_secret informado no header é inválido. Verifique se o client_secret informado é o mesmo da APP e se o header Authorization está sendo passado conforme especificado. |
| 401 | Unauthorized | Could not find a required APP in the request, identified by HEADER client_id. | O client_id informado no header é inválido. Verifique se o client_id informado é o mesmo da APP e se o header Authorization está sendo passado conforme especificado. |
| 404 | Not Found | Not Found | Provavelmente a URL sendo chamado não está correta. Verifique se está conforme especificado. |
| 429 | Too Many Requests | Too Many Requests | O consumidor estourou o limite de requisições por tempo. Aguarde um pouco para tentar novas requisições. |
| 500 | Internal Server Error | Internal Server Error | Erro não esperado, algo está quebrado na API. Por favor aguarde ou entre em contato com o time de suporte. |
Estrutura da mensagem de erro
ErrorResult
Representa um resultado de erro na chamada da plataforma.
| Campo | Tipo | Regras | Descrição |
| errors | array de ErrorMessage | Opcional | Lista de erros da solicitação. |
ErrorMessage
Contém informações de um erro.
| Campo | Tipo | Regras | Descrição |
| code | string | Opcional | Código de identificação do erro. |
| message | string | Opcional | Descrição do erro. |
