policy-holders
Onboarding
A API para cadastro de tomador facilita o processo do cadastro e nomeação de tomadores, possibilitando que o cadastro possa ser feito de forma mais ágil e eficiente.
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.Cadastro de um tomador
Solicita o cadastro de um tomador e efetua uma análise prévia de crédito para liberação de um limite e uma taxa
Requisição (Request)
| Url | https://api-sandbox.pottencial.com.br/onboarding/v1/policy-holders | |
| Method | Post | |
| Headers | client_id | Client ID da App. |
| access_token | Token de acesso gerado para a App. |
|
| Body | PolicyHolderRequest | |
Exemplos
Exemplo solicitação de cadastro do tomador
Resposta da solicitação de cadastro do tomador.
{
"brokerDocumentNumber": "33651172000184",
"policyHolderDocumentNumber": "35366879000174"
}
Respostas (Response)
| Status | Descrição | Tipo |
| 202 | A solicitação de cadastro do tomador foi recebida pela Pottencial, mas ainda não foi processada. |
PolicyHolderResponse |
| 400 | Os dados da requisição estão inválidos. |
ErrorResult |
| 400 | O campo {field} é obrigatório e deve ser informado. |
ErrorResult |
| 400 | O campo {field} está com um valor inválido. |
ErrorResult |
| 401 | Parceiro não autorizado a realizar a operação. |
ErrorResult |
| 403 | Parceiro não autorizado a realizar a operação. |
ErrorResult |
| 409 | Já existe uma solicitação de cadastro para o tomador e corretora informadas em andamento. |
ErrorResult |
| 429 | Quantidade de requisições excede o limite permitido para o período. |
ErrorResult |
| 500 | Oops! Tivemos um problema. Aguarde alguns minutos e tente novamente. Se o erro persistir entre em contato conosco através de nosso canal de atendimento a APIs pelo e-mail: [email protected] |
ErrorResult |
Exemplo
{
"requestId": "123e4567-e89b-12d3-a456-426614174000",
"status": "InProgress"
}
Consultar cadastro do tomador
Obtém o status da solicitação de cadastro do tomador.
Requisição (Request)
| Url | https://api-sandbox.pottencial.com.br/onboarding/v1/policy-holders | |
| Method | Get | |
| Query | requestId | Identificador único da solicitação de cadastro. |
| Headers | client_id | Client ID da App. |
| access_token | Token de acesso gerado para a App. |
|
Respostas (Response)
| Status | Descrição | Tipo |
| 200 | Obtém o status da solicitação de cadastro do tomador |
PolicyHolderRequestResponse |
| 400 | Os dados da requisição estão inválidos. |
ErrorResult |
| 400 | O campo {field} é obrigatório e deve ser informado. |
ErrorResult |
| 400 | O campo {field} está com um valor inválido. |
ErrorResult |
| 401 | Parceiro não autorizado a realizar a operação. |
ErrorResult |
| 403 | Parceiro não autorizado a realizar a operação. |
ErrorResult |
| 429 | Quantidade de requisições excede o limite permitido para o período. |
ErrorResult |
| 500 | Oops! Tivemos um problema. Aguarde alguns minutos e tente novamente. Se o erro persistir entre em contato conosco através de nosso canal de atendimento a APIs pelo e-mail: [email protected] |
ErrorResult |
Exemplo
[ { "requestId": "123e4567-e89b-12d3-a456-426614174001", "status": "InProgress", "policyHolderDocumentNumber": "35366879000174" } ]Exemplo de Erro
[ { "requestId": "123e4567-e89b-12d3-a456-426614174000", "status": "Rejected", "policyHolderDocumentNumber": "35366879000174", "remarks": [ { "code": 01, "description": "Tomador ativo em outra corretora." }, { "code": 02, "description": "O cadastro do tomador não é permitido por este canal." }, { "code": 03, "description": "O cadastro do tomador não foi executado." } ] } ]Solicita de transferência da nomeação
Efetua uma solicitação de transferência da nomeação do tomador para a corretora.
Requisição (Request)
| Url | https://api-sandbox.pottencial.com.br/onboarding/v1/policy-holders/{policyHolderDocumentNumber}/nominations | |
| Method | Post | |
| Path | policyHolderDocumentNumber | CPF ou CNPJ do tomador, sem formatação (apenas números). |
| Headers | client_id | Client ID da App. |
| access_token | Token de acesso gerado para a App. |
|
| Body | PolicyHolderNominationRequest | |
Exemplos
Exemplo solicitação de cadastro de nomeação
Resposta da solicitação de cadastro de nomeação.
{
"brokerDocumentNumber": "33651172000184",
"products": [
"judicial-deposito-recursal",
"judicial-deposito-recursal-substituicao"
],
"requester": {
"name": "Nome do Solicitante",
"email": "E-mail do Solicitante"
},
"attachment": {
"name": "Nome do arquivo",
"content": "BASE64ENCODEDSTRING"
}
}
Respostas (Response)
| Status | Descrição | Tipo |
| 202 | A solicitação de nomeação do tomador foi recebida pela Pottencial, mas ainda não foi processada. |
PolicyHolderResponse |
| 400 | Os dados da requisição estão inválidos. |
ErrorResult |
| 400 | O campo {field} é obrigatório e deve ser informado. |
ErrorResult |
| 400 | O campo {field} está com um valor inválido. |
ErrorResult |
| 401 | Parceiro não autorizado a realizar a operação. |
ErrorResult |
| 403 | Parceiro não autorizado a realizar a operação. |
ErrorResult |
| 409 | Já existe uma solicitação de transferência para o tomador e corretora informadas em andamento. |
ErrorResult |
| 429 | Quantidade de requisições excede o limite permitido para o período. |
ErrorResult |
| 500 | Oops! Tivemos um problema. Aguarde alguns minutos e tente novamente. Se o erro persistir entre em contato conosco através de nosso canal de atendimento a APIs pelo e-mail: [email protected] |
ErrorResult |
Exemplo
{
"requestId": "123e4567-e89b-12d3-a456-426614174000",
"status": "InProgress"
}
Consultar nomeação para a corretora
Obtém o status de uma solicitação de transferência de nomeação para a corretora.
Requisição (Request)
| Url | https://api-sandbox.pottencial.com.br/onboarding/v1/policy-holders/{policyHolderDocumentNumber}/nominations | |
| Method | Get | |
| Path | policyHolderDocumentNumber | CPF ou CNPJ do tomador, sem formatação (apenas números). |
| Query | requestId | Identificador único da solicitação de cadastro. |
| Headers | client_id | Client ID da App. |
| access_token | Token de acesso gerado para a App. |
|
Respostas (Response)
| Status | Descrição | Tipo |
| 200 | Obtém o status de uma solicitação de transferência de nomeação para a corretora. |
PolicyHolderNominationResponse |
| 400 | Os dados da requisição estão inválidos. |
ErrorResult |
| 401 | Parceiro não autorizado a realizar a operação. |
ErrorResult |
| 403 | Parceiro não autorizado a realizar a operação. |
ErrorResult |
| 429 | Quantidade de requisições excede o limite permitido para o período. |
ErrorResult |
| 500 | Oops! Tivemos um problema. Aguarde alguns minutos e tente novamente. Se o erro persistir entre em contato conosco através de nosso canal de atendimento a APIs pelo e-mail: [email protected] |
ErrorResult |
Exemplo
[
{
"requestId": "123e4567-e89b-12d3-a456-426614174001",
"status": "Completed"
}
]
Exemplo de Erro
[
{
"requestId": "123e4567-e89b-12d3-a456-426614174000",
"status": "Rejected",
"remarks": [
{
"code": 04,
"description": "A solicitação de transferência da nomeação para o tomador não foi acatada."
},
{
"code": 05,
"description": "A solicitação de transferência da nomeação para o tomador não é necessária, devido aos produtos que foram solicitados não necessitar de nomeação."
}
]
}
]
Dicionário
PolicyHolderRequest
Contém informações do tomador para liberação de um limite e uma taxa
| Campo | Tipo | Regras | Descrição |
| brokerDocumentNumber | string | Obrigatório | CPF ou CNPJ do corretor, sem formatação (apenas números) |
| policyHolderDocumentNumber | string | Obrigatório | CPF ou CNPJ do tomador, sem formatação (apenas números). |
PolicyHolderResponse
Contém Identificador único da solicitação de cadastro
| Campo | Tipo | Regras | Descrição |
| requestId | string (uuid) | Obrigatório | Identificador único da solicitação de cadastro |
| status | string | Obrigatório | status do processamento do cadastro InProgressO cadastro do tomador encontra-se na fila para ser executado. CompletedO cadastro do tomador foi efetivado com sucesso. RejectedO cadastro do tomador não foi efetivado com sucesso. |
StatusRegister
Status atual da solicitação de cadastro.
- InProgress: O cadastro do tomador encontra-se na fila para ser executado.
- Completed: O cadastro do tomador foi efetivado com sucesso
- Rejected: O cadastro do tomador não foi efetivado com sucesso.
PolicyHolderRequestResponse
Contém Identificador único da solicitação de cadastro
| Campo | Tipo | Regras | Descrição |
| requestId | string (uuid) | Obrigatório | Identificador único da solicitação de cadastro |
| status | string | Obrigatório | status do processamento do cadastro InProgressO cadastro do tomador encontra-se na fila para ser executado. CompletedO cadastro do tomador foi efetivado com sucesso. RejectedO cadastro do tomador não foi efetivado com sucesso. |
| policyHolderDocumentNumber | string | Obrigatório | CPF ou CNPJ do tomador, sem formatação (apenas números). |
| remarks | array de Remarks | Obrigatório | status do processamento do cadastro |
Remarks
Contém informações de um erro.
| Campo | Tipo | Regras | Descrição |
| code | string | Obrigatório | Código de identificação do erro. |
| description | string | Obrigatório | Descrição do erro. |
PolicyHolderNominationRequest
Contém informações do tomador para nomeação
| Campo | Tipo | Regras | Descrição |
| brokerDocumentNumber | string | Obrigatório | CPF ou CNPJ do corretor, sem formatação (apenas números) |
| products | array (string) | Obrigatório | Lista de produtos que serão transferidas a nomeação do tomador para a corretora. |
| requester | object Requester | Obrigatório | Dados do solicitante |
| attachment | object Attachment | Obrigatório | Documento anexo (carta de nomeação) |
Requester
Dados do Solicitante
| Campo | Tipo | Regras | Descrição |
| name | string | Obrigatório | Nome do solicitante |
| string | Obrigatório | Email do solicitante |
Attachment
Documento anexo
| Campo | Tipo | Regras | Descrição |
| name | string | Obrigatório | Nome do arquivo |
| content | string (base64) | Obrigatório | Conteúdo do arquivo em base64 |
PolicyHolderNominationResponse
Contém Identificador único da solicitação de nomeação
| Campo | Tipo | Regras | Descrição |
| requestId | string (uuid) | Obrigatório | Identificador único da solicitação de cadastro |
| status | string | Obrigatório | status do processamento do cadastro InProgressO cadastro do tomador encontra-se na fila para ser executado. CompletedO cadastro do tomador foi efetivado com sucesso. RejectedO cadastro do tomador não foi efetivado com sucesso. |
| remarks | array de Remarks | Obrigatório | status do processamento de nomeação |
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. |
Informações adicionais
Nomeação
é um processo do mercado de seguros no qual o cliente nomeia uma corretora, habilitando-a a negociar determinados produtos oferecidos pela seguradora.A carta de nomeação
é um documento assinado pelo tomador autorizando a corretora à ter acesso informações com referências às apólices, endossos, taxas bem como quaisquer outras informações necessárias. A natureza da assinatura da carta pode ser de duas maneiras: • Assinatura digital • Assinatura física importantes a considerar na carta: • Se está direcionada ao Mercado Segurador, Ao Cadastro ou a Pottencial; • Data de validade da carta; • Dados do tomador e dados da corretora • Validar se o signatário tem poderes para assinar • Qual tipo de produtos serão nomeados • As assinaturas não podem ser coladas • A corretora que está nomeada atualmente tem a permissão de solicitar e receber o histórico de todas as cópias das apólices/endossos emitidas na Pottencial referentes às modalidades de Seguro(s)/Tomadores aos quais ela representa, independentemente se possuía nomeação na data que as apólices/endossos foram emitidas. Exemplo: A Corretora X perdeu a nomeação do Tomador Z a partir de 01/01/2023. A corretora Y (nova corretora) em 02/01/2023 ganhou a nomeação do Tomador Z, por isso ela tem poderes para solicitar e receber todas as cópias das apólices/endossos emitidas na Pottencial referentes às modalidades de Seguro(s) aos quais ela representa para o Tomador Z. • A corretora que perdeu a nomeação de um tomador tem a permissão de solicitar e receber as cópias das apólices/endossos deste tomador referentes às modalidades de Seguro(s) aos quais ela representou no período em que possuía a nomeação. Exemplo: A Corretora X possuía nomeação no período de 10/01/2023 a 20/07/2023. Podem ser enviadas para esta corretora todas as cópias de apólices/endossos referentes ao Tomador e modalidades de Seguro(s) aos quais ela representou nesse período.Quando uma nomeação for acatada, o corretor já pode realizar cotações utilizando o tomador através das APIs. Caso tenha alguma dúvida durante o processo entre em contato com seu Gerente Comercial/Consultor Comercial. Atenção: A nomeação precisa ser assinada por uma pessoa que tenha poderes para representar a empresa. • Para acatarmos a assinatura digital é necessário encaminhar o link e a chave de acesso para conferência • Para assinatura de próprio punho gentileza encaminhar RG
Termos/Glossário • Carta de nomeação: documento assinado que dá poderes a uma corretora a intermediar contratos de seguros com seguradoras em nome de seus tomadores • Tomador: Devedor das obrigações por ele assumidas no contrato principal. • Corretora: É 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. • Apólice: É o contrato do seguro, onde os riscos de prejuízo de um objeto são repassados à seguradora, por um preço. A apólice contém as cláusulas e condições gerais, além das coberturas específicas a cada produto. Nela constam quem é o estipulante, o segurado, o beneficiário, a seguradora, dentre outros dados identificadores. • Endosso: Documento que altera a apólice principal.
