ℹ️ 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:

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

Autenticação

Todas as requisições precisam incluir o token de autenticação no header:

Authorization: Bearer <seu_token_jwt>

Atenção

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

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.

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.

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": {}
  }
}

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.

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
  }'

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.

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
  }'

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. Exibir informações completas (seguradora, coberturas, valor)
   ↓
7. Cliente aceita os termos
   ↓
8. Realizar Adesão
   ↓
9. Produto Contratado! ✅

Fluxo de Cancelamento

1. Consultar Produtos Contratados
   ↓
2. Exibir lista de produtos ativos
   ↓
3. Cliente seleciona produto para cancelar
   ↓
4. Solicitar confirmação e motivo
   ↓
5. Executar Cancelamento
   ↓
6. 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

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​

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​

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

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

Suporte