FiancaLocaticia
Aluguel Mensalizado
O Seguro Aluguel Mensalizado é o seguro fiança locatícia da Pottencial que substitui o fiador e outras garantias na locação de imóveis, protegendo o proprietário em caso de não pagamento de aluguel e encargos por parte do inquilino.
As APIs da Pottencial permitem que sua empresa realize cotações, propostas e emissões de apólices para os nossos produtos 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 - Validar Biometria: Caso seja necessário efetuar a validação via Biometria Facial .
- Passo 4 - Enviar proposta: Quando a cotação estiver pronta, envie os dados para criar uma proposta.
- Passo 5 - Aceitar proposta: Aceite a proposta criada.
- Passo 6 - 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.Analise de Crédito
Para consultar Analise de Crédito utilizar Api Onboarding em:
Consultar Analise de Crédito
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/fianca-locaticia-mensalizado-pf/quotes | |
| Method | Post | |
| Headers | client_id |
Client ID da App. |
| access_token |
Token de acesso gerado para a App. |
|
| Body | Quote | |
Cotação para o produto Aluguel Mensalizado
Para cadastro de cotação para o produto Aluguel Mensalizado é necessário informar um único objeto de risco do tipo RentalProperty.
{
"policyPeriodStart": "2021-01-01",
"policyPeriodEnd": "2021-12-31",
"policyType": "Unique",
"discountPercentage": "0",
"commercialLoadingFee": "0",
"commissionedAgents": [
{
"documentNumber": "11111111111111",
"role": "Broker",
"commissionPercentage": "0.15",
"lead": "true"
},
{
"documentNumber": "10864690000180",
"role": "PolicyOwner",
"commissionPercentage":0,
"isPayer": true
}
],
"participants": [
{
"documentNumber": "33333333333",
"role": "Insured",
"address": {
"street": "Av. Raja Gabáglia",
"number": "1143",
"district": "Luxemburgo",
"city": "Belo Horizonte",
"state": "MG",
"zipCode": "30380403",
"complement": "20º andar",
"country": "BRA",
"type": "Residential"
},
"contact": {
"name": "nome do contato",
"email": "[email protected]",
"phoneNumber": "31999999999",
"cellPhoneNumber": "31999999999"
}
},
{
"documentNumber": "33333333333",
"role": "Beneficiary",
"participationPercentage": "1",
"address": {
"street": "Av. Raja Gabáglia",
"number": "1143",
"district": "Luxemburgo",
"city": "Belo Horizonte",
"state": "MG",
"zipCode": "30380403",
"complement": "20º andar",
"country": "BRA",
"type": "Residential"
},
"contact": {
"name": "nome do contato",
"email": "[email protected]",
"phoneNumber": "31999999999",
"cellPhoneNumber": "31999999999"
}
},
{
"documentNumber": "4444444444444",
"role": "PolicyHolder",
"address": {
"street": "Av. Raja Gabáglia",
"number": "1143",
"district": "Luxemburgo",
"city": "Belo Horizonte",
"state": "MG",
"zipCode": "30380403",
"complement": "20º andar",
"country": "BRA",
"type": "Residential"
},
"contact": {
"name": "nome do contato",
"email": "[email protected]",
"phoneNumber": "31999999999",
"cellPhoneNumber": "31999999999"
}
}
],
"riskObjects": [
{
"type": "rentalProperty",
"tenantDocumentNumber": "7777777777777",
"startLeaseContract": "2022-12-27",
"endLeaseContract": "2023-12-27",
"coverages": [
{
"key": "basica",
"insuredAmount": "50000.00"
}
],
"riskLocation": {
"nationalCoverage": "false",
"address": {
"street": "Av. Raja Gabáglia",
"number": "1143",
"district": "Luxemburgo",
"city": "Belo Horizonte",
"state": "MG",
"zipCode": "30380403",
"complement": "20º andar",
"country": "BRA",
"type": "Residential"
}
},
"expenses": [
{
"description": "VALOR_ALUGUEL",
"value": "50:55"
},
{
"description": "VALOR_CONDOMINIO",
"value": "50:55"
}
],
"planKey": "Basic",
"occupation": "Residencial",
"inhabited": "true",
"multiple": "30",
"paymentConditions": {
"paymentType": "Invoice",
"installments": "2"
}
}
]
}
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 |
Cotação para o produto Aluguel Mensalizado
Resposta cotação Aluguel Mensalizado com um único objeto de risco do tipo RentalProperty.
{
"quoteId": "c03ab663-3d5c-4014-aa5e-cae727103392",
"productKey": "fianca-locaticia-mensalizado-pf",
"policyPeriodStart": "2021-01-01",
"policyPeriodEnd": "2021-12-31",
"policyType": "Unique",
"quoteNumber": "99999",
"createdAt": "2021-04-29T17:12:27.219Z",
"status": "Approved",
"commercialPremium": "109.98",
"grossPremium": "99.99",
"iof": "9.99",
"discountPercentage": "0.5",
"commercialLoadingFee": "0.2",
"commissionedAgents": [
{
"documentNumber": "11111111111111",
"role": "Broker",
"commissionPercentage": "0.15",
"commissionAmount": "486.9,",
"lead": "true",
},
{
"documentNumber": "10864690000180",
"role": "PolicyOwner",
"commissionPercentage":0,
"isPayer": true
}
],
"participants": [
{
"documentNumber": "33333333333",
"role": "Insured",
"address": {
"street": "Av. Raja Gabáglia",
"number": "1143",
"district": "Luxemburgo",
"city": "Belo Horizonte",
"state": "MG",
"zipCode": "30380403",
"complement": "20º andar",
"country": "BRA",
"type": "Residential"
},
"contact": {
"name": "nome do contato",
"email": "[email protected]",
"phoneNumber": "31999999999",
"cellPhoneNumber": "31999999999"
}
},
{
"documentNumber": "33333333333",
"role": "Beneficiary",
"participationPercentage": "1"
}
],
"riskObjects": [
{
"type": "rentalProperty ",
"tenantDocumentNumber": "7777777777777",
"startLeaseContract": "2022-12-27",
"endLeaseContract": "2023-12-27",
"coverages": [
{
"key": "basica",
"insuredAmount": "50000.00",
"grossPremium": "1000,",
"commercialPremium": "1000,",
"lmi": "1000"
},
{
"key": "luz",
"insuredAmount": "5000.00"
},
{
"key": "agua",
"insuredAmount": "1000.00"
},
{
"key": "multa",
"insuredAmount": "5000.00",
"grossPremium": "1000,",
"commercialPremium": "1000,",
"lmi": "1000"
},
{
"key": "danos",
"insuredAmount": "70000.00",
"grossPremium": "1000,",
"commercialPremium": "1000,",
"lmi": "1000,",
"percentage": "0.20,",
"description": "Cobertura de Danos ao imóvel"
},
{
"key": "pintura",
"insuredAmount": "100000.00",
"grossPremium": "1000,",
"commercialPremium": "1000,",
"lmi": "1000"
}
],
"riskLocation": {
"nationalCoverage": "false",
"address": {
"street": "Av. Raja Gabáglia",
"number": "1143",
"district": "Luxemburgo",
"city": "Belo Horizonte",
"state": "MG",
"zipCode": "30380403",
"complement": "20º andar",
"country": "BRA",
"type": "Residential"
}
},
"expenses": [
{
"description": "VALOR_ALUGUEL",
"value": "50:55"
},
{
"description": "VALOR_CONDOMINIO",
"value": "50:55"
}
],
"planKey": "Basic",
"occupation": "Residencial ",
"inhabited": "true",
"multiple": "30"
}
]
}
Consultar cotação
Permite consultar os dados de uma cotação.
Requisição (Request)
| Url | https://api-sandbox.pottencial.com.br/insurance/v1/fianca-locaticia-mensalizado-pf/quotes/{quote_id} | |
| Method | Get | |
| 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 |
Cotação para o produto Aluguel Mensalizado
Resposta cotação Aluguel Mensalizado com um único objeto de risco do tipo RentalProperty.
{
"quoteId": "c03ab663-3d5c-4014-aa5e-cae727103392",
"productKey": "fianca-locaticia-mensalizado-pf",
"policyPeriodStart": "2021-01-01",
"policyPeriodEnd": "2021-12-31",
"policyType": "Unique",
"quoteNumber": "99999",
"createdAt": "2021-04-29T17:12:27.219Z",
"status": "Approved",
"commercialPremium": "109.98",
"grossPremium": "99.99",
"iof": "9.99",
"discountPercentage": "0.5",
"commercialLoadingFee": "0.2",
"commissionedAgents": [
{
"documentNumber": "11111111111111",
"role": "Broker",
"commissionPercentage": "0.15",
"commissionAmount": "486.9,",
"lead": "true",
},
{
"documentNumber": "10864690000180",
"role": "PolicyOwner",
"commissionPercentage":0,
"isPayer": true
}
],
"participants": [
{
"documentNumber": "33333333333",
"role": "Insured",
"address": {
"street": "Av. Raja Gabáglia",
"number": "1143",
"district": "Luxemburgo",
"city": "Belo Horizonte",
"state": "MG",
"zipCode": "30380403",
"complement": "20º andar",
"country": "BRA",
"type": "Residential"
},
"contact": {
"name": "nome do contato",
"email": "[email protected]",
"phoneNumber": "31999999999",
"cellPhoneNumber": "31999999999"
}
},
{
"documentNumber": "33333333333",
"role": "Beneficiary",
"participationPercentage": "1"
}
],
"riskObjects": [
{
"type": "rentalProperty ",
"tenantDocumentNumber": "7777777777777",
"startLeaseContract": "2022-12-27",
"endLeaseContract": "2023-12-27",
"coverages": [
{
"key": "basica",
"insuredAmount": "50000.00",
"grossPremium": "1000,",
"commercialPremium": "1000,",
"lmi": "1000"
},
{
"key": "luz",
"insuredAmount": "5000.00"
},
{
"key": "agua",
"insuredAmount": "1000.00"
},
{
"key": "multa",
"insuredAmount": "5000.00",
"grossPremium": "1000,",
"commercialPremium": "1000,",
"lmi": "1000"
},
{
"key": "danos",
"insuredAmount": "70000.00",
"grossPremium": "1000,",
"commercialPremium": "1000,",
"lmi": "1000,",
"percentage": "0.20,",
"description": "Cobertura de Danos ao imóvel"
},
{
"key": "pintura",
"insuredAmount": "100000.00",
"grossPremium": "1000,",
"commercialPremium": "1000,",
"lmi": "1000"
}
],
"riskLocation": {
"nationalCoverage": "false",
"address": {
"street": "Av. Raja Gabáglia",
"number": "1143",
"district": "Luxemburgo",
"city": "Belo Horizonte",
"state": "MG",
"zipCode": "30380403",
"complement": "20º andar",
"country": "BRA",
"type": "Residential"
}
},
"expenses": [
{
"description": "VALOR_ALUGUEL",
"value": "50:55"
},
{
"description": "VALOR_CONDOMINIO",
"value": "50:55"
}
],
"planKey": "Basic",
"occupation": "Residencial ",
"inhabited": "true",
"multiple": "30"
}
]
}
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/fianca-locaticia-mensalizado-pf/quotes/{quote_id}/draft | |
| Method | Get | |
| 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 minuta localizado com sucesso. |
|
| 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 |
Consultar Biometria Facial
Permite consultar a url de uma cotação para autorizar.
Requisição (Request)
| Url | https://api-sandbox.pottencial.com.br/insurance/v1/fianca-locaticia-mensalizado-pf/quotes/facial-biometrics/{quote_id} | |
| Method | Get | |
| 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 |
Url da biometria localizada com sucesso. |
Biometrics |
| 400 |
Os dados da requisição estão inválidos. |
ErrorResult |
| 401 |
Parceiro não autorizado a realizar a operação. |
ErrorResult |
| 500 |
Os dados da requisição estão inválidos. |
ErrorResult | Erro interno da API. Por favor tente novamente mais tarde ou contate o suporte técnico da Pottencial. |
ErrorResult |
Exemplo
{
"url": "https://developers.pottencial.com.br/api-portal/pt-br/content/fiancalocaticia"
}
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/fianca-locaticia-mensalizado-pf/proposals | |
| Method | Post | |
| Headers | client_id |
Client ID da App. |
| access_token |
Token de acesso gerado para a App. |
|
| Body | Proposal | |
Proposta
Proposta com pagamento à vista através de Fatura, com vencimento em 7 dias.
{
"quoteId": "ac721b29-0a5a-44b4-a205-b23288164f40",
"policyPeriodStart": "2021-01-01",
"policyPeriodEnd": "2021-12-31",
"payment": {
"paymentType": "Invoice",
"paymentInstructions": "informações da forma de pagamento"
"firstInstallmentDueDateDelay": "7"
}
}
Proposta com fatura
Proposta com pagamento parcelado em 12 vezes através de Fatura.
{ "quoteId": "ac721b29-0a5a-44b4-a205-b23288164f40", "policyPeriodStart": "2021-01-01", "policyPeriodEnd": "2021-12-31", "payment": { "paymentType": "Invoice", "firstDueDate": "2023-04-06", "paymentInstructions": "informações 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 |
Resposta de proposta com fatura
Resposta de proposta com pagamento à vista através de fatura, com vencimento em 7 dias.
{
"proposalId": "a6ab0082-64ec-4350-81d0-281888fa638e",
"quoteId": "ac721b29-0a5a-44b4-a205-b23288164f40",
"proposalNumber": "99999",
"policyPeriodStart": "2021-01-01",
"policyPeriodEnd": "2021-12-31",
"payment": {
"paymentType": "Invoice",
"installments": "1",
"firstInstallmentDueDateDelay": "7"
},
"createdAt": "2021-08-03",
"status": "Ready"
}
Resposta de proposta com fatura
Resposta de proposta com pagamento parcelado em 12 vezes através de Fatura.
{
"proposalId": "a6ab0082-64ec-4350-81d0-281888fa638e",
"quoteId": "ac721b29-0a5a-44b4-a205-b23288164f40",
"proposalNumber": "99999",
"policyPeriodStart": "2021-01-01",
"policyPeriodEnd": "2021-12-31",
"payment": {
"paymentType": "Invoice",
"installments": "12"
},
"createdAt": "2021-08-03",
"status": "Ready"
}
Aceitar proposta
Permite aprovar uma proposta criada.
Requisição (Request)
| Url | https://api-sandbox.pottencial.com.br/insurance/v1/fianca-locaticia-mensalizado-pf/proposals/{proposal_id}/accept | |
| Method | Post | |
| 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/fianca-locaticia-mensalizado-pf/proposals/{proposal_id} | |
| Method | Get | |
| 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 |
Resposta de proposta com fatura
Resposta de proposta com pagamento à vista através de fatura, com vencimento em 7 dias.
{
"proposalId": "a6ab0082-64ec-4350-81d0-281888fa638e",
"quoteId": "ac721b29-0a5a-44b4-a205-b23288164f40",
"proposalNumber": "99999",
"policyPeriodStart": "2021-01-01",
"policyPeriodEnd": "2021-12-31",
"payment": {
"paymentType": "Invoice",
"installments": "1",
"firstInstallmentDueDateDelay": "7"
},
"createdAt": "2021-08-03",
"status": "Ready"
}
Resposta de proposta com fatura
Resposta de proposta com pagamento parcelado em 12 vezes através de Fatura.
{
"proposalId": "a6ab0082-64ec-4350-81d0-281888fa638e",
"quoteId": "ac721b29-0a5a-44b4-a205-b23288164f40",
"proposalNumber": "99999",
"policyPeriodStart": "2021-01-01",
"policyPeriodEnd": "2021-12-31",
"payment": {
"paymentType": "Invoice",
"installments": "12"
},
"createdAt": "2021-08-03",
"status": "Ready"
}
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/fianca-locaticia-mensalizado-pf/proposals/{proposal_id}/document | |
| Method | Get | |
| 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. |
|
| 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/fianca-locaticia-mensalizado-pf/policies | |
| Method | Post | |
| 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": "62354f29-4029-4ba1-82f8-309e458a0170",
"proposalId": "a6ab0082-64ec-4350-81d0-281888fa638e",
"quoteId": "81e56840-adb3-404f-8ce1-0a75d5dc029c",
"policyNumber": "0306920219901140003053000",
"policyPeriodStart": "2021-08-03T00:00:00Z",
"policyPeriodEnd": "2022-08-03T00:00:00Z",
"status": "Active",
"createdAt": "2021-08-03T18:11:02.573Z"
}
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/fianca-locaticia-mensalizado-pf/policies/{policy_id} | |
| Method | Get | |
| 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": "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": "62354f29-4029-4ba1-82f8-309e458a0170",
"proposalId": "a6ab0082-64ec-4350-81d0-281888fa638e",
"quoteId": "81e56840-adb3-404f-8ce1-0a75d5dc029c",
"policyNumber": "0306920219901140003053000",
"policyPeriodStart": "2021-08-03T00:00:00Z",
"policyPeriodEnd": "2022-08-03T00:00:00Z",
"status": "Active",
"createdAt": "2021-08-03T18:11:02.573Z"
}
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/fianca-locaticia-mensalizado-pf/policies/{policy_id}/document | |
| Method | Get | |
| 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. |
|
| 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 |
Dicionário
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.
|
| productKey | string (uuid) | Somente leitura |
Chave do produto. A API de produtos deve ser utilizada para recuperar a lista de produtos que estão disponíveis para cotação. |
| policyType | string (PolicyType) | Somente leitura |
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.
|
| 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 pró-labore. 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. |
| policyPeriodStart | string (date) | Opcional |
Data de início de vigência da apólice. |
| policyPeriodEnd | string (date) | Opcional |
Data do fim de vigência da apólice. |
| 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 |
| partners | array de Partners | Opcional |
Lista de Parceiros comerciais em uma apólice, não é uma entidade oficial ou regulamentada. É utilizada somente para representar vínculos comerciais. |
| 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.
- Expired: A cotação foi cancelada devido a data.
- UnderAnalysis: A cotação está sob análise da subscrição.
- Performed: A cotação foi efetivada.
- PreApproved: A cotação pré-aprovada.
- Approved: A cotação foi aprovada.
- Refused: A cotação não foi aprovada.
- PendingBiometry: A cotação está aguardando realização da biometria.
- ApprovedBiometry: A cotação foi aprovada na biometria.
- RefusedBiometry: A cotação não foi aprovada na biometria.
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 visíveis.
Exemplos de retorno: 11699534000174 -> 11699\*\*\*0001\*\* |
| 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 | Opcional |
Contato do participante. |
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 visíveis.
Exemplos de retorno: 11699534000174 -> 11699\*\*\*0001\*\* |
| 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. |
| 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 | Opcional |
informa quem é o pagador da apólice. |
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.
Contact
Representa os dados de contato.
| Campo | Tipo | Regras | Descrição |
| name | string | Obrigatório |
Nome para identificação do contato. |
| string | Obrigatório |
E-mail de contato. |
|
| phoneNumber | string | Obrigatório |
Número do telefone, com DDD. |
| cellPhoneNumber | string | Opcional |
Número do Celular, com DDD. |
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.
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. |
| commercialPremium | number | Somente leitura |
Valor de prêmio considerando-se subscrição e comercial, incluindo valores de comissão e pró-labore. 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. |
| percentage | number | Opcional |
Percentual de participação na comissão. |
| description | string | Opcional |
texto descritivo da franquia. |
PaymentConditions
Representa um objeto informando forma de pagamento na Pottencial.
| 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. |
RentalProperty
Representa uma objeto de Aluguel Mensalizado.
| Campo | Tipo | Regras | Descrição |
| type | string | Opcional |
Tipo do Objeto referente a Aluguel Mensalizado |
| startLeaseContract | string | Obrigatório |
Data início do contrato de aluguel |
| endLeaseContract | string | Obrigatório |
Data fim do contrato de aluguel |
| tenantDocumentNumber | string | Obrigatório |
cpf do inquilino. |
| expenses | object expenses | Obrigatório |
Representa os Encargos. |
| planKey | string | Obrigatório |
chave do plano
|
| multiple | number | Obrigatório |
Número de vezes que se deseja que o valor da cobertura seja indeniza gerando um total da importância segurada
|
| occupation | string | Obrigatório |
Tipo de ocupação
|
| inhabited | boolean | Obrigatório |
habitada, em uso. |
| riskLocation | object | Obrigatório |
Representa o Local do Objeto de Risco. |
| coverages | array de Coverage | Obrigatório |
Lista de coberturas para o objeto segurado. |
| paymentConditions | PaymentConditions | Opcional |
Representa um objeto informando forma de pagamento na Pottencial. |
Expenses
Representa os Encargos.
| Campo | Tipo | Regras | Descrição |
| description | string | Opcional |
chave do plano
|
| value | number | Opcional |
Valor da despesa |
RiskLocation
Representa o Local do Objeto de Risco.
| Campo | Tipo | Regras | Descrição |
| address | Address | Opcional |
Representa um objeto com as informações do Endereço. |
| nationalCoverage | boolean | Opcional |
Descrição da despesa |
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. |
| country | string | Opcional | Pais de Origem. |
| type | string | Opcional | Descrição da localidade
|
Biometrics
Representa o retorno de sucesso com a url do biometria facial.
| Campo | Tipo | Regras | Descrição |
| url | string | Opcional |
url da biometria facial |
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. |
| firstInstallmentDueDateDelay | integer | Opcional |
Carência para a data de vencimento da primeira parcela, em dias, para pagamento. |
| firstDueDate | string | Opcional |
Data de vencimento da primeira parcela. |
| automaticDebitAccount | BankAccount | Opcional |
Dados bancários para pagamento através de débito em conta. |
PaymentType
Lista as possíveis formas de pagamento da apólice.
- Invoice: Pagamento através de fatura.
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. |
| 415 | Unsupported Media Type | Content type not supported | O header Content-Type não está sendo informado conforme esperado. O correto é application/json. |
| 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. |
