ℹ️ Conteúdo em atualização

Estamos revisando estes procedimentos. Pessoas técnicas podem encontrar ajustes em códigos de erro ou mapeamentos de payload; valide com os logs e o OpenAPI mais recente. Pessoas não técnicas podem continuar usando o passo a passo e acionar o time de suporte caso algo pareça diferente do descrito.

🛡️ Venda de Produtos Financeiros

Guia completo para oferecer, contratar e gerenciar produtos financeiros como seguros e proteções aos seus clientes.

📋 Introdução

Este serviço permite que você ofereça produtos financeiros adicionais (como seguros) aos clientes de forma integrada, com funcionalidades de:

🛡️ Consulta de produtos disponíveis
✅ Adesão/contratação de produtos
📋 Consulta de produtos contratados
❌ Cancelamento de produtos
🔐 Geração de tokens transacionais
📄 Detalhamento completo de produtos

URLs Base:

Homologação: https://apihml.credsystem.com.br/venda-app/api/v1
Produção: https://api.credsystem.com.br/venda-app/api/v1

📚 Recursos Adicionais

🔧 Guia de Troubleshooting - Solução de problemas e erros comuns
📖 Especificação OpenAPI — Referência técnica completa (schemas, tipos, exemplos)

🔐 Autenticação

Esta API utiliza Red Hat SSO (Keycloak) com o fluxo Password Grant (usuário e senha).

Todos os endpoints requerem autenticação via Bearer Token (JWT) no header:

Authorization: Bearer <seu_access_token>

Propriedade	Valor
Sistema	Red Hat SSO (Keycloak)
Fluxo OAuth2	Password Grant
Tipo	Autenticação com usuário final (CPF + senha)
Tokens	Access Token + Refresh Token

Atenção

Tokens inválidos ou expirados retornarão erro 401 Unauthorized.

🔑 Como obter o token?

O token é gerado no fluxo de Login dos APPs. O access_token retornado deve ser enviado em todas as chamadas da área logada.

🔄 Fluxo de Contratação

Passo 1: Gerar Token Transacional

Antes de realizar operações sensíveis, gere um token transacional válido.

Endpoint: POST /token-transacional

Exemplo de Request:

POST /venda-app/api/v1/token-transacional HTTP/1.1
Host: apihml.credsystem.com.br
Authorization: Bearer <token>
Accept: application/json

Resposta de Sucesso (200):

[
  {
    "token": 102162,
    "dhexpiracao": "2025-12-04T18:50:46.511Z"
  }
]

Campos da Resposta:

token: Código do token transacional (use para operações sensíveis)
dhexpiracao: Data e hora de expiração do token

Importante

Guarde este token temporário. Ele será necessário para confirmar adesões e cancelamentos.

Problemas com este endpoint?

Consulte o 🔧 Troubleshooting - Gerar Token Transacional para detalhes de erros e soluções.

Passo 2: Consultar Produtos Disponíveis

Veja quais produtos financeiros estão disponíveis para o cliente.

Endpoint: GET /produtos-financeiros/oferta

Exemplo de Request:

GET /venda-app/api/v1/produtos-financeiros/oferta HTTP/1.1
Host: apihml.credsystem.com.br
Authorization: Bearer <token>
Accept: application/json

Resposta de Sucesso (200):

{
  "codigo": 15,
  "codigoTipo": 1,
  "descricaoTipo": "Seguro Cartão Protegido",
  "nome": "Proteção Plus",
  "descricao": "Seguro completo para seu cartão de crédito com cobertura contra roubo, fraude e acidentes",
  "valor": 19.90
}

Campos da Resposta:

codigo: Código único do produto
codigoTipo: Código do tipo de produto
descricaoTipo: Categoria do produto
nome: Nome comercial do produto
descricao: Descrição detalhada dos benefícios
valor: Valor mensal do produto

Dica

Use o campo descricao para exibir os benefícios ao cliente de forma clara.

Problemas com este endpoint?

Consulte o 🔧 Troubleshooting - Consultar Ofertas para detalhes de erros e soluções.

Passo 3: Consultar Detalhes do Produto

Antes de contratar, mostre todos os detalhes do produto ao cliente.

Endpoint: GET /produtos-financeiros/detalhes/{codigoProduto}

Exemplo:

GET /venda-app/api/v1/produtos-financeiros/detalhes/15 HTTP/1.1
Host: apihml.credsystem.com.br
Authorization: Bearer <token>
Accept: application/json

Resposta de Sucesso (200):

{
  "CodigoProduto": 15,
  "NomeProduto": "Proteção Plus",
  "DescricaoProduto": "Seguro completo para seu cartão de crédito",
  "CodigoTipoProduto": 1,
  "NomeTipoProduto": "Seguro Cartão",
  "Seguradora": {
    "Nome": "Seguradora XYZ",
    "CodigoSeguradora": 123,
    "RazaoSocial": "Seguradora XYZ S.A.",
    "Cnpj": "12.345.678/0001-90",
    "Endereco": "Rua Exemplo, 1000 - São Paulo, SP",
    "TipoOperacao": "Seguro",
    "Root_GD": {}
  },
  "RedeCredenciada": {
    "Root_GD": {}
  },
  "Coberturas": {
    "Root_GD": {}
  },
  "Valor": 19.90,
  "FormaPagamento": "Débito em fatura"
}

Informações Retornadas:

Dados do produto (código, nome, descrição)
Informações da seguradora (nome, CNPJ, endereço)
Rede credenciada
Coberturas incluídas

Transparência

Exiba as informações da seguradora e coberturas para garantir clareza ao cliente.

Problemas com este endpoint?

Consulte o 🔧 Troubleshooting - Detalhes do Produto para detalhes de erros e soluções.

Passo 4: Realizar Adesão

Após o cliente aceitar os termos, realize a adesão ao produto.

Endpoint: POST /produtos-financeiros/adesao

Body:

{
  "Codigo": 15,
  "Tipo": 1
}

Campos do Request:

Codigo: Código do produto (obtido no passo 2)
Tipo: Código do tipo de produto (obtido no passo 2)

Resposta de Sucesso (200):

{
  "codigoAdesao": "c4682a1d-2e74-49b5-9944-59737dd0b892"
}

Campo da Resposta:

codigoAdesao: Identificador único da adesão (GUID)

Adesão Confirmada!

Guarde o codigoAdesao - você precisará dele para consultas e cancelamentos futuros.

Exemplo de cURL:

curl -X 'POST' \
  'https://apihml.credsystem.com.br/venda-app/api/v1/produtos-financeiros/adesao' \
  -H 'accept: application/json' \
  -H 'Authorization: Bearer SEU_TOKEN' \
  -H 'Content-Type: application/json' \
  -d '{
    "Codigo": 15,
    "Tipo": 1
  }'

Problemas com este endpoint?

Consulte o 🔧 Troubleshooting - Aderir Produto para detalhes de erros e soluções.

Gerenciamento de Produtos

Consultar Produtos Contratados

Liste todos os produtos financeiros que o cliente possui.

Endpoint: GET /produtos-financeiros/contratados

Exemplo de Request:

GET /venda-app/api/v1/produtos-financeiros/contratados HTTP/1.1
Host: apihml.credsystem.com.br
Authorization: Bearer <token>
Accept: application/json

Resposta de Sucesso (200):

{
  "codigoTipo": 1,
  "descricaoTipo": "Seguro Cartão Protegido",
  "bin": 960333,
  "codigoAdesao": "c4682a1d-2e74-49b5-9944-59737dd0b892",
  "codigoContratoSeguradora": "CTR-2024-12345",
  "codigoProdutoSeguradora": "PROD-SEG-001",
  "nome": "Proteção Plus",
  "vigencia": "12 meses",
  "dataAdesao": "2024-11-15T10:30:00.000Z",
  "dataSolicitacao": "2024-11-15T10:25:00.000Z",
  "dataCancelamento": null,
  "motivoCancelamento": null,
  "status": "ATIVO",
  "codigo": 15
}

Campos da Resposta:

codigoTipo: Tipo do produto
descricaoTipo: Descrição do tipo
bin: BIN do cartão vinculado
codigoAdesao: ID único da adesão
codigoContratoSeguradora: Número do contrato na seguradora
codigoProdutoSeguradora: Código do produto na seguradora
nome: Nome do produto contratado
vigencia: Período de vigência do contrato
dataAdesao: Data em que a adesão foi efetivada
dataSolicitacao: Data em que foi solicitada
dataCancelamento: Data de cancelamento (se aplicável)
motivoCancelamento: Motivo do cancelamento (se aplicável)
status: Status atual do produto

Status Possíveis:

ATIVO: Produto ativo e vigente
PENDENTE: Aguardando aprovação
CANCELADO: Produto cancelado
SUSPENSO: Temporariamente suspenso
EXPIRADO: Vigência expirada

Gestão

Use este endpoint para exibir um painel com todos os produtos que o cliente possui.

Problemas com este endpoint?

Consulte o 🔧 Troubleshooting - Consultar Contratados para detalhes de erros e soluções.

Consultar Motivos de Cancelamento

Lista os motivos de cancelamento disponíveis para uso no cancelamento de produtos.

Endpoint: GET /produtos-financeiros/motivo-cancelamento

Exemplo de Request:

GET /venda-app/api/v1/produtos-financeiros/motivo-cancelamento HTTP/1.1
Host: apihml.credsystem.com.br
Authorization: Bearer <token>
Accept: application/json

Resposta de Sucesso (200):

[
  {
    "codigoMotivoCancelamento": 1,
    "descricaoMotivoCancelamento": "Não preciso mais do serviço"
  },
  {
    "codigoMotivoCancelamento": 2,
    "descricaoMotivoCancelamento": "Valor muito alto"
  },
  {
    "codigoMotivoCancelamento": 3,
    "descricaoMotivoCancelamento": "Contratei outro produto similar"
  }
]

Campos da Resposta:

codigoMotivoCancelamento: Código identificador do motivo
descricaoMotivoCancelamento: Descrição legível do motivo

Uso

Utilize os motivos retornados para preencher uma lista de seleção na interface do cliente antes de confirmar o cancelamento.

Problemas com este endpoint?

Consulte o 🔧 Troubleshooting - Motivos de Cancelamento para detalhes de erros e soluções.

Consultar Termo de Adesão

Recupera o termo de adesão (PDF e/ou texto) de um produto já contratado.

Endpoint: GET /produtos-financeiros/termo/adesao/{codigoAdesao}

Parâmetros:

codigoAdesao (path, obrigatório): Identificador da adesão (GUID)

Exemplo:

GET /venda-app/api/v1/produtos-financeiros/termo/adesao/c4682a1d-2e74-49b5-9944-59737dd0b892 HTTP/1.1
Host: apihml.credsystem.com.br
Authorization: Bearer <token>
Accept: application/json

Resposta de Sucesso (200):

{
  "TermoPDF": "JVBERi0xLjQKJeLjz9M...",
  "Termo40c": "Termo e condições gerais do produto financeiro..."
}

Campos da Resposta:

TermoPDF: Documento do termo em formato PDF codificado em Base64
Termo40c: Texto do termo em formato legível (até 40 colunas)

Como usar

Converta o TermoPDF de Base64 para PDF para exibir ou fazer download. O campo Termo40c pode ser usado para exibição em texto puro.

Problemas com este endpoint?

Consulte o 🔧 Troubleshooting - Consultar Termo de Adesão para detalhes de erros e soluções.

Criar Pré-Adesão

Cria uma pré-adesão a um produto financeiro, gerando o termo para aceite do cliente.

Endpoint: POST /produtos-financeiros/termo/pre-adesao

Body:

{
  "Bin": 960333,
  "CodigoProduto": 15,
  "Canal": 1,
  "Parametros": [
    {
      "Chave": "TIPO_PRODUTO",
      "Valor": "SEGURO"
    }
  ]
}

Campos do Request:

Bin: Número BIN do cartão do cliente
CodigoProduto: Código do produto financeiro (obtido na consulta de ofertas)
Canal: Código do canal de venda/atendimento
Parametros: Lista de parâmetros adicionais (chave-valor)

Resposta de Sucesso (200):

{
  "TermoPDF": "JVBERi0xLjQKJeLjz9M...",
  "Termo40c": "Termo e condições gerais do produto financeiro..."
}

Campos da Resposta:

TermoPDF: Documento do termo em formato PDF codificado em Base64
Termo40c: Texto do termo em formato legível

Fluxo de Pré-Adesão

Consulte ofertas disponíveis
Crie a pré-adesão com este endpoint
Exiba o termo ao cliente
Após aceite, efetive com POST /produtos-financeiros/adesao

Exemplo de cURL:

curl -X 'POST' \
  'https://apihml.credsystem.com.br/venda-app/api/v1/produtos-financeiros/termo/pre-adesao' \
  -H 'accept: application/json' \
  -H 'Authorization: Bearer SEU_TOKEN' \
  -H 'Content-Type: application/json' \
  -d '{
    "Bin": 960333,
    "CodigoProduto": 15,
    "Canal": 1,
    "Parametros": [{"Chave": "TIPO_PRODUTO", "Valor": "SEGURO"}]
  }'

Problemas com este endpoint?

Consulte o 🔧 Troubleshooting - Criar Pré-Adesão para detalhes de erros e soluções.

Cancelamento de Produtos

Cancelar Adesão

Cancele um produto financeiro contratado.

Endpoint: PATCH /produtos-financeiros/cancelamento

Body:

{
  "codigoAdesao": "c4682a1d-2e74-49b5-9944-59737dd0b892",
  "motivoCancelamento": "Não preciso mais do serviço",
  "tipo": 1
}

Campos do Request:

codigoAdesao: ID da adesão a ser cancelada
motivoCancelamento: Motivo informado pelo cliente
tipo: Tipo do produto

Resposta de Sucesso (200):

Corpo vazio (sem conteúdo)

Atenção

O cancelamento é irreversível. Uma nova adesão precisará ser feita caso o cliente queira contratar novamente.

Exemplo de cURL:

curl -X 'PATCH' \
  'https://apihml.credsystem.com.br/venda-app/api/v1/produtos-financeiros/cancelamento' \
  -H 'accept: application/json' \
  -H 'Authorization: Bearer SEU_TOKEN' \
  -H 'Content-Type: application/json' \
  -d '{
    "codigoAdesao": "c4682a1d-2e74-49b5-9944-59737dd0b892",
    "motivoCancelamento": "Não preciso mais do serviço",
    "tipo": 1
  }'

Problemas com este endpoint?

Consulte o 🔧 Troubleshooting - Cancelar Adesão para detalhes de erros e soluções.

Códigos de Resposta

Código	Status	Descrição
200	✅ Sucesso	Requisição processada com sucesso
204	∅ Sem conteúdo	Sem dados para retornar
400	⚠️ Bad Request	Parâmetros inválidos na requisição
401	⛔ Unauthorized	Token inválido ou expirado
500	💥 Internal Error	Erro interno do servidor

Tratamento de Erros

{
  "error": {
    "message": "Descrição do erro",
    "code": 400
  }
}

Fluxo Completo Resumido

1. Gerar Token Transacional
   ↓
2. Consultar Produtos Disponíveis (Ofertas)
   ↓
3. Exibir Produtos ao Cliente
   ↓
4. Cliente seleciona um produto
   ↓
5. Consultar Detalhes do Produto
   ↓
6. Criar Pré-Adesão (gerar termo)
   ↓
7. Exibir termo ao cliente
   ↓
8. Cliente aceita os termos
   ↓
9. Realizar Adesão
   ↓
10. Produto Contratado! ✅

Fluxo de Cancelamento

1. Consultar Produtos Contratados
   ↓
2. Exibir lista de produtos ativos
   ↓
3. Cliente seleciona produto para cancelar
   ↓
4. Consultar Motivos de Cancelamento
   ↓
5. Cliente seleciona motivo e confirma
   ↓
6. Executar Cancelamento
   ↓
7. Produto Cancelado

Boas Práticas

1. Validação e Confirmação

Sempre exiba os detalhes completos antes da adesão
Peça confirmação dupla para adesão e cancelamento
Mostre claramente o valor mensal e forma de cobrança
Exiba as informações da seguradora de forma transparente

2. Gestão de Tokens

Gere um novo token transacional quando necessário
Verifique sempre a data de expiração
Não reutilize tokens expirados
Armazene tokens de forma segura (nunca em logs)

3. UX/Interface

Use ícones e cards visuais para exibir produtos
Destaque os benefícios de cada produto
Mostre o status dos produtos (ATIVO, CANCELADO)
Agrupe produtos por categoria/tipo
Exiba claramente a data de adesão e vigência

4. Performance

Cache a lista de ofertas por período curto (ex: 1 hora)
Atualize produtos contratados após adesão/cancelamento
Implemente retry com backoff em caso de erro 500

5. Segurança

Valide sempre o token JWT antes de operações
Nunca exponha dados sensíveis em logs
Use HTTPS em todas as requisições
Valide o codigoAdesao antes de cancelamentos

6. Tratamento de Erros

Trate casos de 204 (sem produtos disponíveis)
Exiba mensagens amigáveis ao cliente
Implemente fallback para erros 500
Registre erros para monitoramento

Exemplos de Uso

Exemplo 1: Fluxo Completo de Adesão

# Passo 1: Gerar token transacional
curl -X 'POST' \
  'https://apihml.credsystem.com.br/venda-app/api/v1/token-transacional' \
  -H 'Authorization: Bearer TOKEN'

# Passo 2: Consultar ofertas
curl -X 'GET' \
  'https://apihml.credsystem.com.br/venda-app/api/v1/produtos-financeiros/oferta' \
  -H 'Authorization: Bearer TOKEN'

# Passo 3: Ver detalhes do produto código 15
curl -X 'GET' \
  'https://apihml.credsystem.com.br/venda-app/api/v1/produtos-financeiros/detalhes/15' \
  -H 'Authorization: Bearer TOKEN'

# Passo 4: Realizar adesão
curl -X 'POST' \
  'https://apihml.credsystem.com.br/venda-app/api/v1/produtos-financeiros/adesao' \
  -H 'Authorization: Bearer TOKEN' \
  -H 'Content-Type: application/json' \
  -d '{"Codigo": 15, "Tipo": 1}'

Exemplo 2: Verificar Produtos Ativos

# Listar todos os produtos contratados
curl -X 'GET' \
  'https://apihml.credsystem.com.br/venda-app/api/v1/produtos-financeiros/contratados' \
  -H 'Authorization: Bearer TOKEN'

# Filtrar apenas produtos com status = "ATIVO" na aplicação

Exemplo 3: Cancelar Produto

# Cancelar adesão específica
curl -X 'PATCH' \
  'https://apihml.credsystem.com.br/venda-app/api/v1/produtos-financeiros/cancelamento' \
  -H 'Authorization: Bearer TOKEN' \
  -H 'Content-Type: application/json' \
  -d '{
    "codigoAdesao": "c4682a1d-2e74-49b5-9944-59737dd0b892",
    "motivoCancelamento": "Cliente não deseja mais o serviço",
    "tipo": 1
  }'

Casos de Uso Comuns

1. Upsell no Onboarding

Quando um novo cliente recebe o cartão, ofereça produtos de proteção:

Cliente ativa o cartão
Consultar ofertas disponíveis
Exibir benefícios de forma atrativa
Facilitar adesão com 1 clique

2. Cross-sell em Transações

Após uma compra grande, ofereça seguro de compras:

Cliente faz compra de alto valor
Exibir oferta de seguro de compras
Destacar cobertura para aquela transação
Permitir adesão rápida

3. Gestão de Produtos Ativos

Área do cliente para gerenciar seguros:

Exibir todos os produtos contratados
Mostrar status, vigência e valor
Permitir visualização de detalhes
Facilitar cancelamento quando necessário

Glossário

Termo	Significado
Adesão	Processo de contratação de um produto financeiro
BIN	Bank Identification Number (primeiros dígitos do cartão)
Cobertura	Riscos e situações cobertas pelo seguro
Vigência	Período em que o produto está ativo/válido
Token Transacional	Token temporário para operações sensíveis
Seguradora	Empresa responsável pelo produto de seguro
Rede Credenciada	Estabelecimentos/serviços cobertos pelo produto

Integração com Outros Serviços

Cartão

Vincule produtos ao BIN do cartão
Exiba proteções ativas no detalhamento do cartão

Fatura

Mostre o valor do seguro nas transações da fatura
Facilite identificação dos débitos mensais

Empréstimo Pessoal

Ofereça seguro prestamista durante contratação
Inclua proteção no fluxo de efetivação

Dicas de Implementação

Início Rápido: Comece com GET /produtos-financeiros/oferta para listar produtos
Detalhamento: Use /detalhes/{codigo} para exibir informações completas
Adesão: Implemente fluxo com confirmação dupla
Gestão: Crie painel com /contratados mostrando status visual
Cancelamento: Peça sempre motivo e registre para análise

🎓 Recursos Adicionais

🔧 Guia de Troubleshooting — Solução de problemas e erros comuns
📄 Referência OpenAPI — Especificação técnica completa

Suporte

Para dúvidas ou problemas com a integração, entre em contato com a equipe de suporte técnico.

📋 Introdução​

🔐 Autenticação​

🔄 Fluxo de Contratação​

Passo 1: Gerar Token Transacional​

Passo 2: Consultar Produtos Disponíveis​

Passo 3: Consultar Detalhes do Produto​

Passo 4: Realizar Adesão​

Gerenciamento de Produtos​

Consultar Produtos Contratados​

Consultar Motivos de Cancelamento​

Consultar Termo de Adesão​

Criar Pré-Adesão​

Cancelamento de Produtos​

Cancelar Adesão​

Códigos de Resposta​

Tratamento de Erros​

Fluxo Completo Resumido​

Fluxo de Cancelamento​

Boas Práticas​

1. Validação e Confirmação​

2. Gestão de Tokens​

3. UX/Interface​

4. Performance​

5. Segurança​

6. Tratamento de Erros​

Exemplos de Uso​

Exemplo 1: Fluxo Completo de Adesão​

Exemplo 2: Verificar Produtos Ativos​

Exemplo 3: Cancelar Produto​

Casos de Uso Comuns​

1. Upsell no Onboarding​

2. Cross-sell em Transações​

3. Gestão de Produtos Ativos​

Glossário​

Integração com Outros Serviços​

Cartão​

Fatura​

Empréstimo Pessoal​

Dicas de Implementação​

🎓 Recursos Adicionais​

Suporte​

📋 Introdução

🔐 Autenticação

🔄 Fluxo de Contratação

Passo 1: Gerar Token Transacional

Passo 2: Consultar Produtos Disponíveis

Passo 3: Consultar Detalhes do Produto

Passo 4: Realizar Adesão

Gerenciamento de Produtos

Consultar Produtos Contratados

Consultar Motivos de Cancelamento

Consultar Termo de Adesão

Criar Pré-Adesão

Cancelamento de Produtos

Cancelar Adesão

Códigos de Resposta

Tratamento de Erros

Fluxo Completo Resumido

Fluxo de Cancelamento

Boas Práticas

1. Validação e Confirmação

2. Gestão de Tokens

3. UX/Interface

4. Performance

5. Segurança

6. Tratamento de Erros

Exemplos de Uso

Exemplo 1: Fluxo Completo de Adesão

Exemplo 2: Verificar Produtos Ativos

Exemplo 3: Cancelar Produto

Casos de Uso Comuns

1. Upsell no Onboarding

2. Cross-sell em Transações

3. Gestão de Produtos Ativos

Glossário

Integração com Outros Serviços

Cartão

Fatura

Empréstimo Pessoal

Dicas de Implementação

🎓 Recursos Adicionais

Suporte